openafs/doc/man-pages/pod8/backup_labeltape.pod

=head1 NAME

backup labeltape - Creates the magnetic label on a tape

=head1 SYNOPSIS

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

B<backup la> [-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>>]  [-pn <I<permanent tape name>>]
          [B<-l>]  [B<-c> <I<cell name>>]  [-h]

=head1 DESCRIPTION

The 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 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
B<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 -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
B<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<<NULL>>.
The permanent name is set to C<<NULL>> 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 B<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 B<backup> commands. The permanent name appears in
the C<tape> C<name> field of the output from the B<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
B<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<<NULL>>, but the Backup
System automatically assigns the appropriate name when the tape is used in a
future B<backup dump> or B<backup savedb> operation.
The AFS tape name appears in the C<AFS> C<tape>
C<name> field of the output from the B<backup readlabel> and
B<backup scantape> commands.

The 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 B<backup labeltape>
command.

To determine how much data can be written to a tape during a backup
dump or B<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 B<backup
dump> 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 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 -name

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<<NULL>>.
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 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 backup savedb
operation, the value specified for the B<-name> argument must have the
following format:

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

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

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

=item -pname

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 -name argument, but not
both. If this argument is provided, the AFS tape name is set to
C<<NULL>>. If this argument is omitted, any existing
permanent name is retained.

=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 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<<NULL>> 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 /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<CFG_I<device_name>(1)>,
L<backup(1)>,
L<backup_readlabel(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.