jimzah/openafs
1
0
Fork 0
mirror of https://git.openafs.org/openafs.git synced 2025-01-19 07:20:11 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity
cd6e2b9929
openafs/doc/man-pages/pod8/backup_scantape.pod
Russ Allbery 03b9fcc883 man1-editing-pass-20051209 
Complete an initial editing and cleanup pass for all section one man pages.
Fix various conversion problems, formatting inconsistencies, and obvious
problems.  Please note that no editing for content has yet been done; this
is solely editing for formatting and correct conversion to POD.

Also, add some additional section five man pages that were omitted from the
first conversion run due to unusual file names, and globally replace
CAVEATS with CAUTIONS in the man pages to match the original section name.

The section one man pages should now be in reasonable shape and ready for
additional review and further updates, although there are probably still
remaining obvious problems.

====================
This delta was composed from multiple commits as part of the CVS->Git migration.
The checkin message with each commit was inconsistent.
The following are the additional commit messages.
====================

This file got the wrong name when it was originally committed.  Fix.
2005-12-09 14:48:56 +00:00

378 lines
12 KiB
Plaintext
Raw Blame History

=head1 NAME
backup scantape - Extracts dump information from a tape
=head1 SYNOPSIS
B<backup scantape> [B<-dbadd>] [-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]
=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.
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.
=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.
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 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:
=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 -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 -portoffset
Specifies the port offset number of the Tape Coordinator handling the
tapes for this operation.
=item -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.
=item -cell
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.
=item -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 C<tape nameC<>
>
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.
=item C<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 C<creationTime
>
The date and time at which the Backup System started performing the dump
operation that created the initial dump.
=item C<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 C<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.
=item C<dump C<path>
>
The dump level of the initial dump in the dump set.
=item C<dump C<id>
>
The dump ID number of the initial dump in the dump set, as recorded in the
Backup Database.
=item C<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 C<volume C<name>
>
The volume name, complete with a C<.backup> or
C<.readonly> extension, if appropriate.
=item C<volume C<ID>
>
The volume's volume ID.
=item C<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.
=item C<dumpID
>
The dump ID of the dump named in the C<dumpSetName> field.
=item C<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 C<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 C<endTime
>
Is always C<0>; it is reserved for internal use.
=item C<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 = /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 /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 SEE ALSO
L<backup(1)>,
L<backup_dump(1)>,
L<backup_dumpinfo(1)>,
L<butc(1)>
=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.
Reference in New Issue View Git Blame Copy Permalink