Provided by: openafs-client_1.8.0~pre5-1ubuntu1.2_amd64 bug

NAME

       backup_scantape - Extracts dump information from a tape

SYNOPSIS

       backup scantape [-dbadd] [-portoffset <TC port offset>]
           [-localauth] [-cell <cell name>] [-help]

       backup sc [-d] [-p <TC port offset>] [-l]
           [-c <cell name>] [-h]

DESCRIPTION

       The backup scantape command extracts information from the dump labels and volume headers
       on the tape in the device controlled by the Tape Coordinator indicated by the -portoffset
       argument. The Tape Coordinator displays the information for each volume in its window as
       soon as it extracts it (rather than waiting until it has scanned the entire tape).

       (If the "FILE YES" instruction appears in the /var/lib/openafs/backup/CFG_device_name file
       associated with the specified port offset, then the backup scantape command extracts dump
       information from the backup data file named in that port offset's entry in the
       /var/lib/openafs/backup/tapeconfig file on the Tape Coordinator machine, rather than from
       a tape. For the sake of clarity, the following text refers to tapes only, but the Backup
       System handles backup data files in much the same way.)

       If the -dbadd flag is provided, the backup scantape command creates new dump and volume
       records in the Backup Database for the scanned information. However, if it finds that a
       record already exists in the database for the same dump, it terminates the scanning
       operation.

       The scanning operation works only on tapes containing volume data.  The command fails with
       an error message if the tape contains a copy of the Backup Database (was created with the
       backup savedb command, or has the AFS tape name "Ubik_db_dump.1").

       The Tape Coordinator's default response to this command is to access the tape by invoking
       the "MOUNT" instruction in the CFG_device_name file, or by prompting the backup operator
       to insert the tape if there is no "MOUNT" instruction.  However, if the "AUTOQUERY NO"
       instruction appears in the CFG_device_name file, or if the issuer of the butc command
       included the -noautoquery flag, the Tape Coordinator instead expects the tape to be in the
       device already. If it is not, the Tape Coordinator invokes the "MOUNT" instruction or
       prompts the operator.

       To terminate a tape scanning operation in interactive mode, issue the backup kill command.
       In noninteractive mode, the only choice is to use a termination signal such as Ctrl-C to
       halt the Tape Coordinator completely.

CAUTIONS

       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.
       The Tape Coordinator automatically requests any subsequent tapes by invoking the "MOUNT"
       instruction in the local /var/lib/openafs/backup/CFG_device_name file, or by prompting the
       operator if there is no "MOUNT" instruction.

       The Tape Coordinator's success in scanning a tape that is corrupted or damaged depends on
       the extent of the damage and what type of data is corrupted. It can almost always scan the
       tape successfully up to the point of damage. If the damage is minor, the Tape Coordinator
       can usually skip over it and scan the rest of the tape, but more major damage can prevent
       further scanning. Because a scanning operation can start on any tape in a dump set, damage
       on one tape does not prevent scanning of the others in the dump set. However, it is
       possible to scan either the tapes that precede the damaged one or the ones that follow it,
       but not both.

       If a tape is relabeled with the backup labeltape command, it is not possible to recover
       data from it for the purposes of rebuilding the Backup Database.

       If the -dbadd flag is included on the command, it is best not to terminate the tape
       scanning operation before it completes (for example, by issuing the backup kill command in
       interactive mode). The Backup System writes a new record in the Backup Database for each
       dump as soon as it scans the relevant information on the tape, and so it possibly has
       already written new records. If the operator wants to rerun the scanning operation, he or
       she must locate and remove the records created during the terminated operation: the second
       operation exits automatically if it finds that a record that it needs to create already
       exists.

       If the -dbadd flag is included and the first tape provided 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.

OPTIONS

       -dbadd
           Adds the information extracted from the tape to the Backup Database (but only if the
           database does not already contain an entry with the same dump ID number).

       -portoffset <TC port offset>
           Specifies the port offset number of the Tape Coordinator handling the tapes for this
           operation.

       -localauth
           Constructs a server ticket using a key from the local /etc/openafs/server/KeyFile
           file. The backup command interpreter presents it to the Backup Server, Volume Server
           and VL Server during mutual authentication. Do not combine this flag with the -cell
           argument. For more details, see backup(8).

       -cell <cell name>
           Names the cell in which to run the command. Do not combine this argument with the
           -localauth flag. For more details, see backup(8).

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

OUTPUT

       For every dump on a tape, the backup scantape command displays in the Tape Coordinator
       window the dump label and the volume header of each volume in the dump. If a dump spans
       more than one tape, the dump label does not repeat at the beginning of subsequent tapes.

       A dump label contains the following fields, which are the same as in the output from the
       backup readlabel command:

       tape name
           The permanent name assigned by using the -pname argument of the backup labeltape
           command. This name remains on the tape until that argument is used again, no matter
           how many times the tape is recycled or otherwise relabeled. If the tape does not have
           a permanent name, the value "<NULL>" appears in this field.

       AFS tape name
           A tape name in one of the following prescribed formats. The Backup System
           automatically writes the appropriate AFS tape name to the label as part of a backup
           dump operation, or the operator can assign it with the -name argument to the backup
           labeltape command.

           •   volume_set_name.dump_level_name.tape_index, if the tape contains volume data. The
               volume_set_name is the name of the volume set that was dumped to create the
               initial dump in the dump set of which this tape is a part; dump_level_name is the
               last pathname element of the dump level at which the initial dump was backed up;
               and tape_index is the numerical position of the tape in the dump set.

           •   "<NULL>" if the tape has no AFS tape name. This is normally the case if the -name
               argument was not included the last time the backup labeltape command was used on
               this tape, and no data has been written to it since.

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

       cell
           The cell in which the dump set was created. This is the cell whose Backup Database
           contains a record of the dump set.

       size
           The tape's capacity (in kilobytes) as recorded on the label, rather than the amount of
           data on the tape. The value is assigned by the -size argument to the backup labeltape
           command or derived from the /var/lib/openafs/backup/tapeconfig file on the Tape
           Coordinator machine, not from a measurement of the tape.

       dump path
           The dump level of the initial dump in the dump set.

       dump id
           The dump ID number of the initial dump in the dump set, as recorded in the Backup
           Database.

       useCount
           The number of times a dump has been written to the tape, or it has been relabeled.

       The volume header contains the following fields:

       volume name
           The volume name, complete with a ".backup" or ".readonly" extension, if appropriate.

       volume ID
           The volume's volume ID.

       dumpSetName
           The dump to which the volume belongs. The dump name is of the form
           volume_set_name.dump_level_name and matches the name displayed in the dump label.

       dumpID
           The dump ID of the dump named in the "dumpSetName" field.

       level
           The depth in the dump hierarchy of the dump level used in creating the dump. A value
           of 0 indicates a full dump. A value of 1 or greater indicates an incremental dump made
           at the indicated depth in the hierarchy. The value reported is for the entire dump,
           not necessarily for the volume itself; for example, it is possible for a dump
           performed at an incremental level to include a full dump of an individual volume if
           the volume was omitted from previous dumps.

       parentID
           The dump ID number of "dumpSetName"'s parent dump. It is 0 if the value in the "level"
           field is 0.

       endTime
           Is always 0; it is reserved for internal use.

       cloneDate
           The date and time at which the volume was created. For a backup or read-only volume,
           this represents the time at which it was cloned from its read/write source. For a
           read/write volume, it indicates the time at which the Backup System locked the volume
           for purposes of including it in the dump named in the "dumpSetName" field.

       The message "Scantape: Finished" indicates the completion of the output.

       In normal circumstances, the Backup System writes a marker to indicate that a volume is
       the last one on a tape, or that the volume continues on the next tape. However, if a
       backup operation terminated abnormally (for example, because the operator terminated the
       Tape Coordinator by issuing the Ctrl-C command during the operation), then there is no
       such marker. Some very early versions of the Backup System also did not write these
       markers. If a tape does not conclude with one of the expected markers, the Tape
       Coordinator cannot determine if there is a subsequent tape in the dump set and so
       generates the following message in its window:

          Are there more tapes? (y/n)

EXAMPLES

       The following example shows the output for the first two volumes on a tape in the device
       with port offset 0:

          % backup scantape
          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
          -- volume --
          volume name: user.guest11.backup
          volume ID 1938519386
          dumpSetName: guests.monthly
          dumpID 917860000
          level 0
          parentID 0
          endTime 0
          clonedate Mon Feb  1 03:05:15 1999

PRIVILEGE REQUIRED

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

SEE ALSO

       butc(5), backup(8), backup_dump(8), backup_dumpinfo(8), butc(8)

COPYRIGHT

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

       This documentation is covered by the IBM Public License Version 1.0.  It was converted
       from HTML to POD by software written by Chas Williams and Russ Allbery, based on work by
       Alf Wachsmann and Elizabeth Cassell.