Section: AFS Command Reference (8)
Updated: OpenAFS


backup labeltape - Creates the magnetic label on a tape 


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] 


The backup labeltape command creates a magnetic label, readable by theBackup System, at the beginning of a tape. The label records the tape'sname (either a permanent name, or an AFS tape name that reflects thetape's contents in a prescribed format) and its capacity.

(If the FILE YES instruction appears in the/usr/afs/backup/CFG_device_name file on the Tape Coordinator machineassociated with the specified port offset, then the backup commandwrites label information to the first 16 KB block in the backup data filelisted for that port offset in the Tape Coordinator's/usr/afs/backup/tapeconfig file, rather than at the beginning of atape. 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 makesthe data unusable, because the command removes the Backup Database recordof the complete dump set of which the tape is a part. Use this command toenable recycling of a tape that contains unexpired dumps that are notactually still needed.

To write a permanent name on the label, include the -pname argument tospecify a string of up to 32 characters. The permanent name persists untilthe -pname argument is again included on the backup labeltapecommand, regardless of the tape's contents and of how often the tape isotherwise relabeled or recycled. Include this argument or the -nameargument, but not both. If this argument is included, the AFS tape name isset to < <NULL >>. The permanent name is set to < <NULL >> if thisargument is omitted and no permanent name already exists.

The issuer must ensure that a permanent name is unique among the tapesused for AFS backup in the cell, because the backup command interpreterdoes not verify that another tape does not already have the same permanentname. When a tape has a permanent name, the Backup System uses it insteadof the AFS tape name in most prompts and when referring to the tape inoutput from backup commands. The permanent name appears in the tapename field of the output from the backup readlabel command.

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

The backup command interpreter does not accept the -name argument ifthe tape already has a permanent name. To erase a tape's permanent name,provide a null value to the -pname argument by issuing the followingcommand:

   % backup labeltape -pname ""
To record the tape's capacity on the label, specify a number of kilobytesas the -size argument. If the argument is omitted the first time a tapeis labeled, the Backup System records the default tape capacity recordedfor the specified port offset in the /usr/afs/backup/tapeconfig file onthe Tape Coordinator machine. Subsequently, the value in the size fieldpersists until the -size argument is again included on the backuplabeltape command.

To determine how much data can be written to a tape during a backup dumpor backup savedb operation, the Tape Coordinator reads the capacityrecorded on the tape's label (or uses the value associated with its portoffset in the /usr/afs/backup/tapeconfig file, if the tape was neverlabeled). For further description, see the backup dump reference page.

The Tape Coordinator's default response to this command is to access thetape by invoking the MOUNT instruction in the local/usr/afs/backup/CFG_device_name file, or by prompting the backupoperator to insert the tape if there is no MOUNT instruction. However,if the AUTOQUERY NO instruction appears in the CFG_device_namefile, or if the issuer of the butc command included the -noautoqueryflag, the Tape Coordinator instead expects the tape to be in the devicealready. If it is not, the Tape Coordinator invokes the MOUNTinstruction or prompts the operator. 


-name <AFS tape name>
Specifies the AFS tape name to record on the label. Include this argumentor the -pname argument, but not both. If this argument is omitted, theAFS tape name is set to < <NULL >>. If this argument is provided, itmust have the following format:

for the tape to be acceptable for use in a future backup dumpoperation. The <volume_set_name> must match the volume set name of theinitial dump to be written to the tape, <dump_level_name> must match thelast element of the dump level pathname at which the volume set will bedumped, 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_namefile.

For the tape to be acceptable for use in a future backup savedb operation,the value specified for the -name argument must have the followingformat:

where <tape_index> indicates the order of the tape in the set of tapesthat house the Backup Database dump; indexing begins with 1 (one).
-size <tape size>
Specifies the tape capacity to record on the label. Provide an integervalue followed by a letter that indicates units, with no interveningspace. A unit value of k or K indicates kilobytes, m or Mindicates megabytes, and g or G indicates gigabytes. If the unitsletter is omitted, the default is kilobytes.

If this argument is omitted the first time a tape is labeled, the BackupSystem records the capacity that is associated with the specified portoffset in the /usr/afs/backup/tapeconfig file on the Tape Coordinatormachine. 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 tapefor this operation.
-pname <permanent tape name>
Specifies the permanent name to record on the label. It can be up to 32characters in length, and include any alphanumeric characters. Avoidmetacharacters that have a special meaning to the shell, to avoid havingto mark them as literal in commands issued at the shell prompt.

Include this argument or the -name argument, but not both. If thisargument is provided, the AFS tape name is set to < <NULL >>. If thisargument is omitted, any existing permanent name is retained.

Constructs a server ticket using a key from the local/usr/afs/etc/KeyFile file. The backup command interpreter presentsit to the Backup Server, Volume Server and VL Server during mutualauthentication. Do not combine this flag with the -cell argument. Formore details, see the backup(8) manpage.
-cell <cell name>
Names the cell in which to run the command. Do not combine this argumentwith the -localauth flag. For more details, see the backup(8) manpage.
Prints the online help for this command. All other valid options areignored.


The following command records the AFS tape name user.monthly.1 on thelabel 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 acapacity of 2 GB on the label of the tape in the device with port offset4. They set the AFS tape name to < <NULL >> and leave the permanentname unchanged.

   % backup labeltape -size 2g -portoffset 4   % backup labeltape -size 2048M -portoffset 4   % backup labeltape -size 2097152 -portoffset 4


The issuer must be listed in the /usr/afs/etc/UserList file on everymachine where the Backup Server is running, or must be logged onto aserver machine as the local superuser root if the -localauth flag isincluded. 


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


IBM Corporation 2000. <> All Rights Reserved.

This documentation is covered by the IBM Public License Version 1.0. It wasconverted from HTML to POD by software written by Chas Williams and RussAllbery, based on work by Alf Wachsmann and Elizabeth Cassell.




This document was created byman2html,using the manual pages.