=head1 NAME

backup_readlabel - Reads and displays a tape's label

=head1 SYNOPSIS

=for html
<div class="synopsis">

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

B<backup rea> 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 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 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 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 F</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 C<MOUNT> instruction in the local
F</usr/afs/backup/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.

=head1 OPTIONS

=over 4

=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

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: <tape name> (<dump id>)
        size: <size> Kbytes

where <tape name> is the permanent name if the tape has one, or the AFS
tape name otherwise. The <dump ID> is dump ID of the initial dump on the
tape, and <size> is the recorded capacity of the tape in kilobytes.

The output in the Tape Coordinator windows is bounded by an underlined
C<Tape 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 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 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 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 message C<ReadLabel: Finished> indicates the completion of the output.

=head1 EXAMPLES

The following example shows the output for the tape with permanent name
C<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 = example.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 = example.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 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_labeltape(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.
