doc/man-pages/pod8/backup_readlabel.pod

   1 =head1 NAME
   2
   3 backup_readlabel - Reads and displays a tape's label
   4
   5 =head1 SYNOPSIS
   6
   7 =for html
   8 <div class="synopsis">
   9
  10 B<backup readlabel> S<<< [B<-portoffset> <I<TC port offset>>] >>>
  11     [B<-localauth>] S<<< [B<-cell> <I<cell name>>] >>> [B<-help>]
  12
  13 B<backup rea> S<<< [B<-p> <I<TC port offset>>] >>>
  14     [B<-l>] S<<< [B<-c> <I<cell name>>] >>> [B<-h>]
  15
  16 =for html
  17 </div>
  18
  19 =head1 DESCRIPTION
  20
  21 The B<backup readlabel> command displays information from the magnetic
  22 tape label of a tape. The information includes the tape's name (either a
  23 I<permanent name>, or an I<AFS tape name> that reflects the tape's
  24 contents in a prescribed format) and its capacity.
  25
  26 If the C<FILE YES> instruction appears in the
  27 F</usr/afs/backup/CFG_I<device_name>> file associated with the specified
  28 port offset, then the B<backup readlabel> command reads the label
  29 information from the first 16 KB block in the backup data file listed for
  30 that port offset in the Tape Coordinator's F</usr/afs/backup/tapeconfig>
  31 file, rather than from the beginning of a tape.
  32
  33 The Tape Coordinator's default response to this command is to access the
  34 tape by invoking the C<MOUNT> instruction in the local
  35 F</usr/afs/backup/CFG_I<device_name>> file, or by prompting the backup
  36 operator to insert the tape if there is no C<MOUNT> instruction. However,
  37 if the C<AUTOQUERY NO> instruction appears in the F<CFG_I<device_name>>
  38 file, or if the issuer of the B<butc> command included the B<-noautoquery>
  39 flag, the Tape Coordinator instead expects the tape to be in the device
  40 already.  If it is not, the Tape Coordinator invokes the C<MOUNT>
  41 instruction or prompts the operator.
  42
  43 =head1 OPTIONS
  44
  45 =over 4
  46
  47 =item B<-portoffset> <I<TC port offset>>
  48
  49 Specifies the port offset number of the Tape Coordinator handling the
  50 tapes for this operation.
  51
  52 =item B<-localauth>
  53
  54 Constructs a server ticket using a key from the local
  55 F</usr/afs/etc/KeyFile> file. The B<backup> command interpreter presents
  56 it to the Backup Server, Volume Server and VL Server during mutual
  57 authentication. Do not combine this flag with the B<-cell> argument. For
  58 more details, see L<backup(8)>.
  59
  60 =item B<-cell> <I<cell name>>
  61
  62 Names the cell in which to run the command. Do not combine this argument
  63 with the B<-localauth> flag. For more details, see L<backup(8)>.
  64
  65 =item B<-help>
  66
  67 Prints the online help for this command. All other valid options are
  68 ignored.
  69
  70 =back
  71
  72 =head1 OUTPUT
  73
  74 Output from this command appears in both the shell window where the
  75 command is issued, and in the Tape Coordinator window.
  76
  77 If the tape is unlabeled or if the specified tape device is empty, the
  78 output reads
  79
  80    Failed to read tape label.
  81
  82 Otherwise, the output in the shell window has the following format:
  83
  84    Tape read was labelled: <tape name> (<dump id>)
  85         size: <size> Kbytes
  86
  87 where <tape name> is the permanent name if the tape has one, or the AFS
  88 tape name otherwise. The <dump ID> is dump ID of the initial dump on the
  89 tape, and <size> is the recorded capacity of the tape in kilobytes.
  90
  91 The output in the Tape Coordinator windows is bounded by an underlined
  92 C<Tape label> header at the top, and the following string at the bottom:
  93
  94    -- End of tape label --
  95
  96 In between are lines reporting the following information:
  97
  98 =over 4
  99
 100 =item tape name
 101
 102 The permanent name assigned by using the -pname argument of the B<backup
 103 labeltape> command. This name remains on the tape until that argument is
 104 used again, no matter how many times the tape is recycled or otherwise
 105 relabeled. If the tape does not have a permanent name, the value C<<
 106 <NULL> >> appears in this field.
 107
 108 =item AFS tape name
 109
 110 A tape name in one of the following prescribed formats. The Backup System
 111 automatically writes the appropriate AFS tape name to the label as part of
 112 a B<backup dump> or B<backup savedb> operation, or the operator can assign
 113 it with the B<-name> argument to the B<backup labeltape> command.
 114
 115 =over 4
 116
 117 =item *
 118
 119 I<volume_set_name>B<.>I<dump_level_name>.I<tape_index>, if the tape
 120 contains volume data. The I<volume_set_name> is the name of the volume set
 121 that was dumped to create the initial dump in the dump set of to which
 122 this tape belongs; I<dump_level_name> is the last pathname element of the
 123 dump level at which the initial dump was backed up; and I<tape_index> is
 124 the numerical position of the tape in the dump set.
 125
 126 =item *
 127
 128 C<Ubik.db.dump.>I<tape_index> if the tape contains a dump of the Backup
 129 Database, created with the B<backup savedb> command. The I<tape_index> is
 130 the ordinal of the tape in the dump set.
 131
 132 =item *
 133
 134 C<< <NULL> >> if the tape has no AFS tape name. This is normally the case
 135 if the B<-name> argument was not included the last time the B<backup
 136 labeltape> command was used on this tape, and no data has been written to
 137 it since.
 138
 139 =back
 140
 141 =item creationTime
 142
 143 The date and time at which the Backup System started performing the dump
 144 operation that created the initial dump.
 145
 146 =item cell
 147
 148 The cell in which the dump set was created. This is the cell whose Backup
 149 Database contains a record of the dump set.
 150
 151 =item size
 152
 153 The tape's capacity (in kilobytes) as recorded on the label, rather than
 154 the amount of data on the tape. The value is assigned by the B<-size>
 155 argument to the B<backup labeltape> command or derived from the
 156 F</usr/afs/backup/tapeconfig> file on the Tape Coordinator machine, not
 157 from a measurement of the tape.
 158
 159 =item dump path
 160
 161 The dump level of the initial dump in the dump set.
 162
 163 =item dump id
 164
 165 The dump ID number of the initial dump in the dump set, as recorded in the
 166 Backup Database.
 167
 168 =item useCount
 169
 170 The number of times a dump has been written to the tape, or it has been
 171 relabeled.
 172
 173 =back
 174
 175 The message C<ReadLabel: Finished> indicates the completion of the output.
 176
 177 =head1 EXAMPLES
 178
 179 The following example shows the output for the tape with permanent name
 180 C<oct.guest.dump> and capacity 2 MB, expressed in kilobyte units (2097152
 181 equals 2 times 10242).
 182
 183    % backup readlabel -portoffset 6
 184    Tape read was labelled: oct.guest.dump (907215000)
 185         size: 2097152 Kbytes
 186
 187 The output in the Tape Coordinator window reads:
 188
 189    Tape label
 190    ----------
 191    tape name = oct.guest.dump
 192    AFS tape name = guests.monthly.3
 193    creationTime = Thu Oct 1 00:10:00 1998
 194    cell = abc.com
 195    size = 2097152 Kbytes
 196    dump path = /monthly
 197    dump id = 907215000
 198    useCount = 5
 199    ---- End of tape label ----
 200
 201 The following example is for a tape that does not have a permanent tape.
 202
 203    % backup readlabel -portoffset 6
 204    Tape read was labelled: guests.monthly.2 (909899900)
 205         size: 2097152 Kbytes
 206
 207 The output in the Tape Coordinator window reads:
 208
 209    Tape label
 210    ----------
 211    tape name = <NULL>
 212    AFS tape name = guests.monthly.2
 213    creationTime = Sun Nov 1 00:58:20 1998
 214    cell = abc.com
 215    size = 2097152 Kbytes
 216    dump path = /monthly
 217    dump id = 909899900
 218    useCount = 1
 219    ---- End of tape label ----
 220
 221 =head1 PRIVILEGE REQUIRED
 222
 223 The issuer must be listed in the F</usr/afs/etc/UserList> file on every
 224 machine where the Backup Server is running, or must be logged onto a
 225 server machine as the local superuser C<root> if the B<-localauth> flag is
 226 included.
 227
 228 =head1 SEE ALSO
 229
 230 L<butc(5)>,
 231 L<backup(8)>,
 232 L<backup_labeltape(8)>,
 233 L<butc(8)>
 234
 235 =head1 COPYRIGHT
 236
 237 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
 238
 239 This documentation is covered by the IBM Public License Version 1.0.  It was
 240 converted from HTML to POD by software written by Chas Williams and Russ
 241 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.