Displaying Backup Dump Records

Displaying Backup Dump Records
	Chapter 7. Backing Up and Restoring AFS Data

The backup command suite includes three commands for displaying information about data you have backed up:

To display information about one or more dump operations, such as the date it was performed and the number of volumes included, use the backup dumpinfo command as described in To display dump records. You can display a detailed record of a single dump or more condensed records for a certain number of dumps, starting with the most recent and going back in time. You can specify the number of dumps or accept the default of 10.
To display a volume's dump history, use the backup volinfo command as described in To display a volume's dump history.
To display information extracted from a tape or backup data file about the volumes it includes, use the backup scantape command. To create new dump and tape records in the Backup Database derived from the tape and dump labels, add the -dbadd flag. For instructions, see To scan the contents of a tape.

To display dump records

Verify that you are authenticated as a user listed in the /usr/afs/etc/UserList file. If necessary, issue the bos listusers command, which is fully described in To display the users in the UserList file.
```
   % bos listusers <machine name>
```
Issue the backup dumpinfo command to list information about dumps recorded in the Backup Database.
```
   % backup dumpinfo [-ndumps <no. of dumps>]  [-id <dump id>]  [-verbose]
```
where
dump
Is the shortest acceptable abbreviation of dumpinfo.
-ndumps
Displays the Backup Database record for each of the specified number of dumps, starting with the most recent and going back in time. 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 -id argument or -verbose flag; omit all three options to display the records for the last 10 dumps.
-id
Specifies the dump ID number of a single dump for which to display the Backup Database record. You must include the -id switch. Do not combine this option with the -ndumps or -verbose arguments; omit all three arguments to display the records for the last 10 dumps.
-verbose
Provides more detailed information about the dump specified with the -id argument, which must be provided along with it. Do not combine this flag with the -ndumps option.

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

dumpid

The dump ID number.

parentid

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

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 parentid field is also 0. A value of 1 or greater indicates an incremental dump made at the corresponding level in the dump hierarchy.

created

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

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 backup deletedump command to remove such entries.

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 (zero) in this case.

dump name

The dump name in the form

   volume_set_name.dump_level_name (initial_dump_ID)

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

The 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.

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

id: The dump ID number.
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.
volumes: The number of volumes for which the dump includes data.
created: The date and time at which the dump operation began.

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: XBSA_program: Server: hostname

where XBSA_program is the name of the XBSA-compliant program and 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 Tape, the first two lines of each entry report information about that tape in the following fields:

name: The tape's permanent name if it has one, or its AFS tape name otherwise, and its tape ID number in parentheses.
nVolumes: The number of volumes for which this tape includes dump data.
created: The date and time at which the Tape Coordinator began writing data to this tape.

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:

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.
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.
Nbytes: The number of bytes of data in the dump of the volume.
Volume: The volume name, complete with .backup or .readonly extension if appropriate.

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

The first section, headed by the underlined string Dump, includes information about the entire dump. The fields labeled id, level, created, and nVolumes report the same values (though in a different order) as appear on the first line of output when the -id argument is provided by itself. Other fields of potential interest to the backup operator are:
Group id
The dump's group ID number, which is recorded in the dump's Backup Database record if the GROUPID instruction appears in the Tape Coordinator's /usr/afs/backup/CFG_tcid file when the dump is created.
maxTapes
The number of tapes that contain the dump set to which this dump belongs.
Start Tape Seq
The ordinal of the tape on which this dump begins in the set of tapes that contain the dump set.
For each tape that contains data from this dump, there follows a section headed by the underlined string Tape. The fields labeled name, written, and nVolumes report the same values (though in a different order) as appear on the second and third lines of output when the -id argument is provided by itself. Other fields of potential interest to the backup operator are:
expires
The date and time when this tape can be recycled, because all dumps it contains have expired.
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).
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 nMBytes Data and 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.
For each volume on a given tape, there follows a section headed by the underlined string Volume. The fields labeled name, position, clone, and nBytes report the same values (though in a different order) as appear in the table that lists the volumes in each tape when the -id argument is provided by itself. Other fields of potential interest to the backup operator are:
id
The volume ID.
tape
The name of the tape containing this volume data.

The following example command displays the Backup Database records for the five most recent dump operations.

   % backup dump 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

To display a volume's dump history

Verify that you are authenticated as a user listed in the /usr/afs/etc/UserList file. If necessary, issue the bos listusers command, which is fully described in To display the users in the UserList file.
```
   % bos listusers <machine name>
```
Issue the backup volinfo command to display a volume's dump history.
```
   % backup volinfo <volume name>
```
where
voli
Is the shortest acceptable abbreviation of volinfo.
volume name
Names the volume for which to display the dump history. If you dumped the backup or read-only version of the volume, include the .backup or .readonly extension.

The output includes a line for each Backup Database dump record that mentions the specified volume, order from most to least recent. The output for each record appears in a table with six columns:

dumpID: The dump ID of the dump that includes the volume.
lvl: The depth in the dump hierarchy of the dump level at which the volume was dumped. A value of 0 indicates a full dump. A value of 1 or greater indicates an incremental dump made at the specified depth in the dump hierarchy.
parentid: The dump ID of the dump's parent dump. A value of 0 indicates a full dump, which has no parent; in this case, the value in the lvl column is also 0.
creation date: The date and time at which the Backup System started the dump operation that created the dump.
clone date: For a backup or read-only volume, the time at which it was cloned from its read/write source. For a read/write volume, the same as the value in the creation date field.
tape name: The name of the tape containing the dump: either the permanent tape name, or an AFS tape name in the format volume_set_name.dump_level_name.tape_index where volume_set_name is the name of the volume set associated with the initial dump in the dump set of which this tape is a part; dump_level_name is the name of the dump level at which the initial dump was backed up; tape_index is the ordinal of the tape in the dump set. Either type of name can be followed by a dump ID in parentheses; if it appears, it is the dump ID of the initial dump in the dump set to which this appended dump belongs.

The following example shows part of the dump history of the backup volume user.smith.backup:

   % backup volinfo user.smith.backup
   DumpID    lvl parentID  creation   date  clone date       tape name
   924600000 1   924427600 04/20/1999 05:20 04/20/1999 05:01 user_incr_2 (924514392)
   924514392 1   924427600 04/19/1999 05:33 04/19/1999 05:08 user_incr_2 
   924427600 0           0 04/18/1999 05:26 04/18/1999 04:58 user_full_6 
       .     .      .         .       .       .      .         .
       .     .      .         .       .       .      .         .

To scan the contents of a tape

Note

The ability to scan a tape that is corrupted or damaged depends on the extent of the damage and what type of data is corrupted. The Backup System can almost always scan the tape successfully up to the point of damage. If the damage is minor, the Backup System can usually skip over it and scan the rest of the tape, but more major damage can prevent further scanning. A scanning operation does not have to begin with the first tape in a dump set, but the Backup System can process tapes only in sequential order after the initial tape provided. Therefore, damage on one tape does not prevent scanning of the others in the dump set, but it is possible to scan either the tapes that precede the damaged one or the ones that follow it, not both.

If you use the -dbadd flag to scan information into the Backup Database and the first tape you provide is not the first tape in the dump set, the following restrictions apply:

If the first data on the tape is a continuation of a volume that begins on the previous (unscanned) tape in the dump set, the Backup System does not add a record for that volume to the Backup Database.
The Backup System must read the marker that indicates the start of an appended dump to add database records for the volumes in it. If the first volume on the tape belongs to an appended dump, but is not immediately preceded by the appended-dump marker, the Backup System does not create a Backup Database record for it or any subsequent volumes that belong to that appended dump.

Verify that you are authenticated as a user listed in the /usr/afs/etc/UserList file. If necessary, issue the bos listusers command, which is fully described in To display the users in the UserList file.
```
   % bos listusers <machine name>
```
If the Tape Coordinator for the tape device that is to perform the operation is not already running, open a connection to the appropriate Tape Coordinator machine and issue the butc command, for which complete instructions appear in To start a Tape Coordinator process.
```
   % butc [<port offset>] [-noautoquery]
```
If scanning a tape, place it in the drive.
(Optional) Issue the backup command to enter interactive mode.
```
   % backup
```
Issue the backup scantape command to read the contents of the tape.
```
   backup> scantape [-dbadd] [-portoffset <TC port offset>]
```
where
sc
Is the shortest acceptable abbreviation of scantape.
-dbadd
Constructs dump and tape records from the tape and dump labels in the dump and writes them into the Backup Database.
TC port offset
Specifies the port offset number of the Tape Coordinator process that is handling the operation. You must provide this argument unless the default value of 0 (zero) is appropriate.
If you did not include the -noautoquery flag when you issued the butc command, or the device's CFG_device_name configuration file includes the instruction AUTOQUERY YES instruction, then the Tape Coordinator prompts you to place the tape in the device's drive. You have already done so, but you must now press <Return> to indicate that the tape is ready for reading.

To terminate a tape scanning operation, use a termination signal such as <Ctrl-c>, or issue the (backup) kill command in interactive mode. It is best not to interrupt the scan if you included the -dbadd argument. If the Backup System has already written new records into the Backup Database, then you must remove them before rerunning the scanning operation. If during the repeated scan operation the Backup System finds that a record it needs to create already exists, it halts the operation.

For each dump on the tape, the output in the Tape Coordinator window displays the dump label followed by an entry for each volume. There is no output in the command window. The dump label has the same fields as the tape label displayed by the backup readlabel command, as described in Writing and Reading Tape Labels. Or see the OpenAFS Administration Reference for a detailed description of the fields in the output.

The following example shows the dump label and first volume entry on the tape in the device that has port offset 2:

   % backup scantape 2
   -- Dump label --
   tape name = monthly_guest
   AFS tape name = guests.monthly.3
   creationTime =  Mon Feb  1 04:06:40 1999
   cell = example.com
   size = 2150000 Kbytes
   dump path = /monthly
   dump id = 917860000
   useCount = 44
   -- End of dump label --
   -- volume --
   volume name: user.guest10.backup
   volume ID 1937573829
   dumpSetName: guests.monthly
   dumpID 917860000
   level 0
   parentID 0
   endTime 0
   clonedate Mon Feb  1 03:03:23 1999