Provided by: openafs-client_1.4.1-2_i386 bug

NAME

       backup labeltape - Creates the magnetic label on a tape

SYNOPSIS

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

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

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 permanent name, or an AFS tape name that reflects the
       tape’s contents in a prescribed format) and its capacity.

       (If the FILE YES instruction appears in the
       /var/lib/openafs/backup/CFG_device_name file on the Tape Coordinator
       machine associated with the specified port offset, then the 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
       /var/lib/openafs/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 -pname argument is again included on the 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 -name
       argument, but not both. If this argument is included, the AFS tape name
       is set to < <NULL >>.  The permanent name is set to < <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 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 backup commands. The permanent name appears
       in the tape name field of the output from the backup readlabel command.

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

       The backup command interpreter does not accept the -name argument if
       the tape already has a permanent name. To erase a tape’s permanent
       name, provide a null value to the -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 -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
       /var/lib/openafs/backup/tapeconfig file on the Tape Coordinator
       machine. Subsequently, the value in the size field persists until the
       -size argument is again included on the backup labeltape command.

       To determine how much data can be written to a tape during a backup
       dump or 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 /var/lib/openafs/backup/tapeconfig file, if
       the tape was never labeled). For further description, see the backup
       dump reference page.

       The Tape Coordinator’s default response to this command is to access
       the tape by invoking the MOUNT instruction in the local
       /var/lib/openafs/backup/CFG_device_name file, or by prompting the
       backup operator to insert the tape if there is no MOUNT instruction.
       However, if the AUTOQUERY NO instruction appears in the CFG_device_name
       file, or if the issuer of the butc command included the -noautoquery
       flag, the Tape Coordinator instead expects the tape to be in the device
       already.  If it is not, the Tape Coordinator invokes the MOUNT
       instruction or prompts the operator.

OPTIONS

       -name <AFS tape name>
           Specifies the AFS tape name to record on the label. Include this
           argument or the -pname argument, but not both. If this argument is
           omitted, the AFS tape name is set to < <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 1). To disable this
           type of name checking, include the NAME_CHECK NO instruction in the
           CFG_device_name file.

           For the tape to be acceptable for use in a future backup savedb
           operation, the value specified for the -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 1
           (one).

       -size <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 k or K indicates kilobytes, m or
           M indicates megabytes, and g or 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 /var/lib/openafs/backup/tapeconfig
           file on the Tape Coordinator machine. The value recorded the first
           time then persists until the -size argument is provided on a future
           issuance of the command.

       -portoffset <TC port offset>
           Specifies the port offset number of the Tape Coordinator handling
           the tape for this operation.

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

       -localauth
           Constructs a server ticket using a key from the local
           /etc/openafs/server/KeyFile file. The backup command interpreter
           presents it to the Backup Server, Volume Server and VL Server
           during mutual authentication. Do not combine this flag with the
           -cell argument. For more details, see the backup(8) manpage.

       -cell <cell name>
           Names the cell in which to run the command. Do not combine this
           argument with the -localauth flag. For more details, see the
           backup(8) manpage.

       -help
           Prints the online help for this command. All other valid options
           are ignored.

EXAMPLES

       The following command records the AFS tape name 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 < <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

PRIVILEGE REQUIRED

       The issuer must be listed in the /etc/openafs/server/UserList file on
       every machine where the Backup Server is running, or must be logged
       onto a server machine as the local superuser root if the -localauth
       flag is included.

SEE ALSO

       the butc(5) manpage, the backup(8) manpage, the backup_readlabel(8)
       manpage, the butc(8) manpage

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.