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 "OPTIONS".  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 backup(8).

       -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 backup(8).

       -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

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

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.

OpenAFS                                            2019-11-22                                BACKUP_LABELTAPE(8)