mirror of
https://git.openafs.org/openafs.git
synced 2025-01-19 07:20:11 +00:00
e3dfba8e6c
This is the initial conversion of the AFS Adminstrators Reference into POD for use as man pages. The man pages are now generated via pod2man from regen.sh so that only those working from CVS have to have pod2man available. The Makefile only installs. The pages have also been sorted out into pod1, pod5, and pod8 directories, making conversion to the right section of man page easier without maintaining a separate list and allowing for names to be duplicated between pod5 and pod1 or pod8 (which will likely be needed in a few cases). This reconversion is done with a new script based on work by Chas Williams. In some cases, the output is worse than the previous POD pages, but this is a more comprehensive conversion. This is only the first step, and this initial conversion has various problems. In addition, the file man pages that didn't have simple names have not been converted in this pass and will be added later. Some of the man pages have syntax problems and all of them have formatting errors. The next editing pass, coming shortly, will clean up most of the remaining mess.
257 lines
7.2 KiB
Plaintext
257 lines
7.2 KiB
Plaintext
=head1 NAME
|
|
|
|
backup readlabel - Reads and displays a tape's label
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
B<backup readlabel> [-portoffset <I<TC port offset>>]
|
|
[B<-localauth>] [B<-cell> <I<cell name>>] [B<-help>]
|
|
|
|
B<backup rea> [B<-p> <I<TC port offset>>] [B<-l>] [B<-c> <I<cell name>>] [-h]
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
The backup readlabel command displays information from the
|
|
magnetic tape label of a tape. The information includes the tape's
|
|
name (either a I<permanent name>, or an I<AFS tape name> that
|
|
reflects the tape's contents in a prescribed format) and its
|
|
capacity.
|
|
|
|
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 readlabel> command reads the
|
|
label information from the first 16 KB block in the backup data file listed
|
|
for that port offset in the Tape Coordinator's
|
|
B</usr/afs/backup/tapeconfig> file, rather than from the beginning of
|
|
a tape.
|
|
|
|
The Tape Coordinator's default response to this command is to access
|
|
the tape by invoking the B<MOUNT> instruction in the local
|
|
B</usr/afs/backup/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.
|
|
|
|
=head1 OPTIONS
|
|
|
|
=over 4
|
|
|
|
=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
|
|
|
|
Output from this command appears in both the shell window where the command
|
|
is issued, and in the Tape Coordinator window.
|
|
|
|
If the tape is unlabeled or if the specified tape device is empty, the
|
|
output reads
|
|
|
|
Failed to read tape label.
|
|
|
|
Otherwise, the output in the shell window has the following format:
|
|
|
|
Tape read was labelled: I<tape name> (I<dump id>)
|
|
size: I<size> Kbytes
|
|
|
|
where I<tape name> is the permanent name if the tape has one, or the
|
|
AFS tape name otherwise. The I<dump ID> is dump ID of the initial
|
|
dump on the tape, and I<size> is the recorded capacity of the tape in
|
|
kilobytes.
|
|
|
|
The output in the Tape Coordinator windows is bounded by an underlined
|
|
C<Tape> C<label> header at the top, and the following string
|
|
at the bottom:
|
|
|
|
-- End of tape label --
|
|
|
|
In between are lines reporting the following information:
|
|
|
|
=over 4
|
|
|
|
=item C<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.
|
|
|
|
=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> or B<backup savedb> 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>B<.>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 to which this tape belongs; 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<Ubik.db.dump.>I<tape_index> if the
|
|
tape contains a dump of the Backup Database, created with the B<backup
|
|
savedb> command. The I<tape_index> is the ordinal 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 path
|
|
>
|
|
|
|
The dump level of the initial dump in the dump set
|
|
|
|
=item C<dump 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 message C<ReadLabel: Finished> indicates the completion
|
|
of the output.
|
|
|
|
=head1 EXAMPLES
|
|
|
|
The following example shows the output for the tape with permanent name
|
|
B<oct.guest.dump> and capacity 2 MB, expressed in
|
|
kilobyte units (2097152 equals 2 times 10242).
|
|
|
|
% backup readlabel -portoffset 6
|
|
Tape read was labelled: oct.guest.dump (907215000)
|
|
size: 2097152 Kbytes
|
|
|
|
The output in the Tape Coordinator window reads:
|
|
|
|
Tape label
|
|
----------
|
|
tape name = oct.guest.dump
|
|
AFS tape name = guests.monthly.3
|
|
creationTime = Thu Oct 1 00:10:00 1998
|
|
cell = abc.com
|
|
size = 2097152 Kbytes
|
|
dump path = /monthly
|
|
dump id = 907215000
|
|
useCount = 5
|
|
---- End of tape label ----
|
|
|
|
The following example is for a tape that does not have a permanent
|
|
tape.
|
|
|
|
% backup readlabel -portoffset 6
|
|
Tape read was labelled: guests.monthly.2 (909899900)
|
|
size: 2097152 Kbytes
|
|
|
|
The output in the Tape Coordinator window reads:
|
|
|
|
Tape label
|
|
----------
|
|
tape name = <NULL>
|
|
AFS tape name = guests.monthly.2
|
|
creationTime = Sun Nov 1 00:58:20 1998
|
|
cell = abc.com
|
|
size = 2097152 Kbytes
|
|
dump path = /monthly
|
|
dump id = 909899900
|
|
useCount = 1
|
|
---- End of tape label ----
|
|
|
|
=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_labeltape(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.
|