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