3 backup readlabel - Reads and displays a tape's label
7 backup readlabel [B<-portoffset> I<TC port offset>]
8 [B<-localauth>] [B<-cell> I<cell name>] [B<-help>]
10 backup rea [B<-p> I<TC port offset>] [B<-l>] [B<-c> I<cell name>] [B<-h>]
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.
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
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.
41 =item B<-portoffset> I<TC port offset>
43 Specifies the port offset number of the Tape Coordinator
44 handling the tapes for this operation.
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)>
55 =item B<-cell> I<cell name>
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.
63 Prints the online help for this command. All other valid
70 Output from this command appears in both the shell window where the
71 command is issued, and in the Tape Coordinator window.
73 If the tape is unlabeled or if the specified tape device is empty, the
76 Failed to read tape label.
78 Otherwise, the output in the shell window has the following format:
80 Tape read was labelled: tape name (dump id)
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.
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:
90 -- End of tape label --
92 In between are lines reporting the following information:
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.
104 =item B<AFS tape name>
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.
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.
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.
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.
139 =item B<creationTime>
141 The date and time at which the Backup System started performing
142 the dump operation that created the initial dump.
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.
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.
159 The dump level of the initial dump in the dump set
163 The dump ID number of the initial dump in the dump set, as
164 recorded in the Backup Database
168 The number of times a dump has been written to the tape, or it
173 The message C<ReadLabel: Finished> indicates the completion of the
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).
182 backup readlabel -portoffset 6
183 Tape read was labelled: oct.guest.dump (907215000)
186 The output in the Tape Coordinator window reads:
190 tape name = oct.guest.dump
191 AFS tape name = guests.monthly.3
192 creationTime = Thu Oct 1 00:10:00 1998
194 size = 2097152 Kbytes
195 dump path = B</monthly>
198 ---- End of tape label ----
200 The following example is for a tape that does not have a permanent
203 backup readlabel -portoffset 6
204 Tape read was labelled: guests.monthly.2 (909899900)
207 The output in the Tape Coordinator window reads:
212 AFS tape name = guests.monthly.2
213 creationTime = Sun Nov 1 00:58:20 1998
215 size = 2097152 Kbytes
216 dump path = B</monthly>
219 ---- End of tape label ----
221 =head1 PRIVILEGE REQUIRED
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
230 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
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.
239 L<backup_labeltape(1)>,