doc: fix some broken link specifications
[openafs.git] / doc / man-pages / pod8 / backup_labeltape.pod
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.