NAME

backup_readlabel - Reads and displays a tape's label

SYNOPSIS

backup readlabel [-portoffset <TC port offset>] [-localauth] [-butc_noauth] [-cell <cell name>] [-config <configuration file>] [-help]

DESCRIPTION

The backup readlabel command displays information from the magnetic tape label of a tape. The information includes 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/yfs/backup/CFG_device_name file associated with the specified port offset, then the backup readlabel command reads the label information from the first 16 KB block in the backup data file listed for that port offset in the Tape Coordinator's /var/yfs/backup/tapeconfig file, rather than from the beginning of a tape.

The Tape Coordinator's default response to this command is to access the tape by invoking the MOUNT instruction in the local /var/yfs/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

-portoffset <TC port offset>

Specifies the port offset number of the Tape Coordinator handling the tapes for this operation.

-localauth

Constructs a server ticket using a key from the local /etc/yfs/server/KeyFileExt 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).

-butc_noauth

Assigns the unprivileged identity anonymous to the issuer for all connections to Tape Controllers butc. This option should only be used when the Tape Controller is incapable of authenticated connections.

-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).

-config <configuration file>

Sets the location of the configuration file to be used. The default file is /etc/yfs/yfs-client.conf.

-help

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

OUTPUT

Output from this command appears in both the shell window where the command is issued, and in the Tape Coordinator window.

If the tape is unlabeled or if the specified tape device is empty, the output reads

   Failed to read tape label.

Otherwise, the output in the shell window has the following format:

   Tape read was labelled: <tape name> (<dump id>)
        size: <size> Kbytes

where <tape name> is the permanent name if the tape has one, or the AFS tape name otherwise. The <dump ID> is dump ID of the initial dump on the tape, and <size> is the recorded capacity of the tape in kilobytes.

The output in the Tape Coordinator windows is bounded by an underlined Tape label header at the top, and the following string at the bottom:

   -- End of tape label --

In between are lines reporting the following information:

tape name

The permanent name assigned by using the -pname argument of the backup labeltape command. This name remains on the tape until that argument is used again, no matter how many times the tape is recycled or otherwise relabeled. If the tape does not have a permanent name, the value <NULL> appears in this field.

AFS tape name

A tape name in one of the following prescribed formats. The Backup System automatically writes the appropriate AFS tape name to the label as part of a backup dump or backup savedb operation, or the operator can assign it with the -name argument to the backup labeltape command.

creationTime

The date and time at which the Backup System started performing the dump operation that created the initial dump.

cell

The cell in which the dump set was created. This is the cell whose Backup Database contains a record of the dump set.

size

The tape's capacity (in kilobytes) as recorded on the label, rather than the amount of data on the tape. The value is assigned by the -size argument to the backup labeltape command or derived from the /var/yfs/backup/tapeconfig file on the Tape Coordinator machine, not from a measurement of the tape.

dump path

The dump level of the initial dump in the dump set.

dump id

The dump ID number of the initial dump in the dump set, as recorded in the Backup Database.

useCount

The number of times a dump has been written to the tape, or it has been relabeled.

The message ReadLabel: Finished indicates the completion of the output.

EXAMPLES

The following example shows the output for the tape with permanent name oct.guest.dump and capacity 2 MB, expressed in kilobyte units (2097152 equals 2 times 10242).

   % backup readlabel -portoffset 6
   Tape read was labelled: oct.guest.dump (907215000)
        size: 2097152 Kbytes

The output in the Tape Coordinator window reads:

   Tape label
   ----------
   tape name = oct.guest.dump
   AFS tape name = guests.monthly.3
   creationTime = Thu Oct 1 00:10:00 1998
   cell = example.com
   size = 2097152 Kbytes
   dump path = /monthly
   dump id = 907215000
   useCount = 5
   ---- End of tape label ----

The following example is for a tape that does not have a permanent tape.

   % backup readlabel -portoffset 6
   Tape read was labelled: guests.monthly.2 (909899900)
        size: 2097152 Kbytes

The output in the Tape Coordinator window reads:

   Tape label
   ----------
   tape name = <NULL>
   AFS tape name = guests.monthly.2
   creationTime = Sun Nov 1 00:58:20 1998
   cell = example.com
   size = 2097152 Kbytes
   dump path = /monthly
   dump id = 909899900
   useCount = 1
   ---- End of tape label ----

PRIVILEGE REQUIRED

The issuer must be listed in the /etc/yfs/server/UserListExt file on every machine where the Backup Server is running, or must be logged onto a server with an account capable of reading the /etc/yfs/server/KeyFileExt file if the -localauth flag is included. =head1 SEE ALSO

butc(5), backup(8), backup_labeltape(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.

ACKNOWLEDGEMENTS

"AFS" is a registered mark of International Business Machines Corporation, used under license. (USPTO Registration 1598389)

"OpenAFS" is a registered mark of International Business Machines Corporation. (USPTO Registration 4577045)

The "AuriStor" name, log 'S' brand mark, and icon are registered marks of AuriStor, Inc. (USPTO Registrations 4849419, 4849421, and 4928460) (EUIPO Registration 015539653).

"Your File System" is a registered mark of AuriStor, Inc. (USPTO Registrations 4801402 and 4849418).

"YFS" and "AuriStor File System" are trademarks of AuriStor, Inc.