doc/man-pages/pod/backup_dumpinfo.pod

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