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