mirror of
https://git.openafs.org/openafs.git
synced 2025-01-19 07:20:11 +00:00
6770c6c411
"local" links to section heads inside the same pod page should be written L</OPTIONS> instead of L<OPTIONS>. the other broken links are assorted typos and capitalization changes. Change-Id: I18b57a81d984501309e96dcd4c04582e744a6db2 Reviewed-on: http://gerrit.openafs.org/4831 Tested-by: BuildBot <buildbot@rampaginggeek.com> Reviewed-by: Derrick Brashear <shadow@dementia.org> Reviewed-by: Ken Dreyer <kdreyer@usgs.gov> Reviewed-by: Jeffrey Altman <jaltman@openafs.org>
222 lines
9.4 KiB
Plaintext
222 lines
9.4 KiB
Plaintext
=head1 NAME
|
|
|
|
backup_labeltape - Creates the magnetic label on a tape
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
=for html
|
|
<div class="synopsis">
|
|
|
|
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 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 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
|
|
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 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 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:
|
|
|
|
<volume_set_name>.<dump_level_name>.<tape_index>
|
|
|
|
for the tape to be acceptable for use in a future backup dump
|
|
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:
|
|
|
|
Ubik_db_dump.<tape_index>
|
|
|
|
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 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 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 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.
|
|
|
|
=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<< <NULL> >>. If this
|
|
argument is omitted, any existing permanent name is retained.
|
|
|
|
=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 EXAMPLES
|
|
|
|
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.
|
|
|
|
% 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 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_readlabel(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.
|