=head1 NAME

backup dumpinfo - Displays a dump record from the Backup Database

=head1 SYNOPSIS

backup dumpinfo [B<-ndumps> I<no. of dumps>]  [B<-id> I<dump id>]
[B<-verbose>]  [B<-localauth>]  [B<-cell> I<cell name>]  [B<-help> ]

backup dumpi [B<-n> I<no. of dumps>]  [B<-i> I<dump id>]
[B<-v>]  [B<-l>]  [B<-c> I<cell name>]  [B<-h>]

=head1 DESCRIPTION

The C<backup dumpinfo> command formats and displays the Backup Database
record for the specified dumps. To specify how many of the most recent
dumps to display, starting with the newest one and going back in time,
use the B<-ndumps> argument. To display more detailed information about a
single dump, use the B<-id> argument. To display the records for the 10
most recent dumps, omit both the B<-ndumps> and B<-id> arguments.

The B<-verbose> flag produces very detailed information that is useful
mostly for debugging purposes. It can be combined only with the B<-id>
argument.

=head1 OPTIONS

=over 4

=item B<-ndumps> I<no. of dumps>

Displays the Backup Database record for each of the specified
number of dumps that were most recently performed. If the
database contains fewer dumps than are requested, the output
includes the records for all existing dumps. Do not combine
this argument with the B<-id> or B<-verbose> options; omit all
options to display the records for the last 10 dumps.

=item B<-id> I<dump id>

Specifies the dump ID number of a single dump for which to
display the Backup Database record. Precede the I<dump id> value
with the B<-id> switch; otherwise, the command interpreter
interprets it as the value of the B<-ndumps> argument. Combine
this argument with the B<-verbose> flag, but not with the B<-ndumps>
argument; omit all options to display the records for the last
10 dumps.

=item B<-verbose>

Provides more detailed information about the dump specified
with the B<-id> argument, which must be provided along with it. Do
not combine this flag with the B<-ndumps> argument.

=item B<-localauth>

Constructs a server ticket using a key from the local
B</usr/afs/etc/KeyFile> file. The C<backup> command interpreter
presents it to the Backup Server, Volume Server and VL Server
during mutual authentication. Do not combine this flag with the
B<-cell> argument. For more details, see the introductory L<backup(1)> reference page.

=item B<-cell> I<cell name>

Names the cell in which to run the command. Do not combine this
argument with the B<-localauth> flag. For more details, see the
introductory L<backup(1)> reference page.


=item B<-help>

Prints the online help for this command. All other valid
options are ignored.

=back

=head1 OUTPUT

If the B<-ndumps> argument is provided, the output presents the following
information in table form, with a separate line for each dump:

=over

=item B<dumpid>

The dump ID number.

=item B<parentid>

The dump ID number of the dump's parent dump. A value of 0
(zero) identifies a full dump.

=item B<lv>

The depth in the dump hierarchy of the dump level used to
create the dump. A value of 0 (zero) identifies a full dump, in
which case the value in the C<parentid> field is also 0. A value
of 1 or greater indicates an incremental dump made at the
corresponding level in the dump hierarchy.

=item B<created>

The date and time at which the Backup System started the dump
operation that created the dump.

=item B<nt>

The number of tapes that contain the data in the dump. A value
of 0 (zero) indicates that the dump operation was terminated or
failed. Use the C<backup deletedump> command to remove such
entries.

=item B<nvols>

The number of volumes from which the dump includes data. If a
volume spans tapes, it is counted twice. A value of 0 (zero)
indicates that the dump operation was terminated or failed; the
value in the nt field is also 0 in this case.

=item B<dump name>

The dump name in the form

I<volume_set_name>.I<dump_level_name> (I<initial_dump_ID>)

where I<volume_set_name> is the name of the volume set, and
I<dump_level_name> is the last element in the dump level pathname
at which the volume set was dumped.

The I<initial_dump_ID>, if displayed, is the dump ID of the
initial dump in the dump set to which this dump belongs. If
there is no value in parentheses, the dump is the initial dump
in a dump set that has no appended dumps.

=back

If the B<-id> argument is provided alone, the first line of output begins
with the string C<Dump> and reports information for the entire dump in
the following fields:

=over

=item B<id>

The dump ID number.

=item B<level>

The depth in the dump hierarchy of the dump level used to
create the dump. A value of 0 (zero) identifies a full dump. A
value of 1 (one) or greater indicates an incremental dump made
at the specified level in the dump hierarchy.

=item B<volumes>

The number of volumes for which the dump includes data.

=item B<created>

The date and time at which the dump operation began.

=back

If an XBSA server was the backup medium for the dump (rather than a
tape device or backup data file), the following line appears next:

Backup Service: I<XBSA_program>: Server: I<hostname>

where I<XBSA_program> is the name of the XBSA-compliant program and
I<hostname> is the name of the machine on which the program runs.

Next the output includes an entry for each tape that houses volume
data from the dump. Following the string C<Tape>, the first two lines of
each entry report information about that tape in the following fields:

=over

=item B<name>

The tape's permanent name if it has one, or its AFS tape name
otherwise, and its tape ID number in parentheses.

=item B<nVolumes>

The number of volumes for which this tape includes dump data.

=item B<created>

The date and time at which the Tape Coordinator began writing
data to this tape.

=back

Following another blank line, the tape-specific information concludes
with a table that includes a line for each volume dump on the tape.
The information appears in columns with the following headings:

=over

=item B<Pos>

The relative position of each volume in this tape or file. On a
tape, the counter begins at position 2 (the tape label occupies
position 1), and increments by one for each volume. For volumes
in a backup data file, the position numbers start with 1 and do
not usually increment only by one, because each is the ordinal
of the 16 KB offset in the file at which the volume's data
begins. The difference between the position numbers therefore
indicates how many 16 KB blocks each volume's data occupies.
For example, if the second volume is at position 5 and the
third volume in the list is at position 9, that means that the
dump of the second volume occupies 64 KB (four 16-KB blocks) of
space in the file.

=item B<Clone time>

For a backup or read-only volume, the time at which it was
cloned from its read/write source. For a Read/Write volume, it
is the same as the dump creation date reported on the first
line of the output.

=item B<Nbytes>

The number of bytes of data in the dump of the volume.

=item B<Volume>

The volume name, complete with C<.backup> or C<.readonly> extension
if appropriate.

=back

If both the B<-id> and B<-verbose> options are provided, the output is
divided into several sections:

=over

=item *

The first section, headed by the underlined string C<Dump>, includes
information about the entire dump. The fields labeled C<id>, C<level>,
C<created>, and C<nVolumes> report the same values (though in a
different order) as appear on the first line of output when the
B<-id> argument is provided by itself. Other fields of potential
interest to the backup operator are:

=over

=item B<Group id>

The dump's I<group ID number>, which is recorded in the
dump's Backup Database record if the B<GROUPID> instruction
appears in the Tape Coordinator's
B</usr/afs/backup/CFG_>I<tcid> file when the dump is created.

=item B<maxTapes>

The number of tapes that contain the dump set to which
this dump belongs.

=item B<Start Tape Seq>

The ordinal of the tape on which this dump begins in the
set of tapes that contain the dump set.

=back

=item *

For each tape that contains data from this dump, there follows a
section headed by the underlined string C<Tape>. The fields labeled
C<name>, C<written>, and C<nVolumes> report the same values (though in a
different order) as appear on the second and third lines of output
when the B<-id> argument is provided by itself. Other fields of
potential interest to the backup operator are:

=over

=item B<expires>

The date and time when this tape can be recycled, because
all dumps it contains have expired.

=item B<nMBytes Data and nBytes Data>

Summed together, these fields represent the total amount
of dumped data actually from volumes (as opposed to
labels, filemarks, and other markers).

=item B<KBytes Tape Used>

The number of kilobytes of tape (or disk space, for a
backup data file) used to store the dump data. It is
generally larger than the sum of the values in the
C<nMBytes> Data and C<nBytes> Data fields, because it includes
the space required for the label, file marks and other
markers, and because the Backup System writes data at 16
KB offsets, even if the data in a given block doesn't
fill the entire 16 KB.

=back

=item *

For each volume on a given tape, there follows a section headed by
the underlined string C<Volume>. The fields labeled C<name>, C<position>,
C<clone>, and C<nBytes> report the same values (though in a different
order) as appear in the table that lists the volumes in each tape
when the B<-id> argument is provided by itself. Other fields of
potential interest to the backup operator are:

=over

=item B<id>

The volume ID.

=item B<tape>

The name of the tape containing this volume data.

=back

=back

=head1 EXAMPLES

The following example displays information about the last five dumps:

    backup dumpinfo -ndumps 5
      dumpid   parentid lv created          nt nvols dump name
   924424000          0 0  04/18/1999 04:26  1    22 usr.sun (924424000)
   924685000  924424000 1  04/21/1999 04:56  1    62 usr.wed (924424000)
   924773000  924424000 1  04/22/1999 05:23  1    46 usr.thu (924424000)
   924860000  924424000 1  04/23/1999 05:33  1    58 usr.fri (924424000)
   925033000          0 0  04/25/1999 05:36  2    73 sys.week

The following example displays a more detailed record for a single
dump.

    backup dumpinfo -id 922097346
   Dump: id 922097346, level 0, volumes 1, created Mon Mar 22 05:09:06 1999
   Tape: name monday.user.backup (922097346)
   nVolumes 1, created 03/22/1999 05:09
    Pos       Clone time   Nbytes Volume
      1 03/22/1999 04:43 27787914 user.pat.backup

The following example displays even more detailed information about
the dump displayed in the previous example (dump ID 922097346). This
example includes only one exemplar of each type of section (C<Dump>,
C<Tape>, and C<Volume>):

    backup dumpinfo -id 922097346 -verbose
   Dump
   ----
   id = 922097346
   Initial id = 0
   Appended id = 922099568
   parent = 0
   level = 0
   flags = 0x0
   volumeSet = user
   dump path = /monday1
   name = user.monday1
   created = Mon Mar 22 05:09:06 1999
   nVolumes = 1
   id  = 0
   tapeServer =
   format= user.monday1.%d
   maxTapes = 1
   Start Tape Seq = 1
   name = pat
   instance =
   cell =
   Tape
   ----
   tape name = monday.user.backup
   AFS tape name = user.monday1.1
   flags = 0x20
   written = Mon Mar 22 05:09:06 1999
   expires = NEVER
   kBytes Tape Used = 121
   nMBytes Data = 0
   nBytes  Data = 19092
   nFiles = 0
   nVolumes = 1
   seq = 1
   tapeid = 0
   useCount = 1
   dump = 922097346
   Volume
   ------
   name = user.pat.backup
   flags = 0x18
   id = 536871640
   server =
   partition = 0
   nFrags = 1
   position = 2
   clone = Mon Mar 22 04:43:06 1999
   startByte = 0
   nBytes = 19092
   seq = 0
   dump = 922097346
   tape = user.monday1.1

=head1 PRIVILEGE REQUIRED

The issuer must be listed in the B</usr/afs/etc/UserList> file on every
machine where the Backup Server is running, or must be logged onto a
server machine as the local superuser B<root> if the B<-localauth> flag is
included.

=head1 COPYRIGHT

IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.

Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
Stanford Linear Accelerator Center, a department of Stanford University.

=head1 SEE ALSO

L<backup(1)>,
L<backup_deletedump(1)>

=cut
