Import Upstream version 1.8.5

[hcoop/debian/openafs.git] / doc / man-pages / pod8 / backup_scantape.pod

=head1 NAME

backup_scantape - Extracts dump information from a tape

=head1 SYNOPSIS

=for html
<div class="synopsis">

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

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

=for html
</div>

=head1 DESCRIPTION

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

=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 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
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 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 L<backup(8)>.

=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 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 tape name

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

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

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

=back

=item creationTime

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

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

=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
F</usr/afs/backup/tapeconfig> file on the Tape Coordinator machine, not
from a measurement of the tape.

=item dump path

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

=item dump id

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

=item 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 4

=item volume name

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

=item volume ID

The volume's volume ID.

=item 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 dumpID

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

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

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

=item endTime

Is always C<0>; it is reserved for internal use.

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

=head1 PRIVILEGE REQUIRED

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<butc(5)>,
L<backup(8)>,
L<backup_dump(8)>,
L<backup_dumpinfo(8)>,
L<butc(8)>

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