=head1 SYNOPSIS
-B<backup scantape> [B<-dbadd>] [-portoffset <I<TC port offset>>]
-[B<-localauth>] [B<-cell> <I<cell name>>] [B<-help>]
+B<backup scantape> [B<-dbadd>] [B<-portoffset> <I<TC port offset>>]
+ [B<-localauth>] [B<-cell> <I<cell name>>] [B<-help>]
-B<backup sc> [B<-d>] [B<-p> <I<TC port offset>>] [B<-l>] [B<-c> <I<cell name>>] [-help]
+B<backup sc> [B<-d>] [B<-p> <I<TC port offset>>] [B<-l>]
+ [B<-c> <I<cell name>>] [B<-h>]
=head1 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 B<-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
-B</usr/afs/backup/CFG_>I<device_name> file associated with the
-specified port offset, then the B<backup scantape> command extracts
-dump information from the backup data file named in that port offset's
-entry in the B</usr/afs/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 B<-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 B<backup savedb> command, or has
-the AFS tape name B<Ubik_db_dump.1>).
-
-The Tape Coordinator's default response to this command is to access
-the tape by invoking the B<MOUNT> instruction in the
-B<CFG_>I<device_name> file, or by prompting the backup operator
-to insert the tape if there is no B<MOUNT> instruction.
-However, if the B<AUTOQUERY NO> instruction appears in the
-B<CFG_>I<device_name> file, or if the issuer of the
-B<butc> command included the B<-noautoquery> flag, the Tape
-Coordinator instead expects the tape to be in the device already. If it
-is not, the Tape Coordinator invokes the B<MOUNT> instruction or
-prompts the operator.
+The B<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 B<-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 C<FILE YES> instruction appears in the
+F</usr/afs/backup/CFG_I<device_name>> file associated with the specified
+port offset, then the B<backup scantape> command extracts dump information
+from the backup data file named in that port offset's entry in the
+F</usr/afs/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 B<-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 B<backup savedb> command, or has the
+AFS tape name C<Ubik_db_dump.1>).
+
+The Tape Coordinator's default response to this command is to access the
+tape by invoking the C<MOUNT> instruction in the F<CFG_I<device_name>>
+file, or by prompting the backup operator to insert the tape if there is
+no C<MOUNT> instruction. However, if the C<AUTOQUERY NO> instruction
+appears in the F<CFG_I<device_name>> file, or if the issuer of the B<butc>
+command included the B<-noautoquery> flag, the Tape Coordinator instead
+expects the tape to be in the device already. If it is not, the Tape
+Coordinator invokes the C<MOUNT> instruction or prompts the operator.
To terminate a tape scanning operation in interactive mode, issue the
-B<(backup) kill> command. In noninteractive mode, the only
-choice is to use a termination signal such as <B<Ctrl-c>> to halt
-the Tape Coordinator completely.
+B<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.
=head1 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 B<MOUNT> instruction in the local
-B</usr/afs/backup/CFG_>I<device_name> file, or by prompting the
-operator if there is no B<MOUNT> instruction.
+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 C<MOUNT> instruction in the
+local F</usr/afs/backup/CFG_I<device_name>> file, or by prompting the
+operator if there is no C<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
+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
+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
+If the B<-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 B<(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:
+issuing the B<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 B<-dbadd> flag is included and the first tape provided is not the
+first tape in the dump set, the following restrictions apply:
=over 4
=item *
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 previous (unscanned) tape in the dump set, the Backup System does not
+add a record for that volume to the Backup Database.
=item *
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
+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.
-
+Backup Database record for it or any subsequent volumes that belong to
+that appended dump.
=back
=over 4
-=item -dbadd
+=item B<-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).
+only if the database does not already contain an entry with the same dump
+ID number).
-=item -portoffset
+=item B<-portoffset> <I<TC port offset>>
Specifies the port offset number of the Tape Coordinator handling the
tapes for this operation.
-=item -localauth
+=item B<-localauth>
Constructs a server ticket using a key from the local
-B</usr/afs/etc/KeyFile> file. The B<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
-B<backup> reference page.
+F</usr/afs/etc/KeyFile> file. The B<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 L<backup(8)>.
-=item -cell
+=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 B<backup> reference page.
+Names the cell in which to run the command. Do not combine this argument
+with the B<-localauth> flag. For more details, see L<backup(8)>.
-=item -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
=head1 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.
+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 B<backup readlabel> command:
=over 4
-=item C<tape nameC<>
->
+=item tape name
-The permanent name assigned by using the -pname argument of the
-B<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 C<<NULL>> appears in this field.
+The permanent name assigned by using the B<-pname> argument of the
+B<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
+C<< <NULL> >> appears in this field.
-=item C<AFS tape name
->
+=item 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 B<backup dump> operation, or the operator can assign it with the
-B<-name> argument to the B<backup labeltape> command.
+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 B<backup dump> operation, or the operator can assign it with the
+B<-name> argument to the B<backup labeltape> command.
=over 4
=item *
-I<volume_set_name>.I<dump_level_name>.I<tape
-_index>, if the tape contains volume data. The
-I<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;
-I<dump_level_name> is the last pathname element of the dump level at
-which the initial dump was backed up; and I<tape_index> is the
-numerical position of the tape in the dump set.
-
+I<volume_set_name>.I<dump_level_name>.I<tape_index>, if the tape contains
+volume data. The I<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; I<dump_level_name> is the last pathname element of the dump level at
+which the initial dump was backed up; and I<tape_index> is the numerical
+position of the tape in the dump set.
=item *
-C<<NULL>> if the tape has no AFS tape name. This is
-normally the case if the B<-name> argument was not included the last
-time the B<backup labeltape> command was used on this tape, and no
-data has been written to it since.
-
+C<< <NULL> >> if the tape has no AFS tape name. This is normally the case
+if the B<-name> argument was not included the last time the B<backup
+labeltape> command was used on this tape, and no data has been written to
+it since.
=back
-=item C<creationTime
->
+=item creationTime
The date and time at which the Backup System started performing the dump
operation that created the initial dump.
-=item C<cell
->
+=item cell
-The cell in which the dump set was created. This is the cell whose
-Backup Database contains a record of the dump set.
+The cell in which the dump set was created. This is the cell whose Backup
+Database contains a record of the dump set.
-=item C<size
->
+=item 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
-B<-size> argument to the B<backup labeltape> command or
-derived from the B</usr/afs/backup/tapeconfig> file on the Tape
-Coordinator machine, not from a measurement of the tape.
+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 B<-size>
+argument to the B<backup labeltape> command or derived from the
+F</usr/afs/backup/tapeconfig> file on the Tape Coordinator machine, not
+from a measurement of the tape.
-=item C<dump C<path>
->
+=item dump path
The dump level of the initial dump in the dump set.
-=item C<dump C<id>
->
+=item dump id
The dump ID number of the initial dump in the dump set, as recorded in the
Backup Database.
-=item C<useCount
->
+=item useCount
The number of times a dump has been written to the tape, or it has been
relabeled.
=over 4
-=item C<volume C<name>
->
+=item volume name
-The volume name, complete with a C<.backup> or
-C<.readonly> extension, if appropriate.
+The volume name, complete with a C<.backup> or C<.readonly> extension, if
+appropriate.
-=item C<volume C<ID>
->
+=item volume ID
The volume's volume ID.
-=item C<dumpSetName
->
+=item dumpSetName
The dump to which the volume belongs. The dump name is of the form
-I<volume_set_name>B<.>I<dump_level_name> and
-matches the name displayed in the dump label.
+I<volume_set_name>.I<dump_level_name> and matches the name displayed in
+the dump label.
-=item C<dumpID
->
+=item dumpID
The dump ID of the dump named in the C<dumpSetName> field.
-=item C<level
->
+=item level
The depth in the dump hierarchy of the dump level used in creating the
-dump. A value of C<0> indicates a full dump. A value of
-C<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.
+dump. A value of C<0> indicates a full dump. A value of C<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.
-=item C<parentID
->
+=item parentID
-The dump ID number of C<dumpSetName>'s parent dump. It
-is C<0> if the value in the C<level> field is
-C<0>.
+The dump ID number of C<dumpSetName>'s parent dump. It is C<0> if the
+value in the C<level> field is C<0>.
-=item C<endTime
->
+=item endTime
Is always C<0>; it is reserved for internal use.
-=item C<cloneDate
->
+=item 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
+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 C<dumpSetName> field.
=back
-The message C<Scantape: Finished> indicates the completion of
-the output.
+The message C<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
-<B<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:
+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)
=head1 PRIVILEGE REQUIRED
-The issuer must be listed in the /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.
+The issuer must be listed in the F</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 C<root> if the B<-localauth> flag is
+included.
=head1 SEE ALSO
-L<backup(1)>,
-L<backup_dump(1)>,
-L<backup_dumpinfo(1)>,
-L<butc(1)>
+L<butc(5)>,
+L<backup(8)>,
+L<backup_dump(8)>,
+L<backup_dumpinfo(8)>,
+L<butc(8)>
=head1 COPYRIGHT
git://git.openafs.org / openafs.git / blobdiff