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