Commit | Line | Data |
---|---|---|
805e021f CE |
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 = example.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 = example.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. |