doc/man-pages/pod8/backup_dumpinfo.pod

   1 =head1 NAME
   2
   3 backup dumpinfo - Displays a dump record from the Backup Database
   4
   5 =head1 SYNOPSIS
   6
   7 B<backup dumpinfo> [B<-ndumps> <I<number of dumps>>] [B<-id> <I<dump id>>]
   8     [B<-verbose>] [B<-localauth>] [B<-cell> <I<cell name>>] [B<-help>]
   9
  10 B<backup dumpi> [B<-n> <I<no. of dumps>>] [-i <I<dump id>>] [B<-v>]
  11     [B<-l>] [B<-c> <I<cell name>>] [B<-h>]
  12
  13 =head1 DESCRIPTION
  14
  15 The B<backup dumpinfo> command formats and displays the Backup Database
  16 record for the specified dumps. To specify how many of the most recent
  17 dumps to display, starting with the newest one and going back in time, use
  18 the B<-ndumps> argument. To display more detailed information about a
  19 single dump, use the B<-id> argument. To display the records for the 10
  20 most recent dumps, omit both the B<-ndumps> and B<-id> arguments.
  21
  22 The B<-verbose> flag produces very detailed information that is useful
  23 mostly for debugging purposes. It can be combined only with the B<-id>
  24 argument.
  25
  26 =head1 OPTIONS
  27
  28 =over 4
  29
  30 =item B<-ndumps> <I<number of dumps>>
  31
  32 Displays the Backup Database record for each of the specified number of
  33 dumps that were most recently performed. If the database contains fewer
  34 dumps than are requested, the output includes the records for all existing
  35 dumps. Do not combine this argument with the B<-id> or B<-verbose>
  36 options; omit all options to display the records for the last 10 dumps.
  37
  38 =item B<-id> <I<dump id>>
  39
  40 Specifies the dump ID number of a single dump for which to display the
  41 Backup Database record. Precede the I<dump id> value with the B<-id>
  42 switch; otherwise, the command interpreter interprets it as the value of
  43 the B<-ndumps> argument. Combine this argument with the B<-verbose> flag,
  44 but not with the B<-ndumps> argument; omit all options to display the
  45 records for the last 10 dumps.
  46
  47 =item B<-verbose>
  48
  49 Provides more detailed information about the dump specified with the
  50 B<-id> argument, which must be provided along with it. Do not combine this
  51 flag with the B<-ndumps> argument.
  52
  53 =item B<-localauth>
  54
  55 Constructs a server ticket using a key from the local
  56 F</usr/afs/etc/KeyFile> file. The B<backup> command interpreter presents
  57 it to the Backup Server, Volume Server and VL Server during mutual
  58 authentication. Do not combine this flag with the B<-cell> argument. For
  59 more details, see L<backup(8)>.
  60
  61 =item B<-cell> <I<cell name>>
  62
  63 Names the cell in which to run the command. Do not combine this argument
  64 with the B<-localauth> flag. For more details, see L<backup(8)>.
  65
  66 =item B<-help>
  67
  68 Prints the online help for this command. All other valid options are
  69 ignored.
  70
  71 =back
  72
  73 =head1 OUTPUT
  74
  75 If the B<-ndumps> argument is provided, the output presents the following
  76 information in table form, with a separate line for each dump:
  77
  78 =over 4
  79
  80 =item dumpid
  81
  82 The dump ID number.
  83
  84 =item parentid
  85
  86 The dump ID number of the dump's parent dump. A value of C<0> (zero)
  87 identifies a full dump.
  88
  89 =item lv
  90
  91 The depth in the dump hierarchy of the dump level used to create the
  92 dump. A value of C<0> (zero) identifies a full dump, in which case the
  93 value in the C<parentid> field is also C<0>. A value of C<1> or greater
  94 indicates an incremental dump made at the corresponding level in the dump
  95 hierarchy.
  96
  97 =item created
  98
  99 The date and time at which the Backup System started the dump operation
 100 that created the dump.
 101
 102 =item nt
 103
 104 The number of tapes that contain the data in the dump. A value of C<0>
 105 (zero) indicates that the dump operation was terminated or failed. Use the
 106 B<backup deletedump> command to remove such entries.
 107
 108 =item nvols
 109
 110 The number of volumes from which the dump includes data. If a volume spans
 111 tapes, it is counted twice. A value of C<0> (zero) indicates that the dump
 112 operation was terminated or failed; the value in the C<nt> field is also
 113 C<0> in this case.
 114
 115 =item dump name
 116
 117 The dump name in the form
 118
 119    <volume_set_name>.<dump_level_name> (<initial_dump_ID>)
 120
 121 where <volume_set_name> is the name of the volume set, and
 122 <dump_level_name> is the last element in the dump level pathname at which
 123 the volume set was dumped.
 124
 125 The <initial_dump_ID>, if displayed, is the dump ID of the initial dump in
 126 the dump set to which this dump belongs. If there is no value in
 127 parentheses, the dump is the initial dump in a dump set that has no
 128 appended dumps.
 129
 130 =back
 131
 132 If the B<-id> argument is provided alone, the first line of output begins
 133 with the string C<Dump> and reports information for the entire dump in the
 134 following fields:
 135
 136 =over 4
 137
 138 =item id
 139
 140 The dump ID number.
 141
 142 =item level
 143
 144 The depth in the dump hierarchy of the dump level used to create the
 145 dump. A value of C<0> (zero) identifies a full dump. A value of C<1> (one)
 146 or greater indicates an incremental dump made at the specified level in
 147 the dump hierarchy.
 148
 149 =item volumes
 150
 151 The number of volumes for which the dump includes data.
 152
 153 =item created
 154
 155 The date and time at which the dump operation began.
 156
 157 =back
 158
 159 If an XBSA server was the backup medium for the dump (rather than a tape
 160 device or backup data file), the following line appears next:
 161
 162    Backup Service: <XBSA_program>: Server: <hostname>
 163
 164 where <XBSA_program> is the name of the XBSA-compliant program and
 165 <hostname> is the name of the machine on which the program runs.
 166
 167 Next the output includes an entry for each tape that houses volume data
 168 from the dump. Following the string C<Tape>, the first two lines of each
 169 entry report information about that tape in the following fields:
 170
 171 =over 4
 172
 173 =item name
 174
 175 The tape's permanent name if it has one, or its AFS tape name otherwise,
 176 and its tape ID number in parentheses.
 177
 178 =item nVolumes
 179
 180 The number of volumes for which this tape includes dump data.
 181
 182 =item created
 183
 184 The date and time at which the Tape Coordinator began writing data to this
 185 tape.
 186
 187 =back
 188
 189 Following another blank line, the tape-specific information concludes with
 190 a table that includes a line for each volume dump on the tape. The
 191 information appears in columns with the following headings:
 192
 193 =over 4
 194
 195 =item Pos
 196
 197 The relative position of each volume in this tape or file. On a tape, the
 198 counter begins at position 2 (the tape label occupies position 1), and
 199 increments by one for each volume. For volumes in a backup data file, the
 200 position numbers start with 1 and do not usually increment only by one,
 201 because each is the ordinal of the 16 KB offset in the file at which the
 202 volume's data begins. The difference between the position numbers
 203 therefore indicates how many 16 KB blocks each volume's data occupies. For
 204 example, if the second volume is at position 5 and the third volume in the
 205 list is at position 9, that means that the dump of the second volume
 206 occupies 64 KB (four 16-KB blocks) of space in the file.
 207
 208 =item Clone time
 209
 210 For a backup or read-only volume, the time at which it was cloned from its
 211 read/write source. For a Read/Write volume, it is the same as the dump
 212 creation date reported on the first line of the output.
 213
 214 =item Nbytes
 215
 216 The number of bytes of data in the dump of the volume.
 217
 218 =item Volume
 219
 220 The volume name, complete with C<.backup> or C<.readonly> extension if
 221 appropriate.
 222
 223 =back
 224
 225 If both the B<-id> and B<-verbose> options are provided, the output is
 226 divided into several sections:
 227
 228 =over 4
 229
 230 =item *
 231
 232 The first section, headed by the underlined string C<Dump>, includes
 233 information about the entire dump. The fields labeled C<id>, C<level>,
 234 C<created>, and C<nVolumes> report the same values (though in a different
 235 order) as appear on the first line of output when the B<-id> argument is
 236 provided by itself.  Other fields of potential interest to the backup
 237 operator are:
 238
 239 =over 4
 240
 241 =item Group id
 242
 243 The dump's I<group ID number>, which is recorded in the dump's Backup
 244 Database record if the C<GROUPID> instruction appears in the Tape
 245 Coordinator's F</usr/afs/backup/CFG_I<tcid>> file when the dump is
 246 created.
 247
 248 =item maxTapes
 249
 250 The number of tapes that contain the dump set to which this dump belongs.
 251
 252 =item Start Tape Seq
 253
 254 The ordinal of the tape on which this dump begins in the set of tapes that
 255 contain the dump set.
 256
 257 =back
 258
 259 =item *
 260
 261 For each tape that contains data from this dump, there follows a section
 262 headed by the underlined string C<Tape>. The fields labeled C<name>,
 263 C<written>, and C<nVolumes> report the same values (though in a different
 264 order) as appear on the second and third lines of output when the B<-id>
 265 argument is provided by itself. Other fields of potential interest to the
 266 backup operator are:
 267
 268 =over 4
 269
 270 =item expires
 271
 272 The date and time when this tape can be recycled, because all dumps it
 273 contains have expired.
 274
 275 =item nMBytes Data and nBytes Data
 276
 277 Summed together, these fields represent the total amount of dumped data
 278 actually from volumes (as opposed to labels, filemarks, and other
 279 markers).
 280
 281 =item KBytes Tape Used
 282
 283 The number of kilobytes of tape (or disk space, for a backup data file)
 284 used to store the dump data. It is generally larger than the sum of the
 285 values in the C<nMBytes Data> and C<nBytes Data> fields, because it
 286 includes the space required for the label, file marks and other markers,
 287 and because the Backup System writes data at 16 KB offsets, even if the
 288 data in a given block doesn't fill the entire 16 KB.
 289
 290 =back
 291
 292 =item *
 293
 294 For each volume on a given tape, there follows a section headed by the
 295 underlined string C<Volume>. The fields labeled C<name>, C<position>,
 296 C<clone>, and C<nBytes> report the same values (though in a different
 297 order) as appear in the table that lists the volumes in each tape when the
 298 B<-id> argument is provided by itself. Other fields of potential interest
 299 to the backup operator are:
 300
 301 =over 4
 302
 303 =item id
 304
 305 The volume ID.
 306
 307 =item tape
 308
 309 The name of the tape containing this volume data.
 310
 311 =back
 312
 313 =back
 314
 315 =head1 EXAMPLES
 316
 317 The following example displays information about the last five dumps:
 318
 319    % backup dumpinfo -ndumps 5
 320       dumpid   parentid lv created          nt nvols dump name
 321    924424000          0 0  04/18/1999 04:26  1    22 usr.sun (924424000)
 322    924685000  924424000 1  04/21/1999 04:56  1    62 usr.wed (924424000)
 323    924773000  924424000 1  04/22/1999 05:23  1    46 usr.thu (924424000)
 324    924860000  924424000 1  04/23/1999 05:33  1    58 usr.fri (924424000)
 325    925033000          0 0  04/25/1999 05:36  2    73 sys.week
 326
 327 The following example displays a more detailed record for a single dump.
 328
 329    % backup dumpinfo -id 922097346
 330    Dump: id 922097346, level 0, volumes 1, created Mon Mar 22 05:09:06 1999
 331    Tape: name monday.user.backup (922097346)
 332    nVolumes 1, created 03/22/1999 05:09
 333     Pos       Clone time   Nbytes Volume
 334       1 03/22/1999 04:43 27787914 user.pat.backup
 335
 336 The following example displays even more detailed information about the
 337 dump displayed in the previous example (dump ID 922097346). This example
 338 includes only one exemplar of each type of section (C<Dump>, C<Tape>, and
 339 C<Volume>):
 340
 341    % backup dumpinfo -id 922097346 -verbose
 342    Dump
 343    ----
 344    id = 922097346
 345    Initial id = 0
 346    Appended id = 922099568
 347    parent = 0
 348    level = 0
 349    flags = 0x0
 350    volumeSet = user
 351    dump path = /monday1
 352    name = user.monday1
 353    created = Mon Mar 22 05:09:06 1999
 354    nVolumes = 1
 355    id  = 0
 356    tapeServer =
 357    format= user.monday1.%d
 358    maxTapes = 1
 359    Start Tape Seq = 1
 360    name = pat
 361    instance =
 362    cell =
 363    Tape
 364    ----
 365    tape name = monday.user.backup
 366    AFS tape name = user.monday1.1
 367    flags = 0x20
 368    written = Mon Mar 22 05:09:06 1999
 369    expires = NEVER
 370    kBytes Tape Used = 121
 371    nMBytes Data = 0
 372    nBytes  Data = 19092
 373    nFiles = 0
 374    nVolumes = 1
 375    seq = 1
 376    tapeid = 0
 377    useCount = 1
 378    dump = 922097346
 379    Volume
 380    ------
 381    name = user.pat.backup
 382    flags = 0x18
 383    id = 536871640
 384    server =
 385    partition = 0
 386    nFrags = 1
 387    position = 2
 388    clone = Mon Mar 22 04:43:06 1999
 389    startByte = 0
 390    nBytes = 19092
 391    seq = 0
 392    dump = 922097346
 393    tape = user.monday1.1
 394
 395 =head1 PRIVILEGE REQUIRED
 396
 397 The issuer must be listed in the F</usr/afs/etc/UserList> file on every
 398 machine where the Backup Server is running, or must be logged onto a
 399 server machine as the local superuser C<root> if the B<-localauth> flag is
 400 included.
 401
 402 =head1 SEE ALSO
 403
 404 L<backup(8)>,
 405 L<backup_deletedump(8)>
 406
 407 =head1 COPYRIGHT
 408
 409 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
 410
 411 This documentation is covered by the IBM Public License Version 1.0.  It was
 412 converted from HTML to POD by software written by Chas Williams and Russ
 413 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.