Section: AFS Command Reference (8)
Updated: OpenAFS


backup scantape - Extracts dump information from a tape 


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

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


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

(If the FILE YES instruction appears in the/usr/afs/backup/CFG_device_name file associated with the specifiedport offset, then the backup scantape command extracts dump informationfrom the backup data file named in that port offset's entry in the/usr/afs/backup/tapeconfig file on the Tape Coordinator machine, ratherthan from a tape. For the sake of clarity, the following text refers totapes only, but the Backup System handles backup data files in much thesame way.)

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

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

The Tape Coordinator's default response to this command is to access thetape by invoking the MOUNT instruction in the CFG_device_namefile, or by prompting the backup operator to insert the tape if there isno MOUNT instruction. However, if the AUTOQUERY NO instructionappears in the CFG_device_name file, or if the issuer of the butccommand included the -noautoquery flag, the Tape Coordinator insteadexpects the tape to be in the device already. If it is not, the TapeCoordinator invokes the MOUNT instruction or prompts the operator.

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


A scanning operation does not have to begin with the first tape in a dumpset, but the Backup System can process tapes only in sequential orderafter the initial tape provided. The Tape Coordinator automaticallyrequests any subsequent tapes by invoking the MOUNT instruction in thelocal /usr/afs/backup/CFG_device_name file, or by prompting theoperator if there is no MOUNT instruction.

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

If a tape is relabeled with the backup labeltape command, it is notpossible to recover data from it for the purposes of rebuilding the BackupDatabase.

If the -dbadd flag is included on the command, it is best not toterminate the tape scanning operation before it completes (for example, byissuing the backup kill command in interactive mode). The Backup Systemwrites a new record in the Backup Database for each dump as soon as itscans the relevant information on the tape, and so it possibly has alreadywritten new records. If the operator wants to rerun the scanningoperation, he or she must locate and remove the records created during theterminated operation: the second operation exits automatically if it findsthat a record that it needs to create already exists.

If the -dbadd flag is included and the first tape provided is not thefirst tape in the dump set, the following restrictions apply:

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


Adds the information extracted from the tape to the Backup Database (butonly if the database does not already contain an entry with the same dumpID number).
-portoffset <TC port offset>
Specifies the port offset number of the Tape Coordinator handling thetapes for this operation.
Constructs a server ticket using a key from the local/usr/afs/etc/KeyFile file. The backup command interpreter presentsit to the Backup Server, Volume Server and VL Server during mutualauthentication. Do not combine this flag with the -cell argument. Formore details, see the backup(8) manpage.
-cell <cell name>
Names the cell in which to run the command. Do not combine this argumentwith the -localauth flag. For more details, see the backup(8) manpage.
Prints the online help for this command. All other valid options areignored.


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

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

tape name
The permanent name assigned by using the -pname argument of thebackup labeltape command. This name remains on the tape until thatargument is used again, no matter how many times the tape is recycled orotherwise 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 Systemautomatically writes the appropriate AFS tape name to the label as part ofa 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 containsvolume data. The volume_set_name is the name of the volume set that wasdumped to create the initial dump in the dump set of which this tape is apart; dump_level_name is the last pathname element of the dump level atwhich the initial dump was backed up; and tape_index is the numericalposition of the tape in the dump set.
< <NULL >> if the tape has no AFS tape name. This is normally the caseif the -name argument was not included the last time the backuplabeltape command was used on this tape, and no data has been written toit since.
The date and time at which the Backup System started performing the dumpoperation that created the initial dump.
The cell in which the dump set was created. This is the cell whose BackupDatabase contains a record of the dump set.
The tape's capacity (in kilobytes) as recorded on the label, rather thanthe amount of data on the tape. The value is assigned by the -sizeargument to the backup labeltape command or derived from the/usr/afs/backup/tapeconfig file on the Tape Coordinator machine, notfrom 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 theBackup Database.
The number of times a dump has been written to the tape, or it has beenrelabeled.

The volume header contains the following fields:

volume name
The volume name, complete with a .backup or .readonly extension, ifappropriate.
volume ID
The volume's volume ID.
The dump to which the volume belongs. The dump name is of the formvolume_set_name.dump_level_name and matches the name displayed inthe dump label.
The dump ID of the dump named in the dumpSetName field.
The depth in the dump hierarchy of the dump level used in creating thedump. A value of 0 indicates a full dump. A value of 1 or greaterindicates an incremental dump made at the indicated depth in thehierarchy. The value reported is for the entire dump, not necessarily forthe volume itself; for example, it is possible for a dump performed at anincremental level to include a full dump of an individual volume if thevolume was omitted from previous dumps.
The dump ID number of dumpSetName's parent dump. It is 0 if thevalue in the level field is 0.
Is always 0; it is reserved for internal use.
The date and time at which the volume was created. For a backup orread-only volume, this represents the time at which it was cloned from itsread/write source. For a read/write volume, it indicates the time at whichthe Backup System locked the volume for purposes of including it in thedump 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 indicatethat a volume is the last one on a tape, or that the volume continues onthe next tape. However, if a backup operation terminated abnormally (forexample, because the operator terminated the Tape Coordinator by issuingthe Ctrl-C command during the operation), then there is no suchmarker. Some very early versions of the Backup System also did not writethese markers. If a tape does not conclude with one of the expectedmarkers, the Tape Coordinator cannot determine if there is a subsequenttape in the dump set and so generates the following message in its window:

   Are there more tapes? (y/n)


The following example shows the output for the first two volumes on a tapein 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 =   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


The issuer must be listed in the /usr/afs/etc/UserList file on everymachine where the Backup Server is running, or must be logged onto aserver machine as the local superuser root if the -localauth flag isincluded. 


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


IBM Corporation 2000. <> All Rights Reserved.

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




This document was created byman2html,using the manual pages.