=head1 NAME
-backup labeltape - Creates the magnetic label on a tape
+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]
+=for html
+<div class="synopsis">
-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]
+B<backup labeltape> S<<< [B<-name> <I<AFS tape name, defaults to NULL>>] >>>
+ S<<< [B<-size> <I<tape size in Kbytes, defaults to size in tapeconfig>>] >>>
+ S<<< [B<-portoffset> <I<TC port offset>>] >>>
+ S<<< [B<-pname> <I<permanent tape name>>] >>>
+ [B<-localauth>] S<<< [B<-cell> <I<cell name>>] >>> [B<-help>]
+
+B<backup la> S<<< [B<-n> <I<AFS tape name, defaults to NULL>>] >>>
+ S<<< [B<-s> <I<tape size in Kbytes, defaults to size in tapeconfig>>] >>>
+ S<<< [B<-po> <I<TC port offset>>] >>>
+ S<<< [B<-pn> <I<permanent tape name>>] >>>
+ [B<-l>] S<<< [B<-c> <I<cell name>>] >>> [B<-h>]
+
+=for html
+</div>
=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.)
+The B<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 C<FILE YES> instruction appears in the
+F</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
+F</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
+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 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:
+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
+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 L</OPTIONS>. 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 tape 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.
+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 F</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 F</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 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 -name
+=item B<-name> <I<AFS tape 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:
+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>
+ <volume_set_name>.<dump_level_name>.<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.
+operation. The <volume_set_name> must match the volume set name of the
+initial dump to be written to the tape, <dump_level_name> must match the
+last element of the dump level pathname at which the volume set will be
+dumped, and <tape_index> indicates the order of the tape in the dump set
+(indexing begins with C<1>). To disable this type of name checking,
+include the C<NAME_CHECK NO> instruction in the F<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:
+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>
+ Ubik_db_dump.<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).
+where <tape_index> indicates the order of the tape in the set of tapes
+that house the Backup Database dump; indexing begins with C<1> (one).
-=item -size
+=item B<-size> <I<tape 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.
+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 C<k> or C<K> indicates kilobytes, C<m> or C<M>
+indicates megabytes, and C<g> or C<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
+System records the capacity that is associated with the specified port
+offset in the F</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.
+B<-size> argument is provided on a future issuance of the command.
-=item -portoffset
+=item B<-portoffset> <I<TC port offset>>
Specifies the port offset number of the Tape Coordinator handling the tape
for this operation.
-=item -pname
+=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
+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.
+Include this argument or the B<-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
+=item B<-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.
+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 -cell
+=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 B<backup> reference page.
+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 -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+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:
+The following command records the AFS tape name C<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.
+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
=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.
+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<CFG_I<device_name>(1)>,
-L<backup(1)>,
-L<backup_readlabel(1)>,
-L<butc(1)>
+L<butc(5)>,
+L<backup(8)>,
+L<backup_readlabel(8)>,
+L<butc(8)>
=head1 COPYRIGHT
git://git.openafs.org / openafs.git / blobdiff