Commit | Line | Data |
---|---|---|
805e021f CE |
1 | =head1 NAME |
2 | ||
3 | backup_labeltape - Creates the magnetic label on a tape | |
4 | ||
5 | =head1 SYNOPSIS | |
6 | ||
7 | =for html | |
8 | <div class="synopsis"> | |
9 | ||
10 | B<backup labeltape> S<<< [B<-name> <I<AFS tape name, defaults to NULL>>] >>> | |
11 | S<<< [B<-size> <I<tape size in Kbytes, defaults to size in tapeconfig>>] >>> | |
12 | S<<< [B<-portoffset> <I<TC port offset>>] >>> | |
13 | S<<< [B<-pname> <I<permanent tape name>>] >>> | |
14 | [B<-localauth>] S<<< [B<-cell> <I<cell name>>] >>> [B<-help>] | |
15 | ||
16 | B<backup la> S<<< [B<-n> <I<AFS tape name, defaults to NULL>>] >>> | |
17 | S<<< [B<-s> <I<tape size in Kbytes, defaults to size in tapeconfig>>] >>> | |
18 | S<<< [B<-po> <I<TC port offset>>] >>> | |
19 | S<<< [B<-pn> <I<permanent tape name>>] >>> | |
20 | [B<-l>] S<<< [B<-c> <I<cell name>>] >>> [B<-h>] | |
21 | ||
22 | =for html | |
23 | </div> | |
24 | ||
25 | =head1 DESCRIPTION | |
26 | ||
27 | The B<backup labeltape> command creates a magnetic label, readable by the | |
28 | Backup System, at the beginning of a tape. The label records the tape's | |
29 | name (either a I<permanent name>, or an I<AFS tape name> that reflects the | |
30 | tape's contents in a prescribed format) and its capacity. | |
31 | ||
32 | (If the C<FILE YES> instruction appears in the | |
33 | F</usr/afs/backup/CFG_I<device_name>> file on the Tape Coordinator machine | |
34 | associated with the specified port offset, then the B<backup> command | |
35 | writes label information to the first 16 KB block in the backup data file | |
36 | listed for that port offset in the Tape Coordinator's | |
37 | F</usr/afs/backup/tapeconfig> file, rather than at the beginning of a | |
38 | tape. For the sake of clarity, the following text refers to tapes only, | |
39 | but the Backup System handles backup data files in much the same way.) | |
40 | ||
41 | Relabeling a tape that already contains AFS backup data effectively makes | |
42 | the data unusable, because the command removes the Backup Database record | |
43 | of the complete dump set of which the tape is a part. Use this command to | |
44 | enable recycling of a tape that contains unexpired dumps that are not | |
45 | actually still needed. | |
46 | ||
47 | To write a permanent name on the label, include the B<-pname> argument to | |
48 | specify a string of up to 32 characters. The permanent name persists until | |
49 | the B<-pname> argument is again included on the B<backup labeltape> | |
50 | command, regardless of the tape's contents and of how often the tape is | |
51 | otherwise relabeled or recycled. Include this argument or the B<-name> | |
52 | argument, but not both. If this argument is included, the AFS tape name is | |
53 | set to C<< <NULL> >>. The permanent name is set to C<< <NULL> >> if this | |
54 | argument is omitted and no permanent name already exists. | |
55 | ||
56 | The issuer must ensure that a permanent name is unique among the tapes | |
57 | used for AFS backup in the cell, because the B<backup> command interpreter | |
58 | does not verify that another tape does not already have the same permanent | |
59 | name. When a tape has a permanent name, the Backup System uses it instead | |
60 | of the AFS tape name in most prompts and when referring to the tape in | |
61 | output from B<backup> commands. The permanent name appears in the C<tape | |
62 | name> field of the output from the B<backup readlabel> command. | |
63 | ||
64 | To write an AFS tape name on the label, provide a value for the B<-name> | |
65 | argument in the required format described in L</OPTIONS>. Include the | |
66 | B<-name> argument or the B<-pname> argument, but not both. If this | |
67 | argument is omitted, the AFS tape name is set to C<< <NULL> >>, but the | |
68 | Backup System automatically assigns the appropriate name when the tape is | |
69 | used in a future B<backup dump> or B<backup savedb> operation. The AFS | |
70 | tape name appears in the C<AFS tape name> field of the output from the | |
71 | B<backup readlabel> and B<backup scantape> commands. | |
72 | ||
73 | The backup command interpreter does not accept the B<-name> argument if | |
74 | the tape already has a permanent name. To erase a tape's permanent name, | |
75 | provide a null value to the B<-pname> argument by issuing the following | |
76 | command: | |
77 | ||
78 | % backup labeltape -pname "" | |
79 | ||
80 | To record the tape's capacity on the label, specify a number of kilobytes | |
81 | as the B<-size> argument. If the argument is omitted the first time a tape | |
82 | is labeled, the Backup System records the default tape capacity recorded | |
83 | for the specified port offset in the F</usr/afs/backup/tapeconfig> file on | |
84 | the Tape Coordinator machine. Subsequently, the value in the size field | |
85 | persists until the B<-size> argument is again included on the B<backup | |
86 | labeltape> command. | |
87 | ||
88 | To determine how much data can be written to a tape during a backup dump | |
89 | or B<backup savedb> operation, the Tape Coordinator reads the capacity | |
90 | recorded on the tape's label (or uses the value associated with its port | |
91 | offset in the F</usr/afs/backup/tapeconfig> file, if the tape was never | |
92 | labeled). For further description, see the B<backup dump> reference page. | |
93 | ||
94 | The Tape Coordinator's default response to this command is to access the | |
95 | tape by invoking the C<MOUNT> instruction in the local | |
96 | F</usr/afs/backup/CFG_I<device_name>> file, or by prompting the backup | |
97 | operator to insert the tape if there is no C<MOUNT> instruction. However, | |
98 | if the C<AUTOQUERY NO> instruction appears in the F<CFG_I<device_name>> | |
99 | file, or if the issuer of the B<butc> command included the B<-noautoquery> | |
100 | flag, the Tape Coordinator instead expects the tape to be in the device | |
101 | already. If it is not, the Tape Coordinator invokes the C<MOUNT> | |
102 | instruction or prompts the operator. | |
103 | ||
104 | =head1 OPTIONS | |
105 | ||
106 | =over 4 | |
107 | ||
108 | =item B<-name> <I<AFS tape name>> | |
109 | ||
110 | Specifies the AFS tape name to record on the label. Include this argument | |
111 | or the B<-pname> argument, but not both. If this argument is omitted, the | |
112 | AFS tape name is set to C<< <NULL> >>. If this argument is provided, it | |
113 | must have the following format: | |
114 | ||
115 | <volume_set_name>.<dump_level_name>.<tape_index> | |
116 | ||
117 | for the tape to be acceptable for use in a future backup dump | |
118 | operation. The <volume_set_name> must match the volume set name of the | |
119 | initial dump to be written to the tape, <dump_level_name> must match the | |
120 | last element of the dump level pathname at which the volume set will be | |
121 | dumped, and <tape_index> indicates the order of the tape in the dump set | |
122 | (indexing begins with C<1>). To disable this type of name checking, | |
123 | include the C<NAME_CHECK NO> instruction in the F<CFG_I<device_name>> | |
124 | file. | |
125 | ||
126 | For the tape to be acceptable for use in a future backup savedb operation, | |
127 | the value specified for the B<-name> argument must have the following | |
128 | format: | |
129 | ||
130 | Ubik_db_dump.<tape_index> | |
131 | ||
132 | where <tape_index> indicates the order of the tape in the set of tapes | |
133 | that house the Backup Database dump; indexing begins with C<1> (one). | |
134 | ||
135 | =item B<-size> <I<tape size>> | |
136 | ||
137 | Specifies the tape capacity to record on the label. Provide an integer | |
138 | value followed by a letter that indicates units, with no intervening | |
139 | space. A unit value of C<k> or C<K> indicates kilobytes, C<m> or C<M> | |
140 | indicates megabytes, and C<g> or C<G> indicates gigabytes. If the units | |
141 | letter is omitted, the default is kilobytes. | |
142 | ||
143 | If this argument is omitted the first time a tape is labeled, the Backup | |
144 | System records the capacity that is associated with the specified port | |
145 | offset in the F</usr/afs/backup/tapeconfig> file on the Tape Coordinator | |
146 | machine. The value recorded the first time then persists until the | |
147 | B<-size> argument is provided on a future issuance of the command. | |
148 | ||
149 | =item B<-portoffset> <I<TC port offset>> | |
150 | ||
151 | Specifies the port offset number of the Tape Coordinator handling the tape | |
152 | for this operation. | |
153 | ||
154 | =item B<-pname> <I<permanent tape name>> | |
155 | ||
156 | Specifies the permanent name to record on the label. It can be up to 32 | |
157 | characters in length, and include any alphanumeric characters. Avoid | |
158 | metacharacters that have a special meaning to the shell, to avoid having | |
159 | to mark them as literal in commands issued at the shell prompt. | |
160 | ||
161 | Include this argument or the B<-name> argument, but not both. If this | |
162 | argument is provided, the AFS tape name is set to C<< <NULL> >>. If this | |
163 | argument is omitted, any existing permanent name is retained. | |
164 | ||
165 | =item B<-localauth> | |
166 | ||
167 | Constructs a server ticket using a key from the local | |
168 | F</usr/afs/etc/KeyFile> file. The B<backup> command interpreter presents | |
169 | it to the Backup Server, Volume Server and VL Server during mutual | |
170 | authentication. Do not combine this flag with the B<-cell> argument. For | |
171 | more details, see L<backup(8)>. | |
172 | ||
173 | =item B<-cell> <I<cell name>> | |
174 | ||
175 | Names the cell in which to run the command. Do not combine this argument | |
176 | with the B<-localauth> flag. For more details, see L<backup(8)>. | |
177 | ||
178 | =item B<-help> | |
179 | ||
180 | Prints the online help for this command. All other valid options are | |
181 | ignored. | |
182 | ||
183 | =back | |
184 | ||
185 | =head1 EXAMPLES | |
186 | ||
187 | The following command records the AFS tape name C<user.monthly.1> on the | |
188 | label of the tape in the device with port offset 3: | |
189 | ||
190 | % backup labeltape -name user.monthly.1 -portoffset 3 | |
191 | ||
192 | The following three commands are equivalent in effect: they all record a | |
193 | capacity of 2 GB on the label of the tape in the device with port offset | |
194 | 4. They set the AFS tape name to C<< <NULL> >> and leave the permanent | |
195 | name unchanged. | |
196 | ||
197 | % backup labeltape -size 2g -portoffset 4 | |
198 | % backup labeltape -size 2048M -portoffset 4 | |
199 | % backup labeltape -size 2097152 -portoffset 4 | |
200 | ||
201 | =head1 PRIVILEGE REQUIRED | |
202 | ||
203 | The issuer must be listed in the F</usr/afs/etc/UserList> file on every | |
204 | machine where the Backup Server is running, or must be logged onto a | |
205 | server machine as the local superuser C<root> if the B<-localauth> flag is | |
206 | included. | |
207 | ||
208 | =head1 SEE ALSO | |
209 | ||
210 | L<butc(5)>, | |
211 | L<backup(8)>, | |
212 | L<backup_readlabel(8)>, | |
213 | L<butc(8)> | |
214 | ||
215 | =head1 COPYRIGHT | |
216 | ||
217 | IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved. | |
218 | ||
219 | This documentation is covered by the IBM Public License Version 1.0. It was | |
220 | converted from HTML to POD by software written by Chas Williams and Russ | |
221 | Allbery, based on work by Alf Wachsmann and Elizabeth Cassell. |