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