backup_readlabel - Reads and displays a tape's label

       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                                            2025-03-21                                BACKUP_READLABEL(8)

       The backupreadlabel command displays information from the magnetic tape label of a tape. The information
       includes the tape's name (either a permanentname, or an AFStapename 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 associated with
       the specified port offset, then the backupreadlabel 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/lib/openafs/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/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.

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

       backup_readlabel - Reads and displays a tape's label

-portoffset <TCportoffset>
           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/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 <cellname>
           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.

       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 backuplabeltape 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 backupdump or backupsavedb  operation,  or  the
           operator can assign it with the -name argument to the backuplabeltape command.

           •   volume_set_name.dump_level_name.tape_index, if the tape contains volume data. The volume_set_name
               is  the  name  of the volume set that was dumped to create the initial dump in the dump set of to
               which this tape belongs; dump_level_name is the last pathname element of the dump level at  which
               the  initial dump was backed up; and tape_index is the numerical position of the tape in the dump
               set.

           •   "Ubik.db.dump."tape_index if the tape contains a dump of the Backup Database,  created  with  the
               backupsavedb command. The tape_index is the ordinal of the tape in the dump set.

           •   "<NULL>"  if  the  tape has no AFS tape name. This is normally the case if the -name argument was
               not included the last time the backuplabeltape command was used on this tape, and  no  data  has
               been written to it since.

       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 backuplabeltape command or derived from the
           /var/lib/openafs/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.

       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.

butc(5), backup(8), backup_labeltape(8), butc(8)

backupreadlabel [-portoffset <TCportoffset>]
           [-localauth] [-cell <cellname>] [-help]

       backuprea [-p <TCportoffset>]
           [-l] [-c <cellname>] [-h]