=head1 NAME

backup scantape - Extracts dump information from a tape

=head1 SYNOPSIS

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

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

=head1 DESCRIPTION

The C<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 B<FILE YES> instruction appears in the
B</usr/afs/backup/CFG_>I<device_name> file associated with the specified
port offset, then the C<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 C<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 C<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.

To terminate a tape scanning operation in interactive mode, issue the
C<(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.

=head1 OPTIONS

=over 4

=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).

=item B<-portoffset> I<TC port offset>

Specifies the port offset number of the Tape Coordinator
handling the tapes for this operation.

=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

For every dump on a tape, the C<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 C<backup readlabel> command:

=over

=item B<tape name>

The permanent name assigned by using the B<-pname> argument of the
C<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<E<lt>NULLE<gt>> appears in this field.

=item B<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 C<backup dump> operation, or the
operator can assign it with the B<-name> argument to the C<backup
labeltape> command.

=over

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

=item *

C<E<lt>NULLE<gt>> 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
C<backup labeltape> command was used on this tape, and no data
has been written to it since.

=back

=item B<creationTime>

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

=item B<cell>

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

=item B<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 C<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.

=item B<dump path>

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

=item B<dump id>

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

=item B<useCount>

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

=back

The volume header contains the following fields:

=over

=item B<volume name>

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

=item B<volume ID>

The volume's volume ID.

=item B<dumpSetName>

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

=item B<dumpID>

The dump ID of the dump named in the C<dumpSetName> field.

=item B<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.

=item B<parentID>

The dump ID number of C<dumpSetName>'s parent dump. It is 0 if the
value in the C<level> field is 0.

=item B<endTime>

Is always 0; it is reserved for internal use.

=item B<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
C<dumpSetName> field.

=back

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:

   Are there more tapes? (y/n)

=head1 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 = abc.com
   size = 2150000 Kbytes
   dump path = B</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

=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 CAVEATS

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.

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 C<backup labeltape> command, it is not
possible to recover data from it for the purposes of rebuilding the
Backup Database.

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 C<(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

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

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

=back

=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_dump(1)>,
L<backup_dumpinfo(1)>,
L<butc(1)>

=cut
