1 <?xml version="1.0" encoding="UTF-8"?>
2 <refentry id="backup_readlabel8">
4 <refentrytitle>backup readlabel</refentrytitle>
5 <manvolnum>8</manvolnum>
8 <refname>backup readlabel</refname>
9 <refpurpose>Reads and displays a tape's label</refpurpose>
12 <title>Synopsis</title>
13 <para><emphasis role="bold">backup readlabel</emphasis> [<emphasis role="bold">-portoffset</emphasis> <<emphasis>TC port offset</emphasis>>] [<emphasis role="bold">-localauth</emphasis>]
14 [<emphasis role="bold">-cell</emphasis> <<emphasis>cell name</emphasis>>] [<emphasis role="bold">-help</emphasis>]</para>
16 <para><emphasis role="bold">backup rea</emphasis> [<emphasis role="bold">-p</emphasis> <<emphasis>TC port offset</emphasis>>] [<emphasis role="bold">-l</emphasis>] [<emphasis role="bold">-c</emphasis> <<emphasis>cell name</emphasis>>]
17 [<emphasis role="bold">-h</emphasis>]</para>
21 <title>Description</title>
22 <para>The <emphasis role="bold">backup readlabel</emphasis> command displays information from the magnetic
23 tape label of a tape. The information includes the tape's name (either a
24 <emphasis>permanent name</emphasis>, or an <emphasis>AFS tape name</emphasis> that reflects the tape's
25 contents in a prescribed format) and its capacity.</para>
27 <para>If the <computeroutput>FILE YES</computeroutput> instruction appears in the
28 <replaceable>/usr/afs/backup/CFG_</replaceable><emphasis>device_name</emphasis><replaceable></replaceable> file associated with the specified
29 port offset, then the <emphasis role="bold">backup readlabel</emphasis> command reads the label
30 information from the first 16 KB block in the backup data file listed for
31 that port offset in the Tape Coordinator's <replaceable>/usr/afs/backup/tapeconfig</replaceable>
32 file, rather than from the beginning of a tape.</para>
34 <para>The Tape Coordinator's default response to this command is to access the
35 tape by invoking the <computeroutput>MOUNT</computeroutput> instruction in the local
36 <replaceable>/usr/afs/backup/CFG_</replaceable><emphasis>device_name</emphasis><replaceable></replaceable> file, or by prompting the backup
37 operator to insert the tape if there is no <computeroutput>MOUNT</computeroutput> instruction. However,
38 if the <computeroutput>AUTOQUERY NO</computeroutput> instruction appears in the <replaceable>CFG_</replaceable><emphasis>device_name</emphasis><replaceable></replaceable>
39 file, or if the issuer of the <emphasis role="bold">butc</emphasis> command included the <emphasis role="bold">-noautoquery</emphasis>
40 flag, the Tape Coordinator instead expects the tape to be in the device
41 already. If it is not, the Tape Coordinator invokes the <computeroutput>MOUNT</computeroutput>
42 instruction or prompts the operator.</para>
46 <title>Options</title>
49 <term><emphasis role="bold">-portoffset</emphasis> <<emphasis>TC port offset</emphasis>></term>
51 <para>Specifies the port offset number of the Tape Coordinator handling the
52 tapes for this operation.</para>
57 <term><emphasis role="bold">-localauth</emphasis></term>
59 <para>Constructs a server ticket using a key from the local
60 <replaceable>/usr/afs/etc/KeyFile</replaceable> file. The <emphasis role="bold">backup</emphasis> command interpreter presents
61 it to the Backup Server, Volume Server and VL Server during mutual
62 authentication. Do not combine this flag with the <emphasis role="bold">-cell</emphasis> argument. For
63 more details, see <link linkend="backup8">backup(8)</link>.</para>
68 <term><emphasis role="bold">-cell</emphasis> <<emphasis>cell name</emphasis>></term>
70 <para>Names the cell in which to run the command. Do not combine this argument
71 with the <emphasis role="bold">-localauth</emphasis> flag. For more details, see <link linkend="backup8">backup(8)</link>.</para>
76 <term><emphasis role="bold">-help</emphasis></term>
78 <para>Prints the online help for this command. All other valid options are
87 <para>Output from this command appears in both the shell window where the
88 command is issued, and in the Tape Coordinator window.</para>
90 <para>If the tape is unlabeled or if the specified tape device is empty, the
94 Failed to read tape label.
97 <para>Otherwise, the output in the shell window has the following format:</para>
100 Tape read was labelled: &lt;tape name&gt; (&lt;dump id&gt;)
101 size: &lt;size&gt; Kbytes
104 <para>where <tape name> is the permanent name if the tape has one, or the AFS
105 tape name otherwise. The <dump ID> is dump ID of the initial dump on the
106 tape, and <size> is the recorded capacity of the tape in kilobytes.</para>
108 <para>The output in the Tape Coordinator windows is bounded by an underlined
109 <computeroutput>Tape label</computeroutput> header at the top, and the following string at the bottom:</para>
112 -- End of tape label --
115 <para>In between are lines reporting the following information:</para>
119 <term>tape name</term>
121 <para>The permanent name assigned by using the -pname argument of the <emphasis role="bold">backup
122 labeltape</emphasis> command. This name remains on the tape until that argument is
123 used again, no matter how many times the tape is recycled or otherwise
124 relabeled. If the tape does not have a permanent name, the value <computeroutput><NULL></computeroutput> appears in this field.</para>
129 <term>AFS tape name</term>
131 <para>A tape name in one of the following prescribed formats. The Backup System
132 automatically writes the appropriate AFS tape name to the label as part of
133 a <emphasis role="bold">backup dump</emphasis> or <emphasis role="bold">backup savedb</emphasis> operation, or the operator can assign
134 it with the <emphasis role="bold">-name</emphasis> argument to the <emphasis role="bold">backup labeltape</emphasis> command.</para>
138 <para><emphasis>volume_set_name</emphasis><emphasis role="bold">.</emphasis><emphasis>dump_level_name</emphasis>.<emphasis>tape_index</emphasis>, if the tape
139 contains volume data. The <emphasis>volume_set_name</emphasis> is the name of the volume set
140 that was dumped to create the initial dump in the dump set of to which
141 this tape belongs; <emphasis>dump_level_name</emphasis> is the last pathname element of the
142 dump level at which the initial dump was backed up; and <emphasis>tape_index</emphasis> is
143 the numerical position of the tape in the dump set.</para>
147 <para><computeroutput>Ubik.db.dump.</computeroutput><emphasis>tape_index</emphasis> if the tape contains a dump of the Backup
148 Database, created with the <emphasis role="bold">backup savedb</emphasis> command. The <emphasis>tape_index</emphasis> is
149 the ordinal of the tape in the dump set.</para>
153 <para><computeroutput><NULL></computeroutput> if the tape has no AFS tape name. This is normally the case
154 if the <emphasis role="bold">-name</emphasis> argument was not included the last time the <emphasis role="bold">backup
155 labeltape</emphasis> command was used on this tape, and no data has been written to
163 <term>creationTime</term>
165 <para>The date and time at which the Backup System started performing the dump
166 operation that created the initial dump.</para>
173 <para>The cell in which the dump set was created. This is the cell whose Backup
174 Database contains a record of the dump set.</para>
181 <para>The tape's capacity (in kilobytes) as recorded on the label, rather than
182 the amount of data on the tape. The value is assigned by the <emphasis role="bold">-size</emphasis>
183 argument to the <emphasis role="bold">backup labeltape</emphasis> command or derived from the
184 <replaceable>/usr/afs/backup/tapeconfig</replaceable> file on the Tape Coordinator machine, not
185 from a measurement of the tape.</para>
190 <term>dump path</term>
192 <para>The dump level of the initial dump in the dump set.</para>
199 <para>The dump ID number of the initial dump in the dump set, as recorded in the
200 Backup Database.</para>
205 <term>useCount</term>
207 <para>The number of times a dump has been written to the tape, or it has been
213 <para>The message <computeroutput>ReadLabel: Finished</computeroutput> indicates the completion of the output.</para>
217 <title>Examples</title>
218 <para>The following example shows the output for the tape with permanent name
219 <computeroutput>oct.guest.dump</computeroutput> and capacity 2 MB, expressed in kilobyte units (2097152
220 equals 2 times 10242).</para>
223 % backup readlabel -portoffset 6
224 Tape read was labelled: oct.guest.dump (907215000)
228 <para>The output in the Tape Coordinator window reads:</para>
233 tape name = oct.guest.dump
234 AFS tape name = guests.monthly.3
235 creationTime = Thu Oct 1 00:10:00 1998
237 size = 2097152 Kbytes
241 ---- End of tape label ----
244 <para>The following example is for a tape that does not have a permanent tape.</para>
247 % backup readlabel -portoffset 6
248 Tape read was labelled: guests.monthly.2 (909899900)
252 <para>The output in the Tape Coordinator window reads:</para>
257 tape name = &lt;NULL&gt;
258 AFS tape name = guests.monthly.2
259 creationTime = Sun Nov 1 00:58:20 1998
261 size = 2097152 Kbytes
265 ---- End of tape label ----
270 <title>Privilege Required</title>
271 <para>The issuer must be listed in the <replaceable>/usr/afs/etc/UserList</replaceable> file on every
272 machine where the Backup Server is running, or must be logged onto a
273 server machine as the local superuser <computeroutput>root</computeroutput> if the <emphasis role="bold">-localauth</emphasis> flag is
278 <title>See Also</title>
279 <para><link linkend="butc5">butc(5)</link>,
280 <link linkend="backup8">backup(8)</link>,
281 <link linkend="backup_labeltape8">backup_labeltape(8)</link>,
282 <link linkend="butc8">butc(8)</link></para>
286 <title>Copyright</title>
287 <para>IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.</para>
289 <para>This documentation is covered by the IBM Public License Version 1.0. It was
290 converted from HTML to POD by software written by Chas Williams and Russ
291 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.</para>