=head1 NAME

backup labeltape - Creates the magnetic label on a tape

=head1 SYNOPSIS

backup labeltape [B<-name> I<AFS tape name, defaults to NULL>]
[B<-size> I<tape size in Kbytes, defaults to size in tapeconfig>]
[B<-portoffset> I<TC port offset>]
[B<-pname> I<permanent tape name>]
[B<-localauth>]  [B<-cell> I<cell name>]  [B<-help>]

backup la [B<-n> I<AFS tape name, defaults to NULL>]
[B<-s> I<tape size in Kbytes, defaults to size in tapeconfig>]
[B<-po> I<TC port offset>]  [B<-pn> I<permanent tape name>]
[B<-l>]  [B<-c> I<cell name>]  [B<-h>]

=head1 DESCRIPTION

The C<backup labeltape> command creates a magnetic label, readable by the
Backup System, at the beginning of a tape. The label records 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 B<FILE YES> instruction appears in the
B</usr/afs/backup/CFG_>I<device_name> file on the Tape Coordinator machine
associated with the specified port offset, then the C<backup> command
writes label information to 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 at the beginning of 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.)

Relabeling a tape that already contains AFS backup data effectively
makes the data unusable, because the command removes the Backup
Database record of the complete dump set of which the tape is a part.
Use this command to enable recycling of a tape that contains unexpired
dumps that are not actually still needed.

To write a permanent name on the label, include the B<-pname> argument to
specify a string of up to 32 characters. The permanent name persists
until the B<-pname> argument is again included on the C<backup labeltape>
command, regardless of the tape's contents and of how often the tape
is otherwise relabeled or recycled. Include this argument or the B<-name>
argument, but not both. If this argument is included, the AFS tape
name is set to C<E<lt>NULLE<gt>>. The permanent name is set to C<E<lt>NULLE<gt>> if this
argument is omitted and no permanent name already exists.

The issuer must ensure that a permanent name is unique among the tapes
used for AFS backup in the cell, because the C<backup> command
interpreter does not verify that another tape does not already have
the same permanent name. When a tape has a permanent name, the Backup
System uses it instead of the AFS tape name in most prompts and when
referring to the tape in output from C<backup> commands. The permanent
name appears in the C<tape name> field of the output from the C<backup
readlabel> command.

To write an AFS tape name on the label, provide a value for the B<-name>
argument in the required format described in the L</"OPTIONS"> section.
Include the B<-name> argument or the B<-pname> argument, but not both. If
this argument is omitted, the AFS tape name is set to C<E<lt>NULLE<gt>>, but the
Backup System automatically assigns the appropriate name when the tape
is used in a future C<backup dump> or C<backup savedb> operation. The AFS
tape name appears in the AFS C<tape name> field of the output from the
C<backup readlabel> and C<backup scantape> commands.

The C<backup> command interpreter does not accept the B<-name> argument if
the tape already has a permanent name. To erase a tape's permanent
name, provide a null value to the B<-pname> argument by issuing the
following command:

   % backup labeltape -pname ""

To record the tape's capacity on the label, specify a number of
kilobytes as the B<-size> argument. If the argument is omitted the first
time a tape is labeled, the Backup System records the default tape
capacity recorded for the specified port offset in the
B</usr/afs/backup/tapeconfig> file on the Tape Coordinator machine.
Subsequently, the value in the size field persists until the B<-size>
argument is again included on the C<backup labeltape> command.

To determine how much data can be written to a tape during a C<backup
dump> or C<backup savedb> operation, the Tape Coordinator reads the
capacity recorded on the tape's label (or uses the value associated
with its port offset in the B</usr/afs/backup/tapeconfig> file, if the
tape was never labeled). For further description, see the L<backup_dump(1)>
reference page.

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 C<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 B<-name> I<AFS tape name, defaults to NULL>

Specifies the AFS tape name to record on the label. Include
this argument or the B<-pname> argument, but not both. If this
argument is omitted, the AFS tape name is set to C<E<lt>NULLE<gt>>. If
this argument is provided, it must have the following format:

I<volume_set_name>.I<dump_level_name>.I<tape_index>

for the tape to be acceptable for use in a future C<backup dump>
operation. The I<volume_set_name> must match the volume set name
of the initial dump to be written to the tape, I<dump_level_name>
must match the last element of the dump level pathname at which
the volume set will be dumped, and I<tape_index> indicates the
order of the tape in the dump set (indexing begins with B<1>). To
disable this type of name checking, include the B<NAME_CHECK NO>
instruction in the B<CFG_>I<device_name> file.

For the tape to be acceptable for use in a future C<backup savedb>
operation, the value specified for the B<-name> argument must have
the following format:

I<Ubik_db_dump>.I<tape_index>

where I<tape_index> indicates the order of the tape in the set of
tapes that house the Backup Database dump; indexing begins with
1 (one).

=item B<-size> I<tape size in Kbytes, defaults to size in tapeconfig>

Specifies the tape capacity to record on the label. Provide an
integer value followed by a letter that indicates units, with
no intervening space. A unit value of B<k> or B<K> indicates
kilobytes, B<m> or B<M> indicates megabytes, and B<g> or B<G> indicates
gigabytes. If the units letter is omitted, the default is
kilobytes.

If this argument is omitted the first time a tape is labeled,
the Backup System records the capacity that is associated with
the specified port offset in the B</usr/afs/backup/tapeconfig>
file on the Tape Coordinator machine. The value recorded the
first time then persists until the B<-size> argument is provided
on a future issuance of the command.

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

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

=item B<-pname> I<permanent tape name>

Specifies the permanent name to record on the label. It can be
up to 32 characters in length, and include any alphanumeric
characters. Avoid metacharacters that have a special meaning to
the shell, to avoid having to mark them as literal in commands
issued at the shell prompt.

Include this argument or the B<-name> argument, but not both. If
this argument is provided, the AFS tape name is set to C<E<lt>NULLE<gt>>.
If this argument is omitted, any existing permanent name is
retained.

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

The following command records the AFS tape name B<user.monthly.1> on the
label of the tape in the device with port offset 3:

    backup labeltape -name user.monthly.1 -portoffset 3

The following three commands are equivalent in effect: they all record
a capacity of 2 GB on the label of the tape in the device with port
offset 4. They set the AFS tape name to C<E<lt>NULLE<gt>> and leave the permanent
name unchanged.

    backup labeltape -size 2g -portoffset 4

    backup labeltape -size 2048M -portoffset 4

    backup labeltape -size 2097152 -portoffset 4

=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 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<CFG_device_name(1)>,
L<backup(1)>,
L<backup_readlabel(1)>,
L<butc(1)>

=cut
