doc/man-pages/pod/backup_readlabel.pod

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