Document KeyFileExt(5)
[openafs.git] / doc / man-pages / pod8 / backup.pod
1 =head1 NAME
2
3 backup - Introduction to the backup command suite
4
5 =head1 DESCRIPTION
6
7 The commands in the B<backup> command suite are the administrative
8 interface to the AFS Backup System. There are several categories of
9 commands in the suite:
10
11 =over 4
12
13 =item *
14
15 Commands to copy data from AFS volumes to tape or a backup data file, and
16 to restore it to the file system:
17 L<B<backup diskrestore>|backup_diskrestore(8)>,
18 L<B<backup dump>|backup_dump(8)>,
19 L<B<backup volrestore>|backup_volrestore(8)>,
20 and L<B<backup volsetrestore>|backup_volsetrestore(8)>.
21
22 =item *
23
24 Commands to administer the records in the Backup Database:
25 L<B<backup adddump>|backup_adddump(8)>,
26 L<B<backup addhost>|backup_addhost(8)>,
27 L<B<backup addvolentry>|backup_addvolentry(8)>,
28 L<B<backup addvolset>|backup_addvolset(8)>,
29 L<B<backup deldump>|backup_deldump(8)>,
30 L<B<backup deletedump>|backup_deletedump(8)>,
31 L<B<backup delhost>|backup_delhost(8)>,
32 L<B<backup delvolentry>|backup_delvolentry(8)>,
33 L<B<backup delvolset>|backup_delvolset(8)>,
34 L<B<backup dumpinfo>|backup_dumpinfo(8)>,
35 L<B<backup listdumps>|backup_listdumps(8)>,
36 L<B<backup listhosts>|backup_listhosts(8)>,
37 L<B<backup listvolsets>|backup_listvolsets(8)>,
38 L<B<backup scantape>|backup_scantape(8)>,
39 L<B<backup setexp>|backup_setexp(8)>,
40 and L<B<backup volinfo>|backup_volinfo(8)>.
41
42 =item *
43
44 Commands to write and read tape labels:
45 L<B<backup labeltape>|backup_labeltape(8)>
46 and L<B<backup readlabel>|backup_readlabel(8)>.
47
48 =item *
49
50 Commands to list and change the status of backup operations and the
51 machines performing them:
52 L<B<backup jobs>|backup_jobs(8)>,
53 L<B<backup kill>|backup_kill(8)>,
54 and L<B<backup status>|backup_status(8)>.
55
56 =item *
57
58 Commands to enter and leave interactive mode:
59 L<B<backup interactive>|backup_interactive(8)>
60 and L<B<backup quit>|backup_quit(8)>.
61
62 =item *
63
64 Commands to check for and repair corruption in the Backup Database:
65 L<B<backup dbverify>|backup_dbverify(8)>,
66 L<B<backup restoredb>|backup_restoredb(8)>,
67 and L<B<backup savedb>|backup_savedb(8)>.
68
69 =item *
70
71 Commands to obtain help:
72 L<B<backup apropos>|backup_apropos(8)>
73 and L<B<backup help>|backup_help(8)>.
74
75 =back
76
77 The backup command interpreter interacts with two other processes:
78
79 =over 4
80
81 =item *
82
83 The Backup Server (B<buserver>) process. It maintains the Backup Database,
84 which stores most of the administrative information used by the Backup
85 System. In the standard configuration, the Backup Server runs on each
86 database server machine in the cell, and uses AFS's distributed database
87 technology, Ubik, to synchronize its copy of the database with the copies
88 on the other database server machines.
89
90 =item *
91
92 The Backup Tape Coordinator (B<butc>) process. A separate instance of the
93 process controls each tape device or backup data file used to dump or
94 restore data. The Tape Coordinator runs on a Tape Coordinator machine,
95 which is an AFS server or client machine that has one or more tape devices
96 attached, or has sufficient disk space to accommodate one or more backup
97 data files on its local disk.
98
99 Each Tape Coordinator must be registered in the Backup Database and in the
100 F</usr/afs/backup/tapeconfig> configuration file on the Tape Coordinator
101 machine's local disk, and information in the two places must be consistent
102 for proper Backup System performance. The optional
103 F</usr/afs/backup/CFG_I<device_name>> for each Tape Coordinator records
104 information used to automate its operation.
105
106 =back
107
108 In addition to the standard command line interface, the B<backup> command
109 suite provides an I<interactive> interface, which has several useful
110 features described in L<backup_interactive(8)>.  Three of the commands in
111 the suite are available only in interactive mode:
112 L<B<backup jobs>|backup_jobs(8)>,
113 L<B<backup kill>|backup_kill(8)>,
114 and L<B<backup quit>|backup_quit(8)>
115
116 =head1 OPTIONS
117
118 The following options are available on many commands in the B<backup>
119 suite. The reference page for each command also lists them, but they are
120 described here in greater detail.
121
122 =over 4
123
124 =item B<-cell> <I<cell name>>
125
126 Names the cell in which to run the command. It is acceptable to abbreviate
127 the cell name to the shortest form that distinguishes it from the other
128 entries in the F</usr/vice/etc/CellServDB> file on the local machine. If
129 the B<-cell> argument is omitted, the command interpreter determines the
130 name of the local cell by reading the following in order:
131
132 =over 4
133
134 =item *
135
136 The value of the AFSCELL environment variable.
137
138 =item *
139
140 The local F</usr/vice/etc/ThisCell> file.
141
142 =back
143
144 Do not combine the B<-cell> and B<-localauth> options. A command on which
145 the B<-localauth> flag is included always runs in the local cell (as
146 defined in the server machine's local F</usr/afs/etc/ThisCell> file),
147 whereas a command on which the B<-cell> argument is included runs in the
148 specified foreign cell.
149
150 The B<-cell> argument is not available on commands issued in interactive
151 mode. The cell defined when the B<backup> command interpreter enters
152 interactive mode applies to all commands issued during the interactive
153 session.
154
155 =item B<-help>
156
157 Prints a command's online help message on the standard output stream. Do
158 not combine this flag with any of the command's other options; when it is
159 provided, the command interpreter ignores all other options, and only
160 prints the help message.
161
162 =item B<-localauth>
163
164 Constructs a server ticket using the server encryption key with the
165 highest key version number in the local F</usr/afs/etc/KeyFile>
166 or F</usr/afs/etc/KeyFileExt> file. The
167 B<backup> command interpreter presents the ticket, which never expires, to
168 the Backup Server, Volume Server and Volume Location (VL) Server during
169 mutual authentication.
170
171 Use this flag only when issuing a command on a server machine; client
172 machines do not usually have a F</usr/afs/etc/KeyFile> or
173 F</usr/afs/etc/KeyFileExt> file.  The issuer
174 of a command that includes this flag must be logged on to the server
175 machine as the local superuser C<root>. The flag is useful for commands
176 invoked by an unattended application program, such as a process controlled
177 by the UNIX B<cron> utility or by a cron entry in the machine's
178 F</usr/afs/local/BosConfig> file. It is also useful if an administrator is
179 unable to authenticate to AFS but is logged in as the local superuser
180 C<root>.
181
182 Do not combine the B<-cell> and B<-localauth> options. A command on which
183 the B<-localauth> flag is included always runs in the local cell (as
184 defined in the server machine's local F</usr/afs/etc/ThisCell> file),
185 whereas a command on which the B<-cell> argument is included runs in the
186 specified foreign cell.
187
188 The B<-localauth> argument is not available on commands issued in
189 interactive mode. The local identity and AFS tokens with which the
190 B<backup> command interpreter enters interactive mode apply to all
191 commands issued during the interactive session.
192
193 =item B<-portoffset> <I<TC port offset>>
194
195 Specifies the port offset number of the Tape Coordinator that is to
196 execute the B<backup> command. The port offset number uniquely identifies
197 a pairing of a Tape Coordinator (B<butc>) process and tape device or
198 backup data file.
199
200 The backup command interpreter and Tape Coordinator process communicate
201 via a UDP socket, or port. Before issuing a B<backup> command that
202 involves reading or writing a tape, the backup operator must start a
203 B<butc> process that controls the appropriate tape device and listens for
204 requests sent to its port number. If a Backup System machine has multiple
205 tape devices attached, they can perform backup operations simultaneously
206 because each device has its own associated B<butc> process and port offset
207 number.
208
209 The Backup System associates a tape capacity and file mark size with each
210 port offset (as defined in the F<tapeconfig> file). For a compressing tape
211 device, the capacity and file mark values differ for compression and
212 non-compression modes, so the two modes have distinct port offset numbers.
213
214 The Backup Database can store up to 58,511 port offsets, so the legal
215 values for this argument are the integers C<0> through C<58510>. If the
216 issuer omits the argument, it defaults to C<0>. (The limit of 58,511 port
217 offsets results from the fact that UDP socket numbers are identified by a
218 16-bit integer, and the lowest socket number used by the Backup System is
219 7025. The largest number that a 16-bit integer can represent is
220 65,535. Subtracting 7,025 yields 58,510. The addition of port offset 0
221 (zero) increases the maximum to 58,511.)
222
223 Although it is possible to define up to 58,511 port offset numbers for a
224 cell, it is not possible to run 58,511 tape devices simultaneously, due to
225 the following limits:
226
227 =over 4
228
229 =item *
230
231 The maximum number of dump or restore operations that can run
232 simultaneously is 64.
233
234 =item *
235
236 The maximum number of tape devices that can work together on a restore
237 operation is 128 (that is the maximum number of values that can be
238 provided for the B<-portoffset> argument to the
239 L<B<backup diskrestore>|backup_diskrestore(8)>,
240 L<B<backup volrestore>|backup_volrestore(8)>,
241 or L<B<backup volsetrestore>|backup_volsetrestore(8)> command).
242
243 =back
244
245 The Backup System does not reserve UDP sockets. If another application is
246 already using the Tape Coordinator's socket when it tries to start, the
247 B<butc> process fails and the following error message appears at the shell
248 prompt:
249
250    bind: Address already in use
251    rxi_GetUDPSocket: bind failed
252
253 =back
254
255 =head1 PRIVILEGE REQUIRED
256
257 To issue any backup command that accesses the Backup Database only, the
258 issuer must be listed in the F</usr/afs/etc/UserList> file on every
259 machine where the Backup Server is running. To issue any B<backup> command
260 that accesses volume data, the issuer must appear in the F<UserList> file
261 on every Backup Server machine, every Volume Location (VL) Server machine,
262 and every file server machine that houses affected volumes. By convention,
263 a common F<UserList> file is distributed to all database server and file
264 server machines in the cell. See the chapter on privileged users in the
265 I<OpenAFS Administration Guide> for more information on this type of
266 privilege.
267
268 If the B<-localauth> flag is included, the user must instead be logged on
269 as the local superuser C<root> on the server machine where the B<backup>
270 command is issued.
271
272 =head1 SEE ALSO
273
274 L<BosConfig(5)>,
275 L<CellServDB(5)>,
276 L<KeyFile(5)>,
277 L<KeyFileExt(5)>,
278 L<ThisCell(5)>,
279 L<UserList(5)>,
280 L<butc(5)>,
281 L<tapeconfig(5)>,
282 L<backup_adddump(8)>,
283 L<backup_addhost(8)>,
284 L<backup_addvolentry(8)>,
285 L<backup_addvolset(8)>,
286 L<backup_apropos(8)>,
287 L<backup_dbverify(8)>,
288 L<backup_deldump(8)>,
289 L<backup_deletedump(8)>,
290 L<backup_delhost(8)>,
291 L<backup_delvolentry(8)>,
292 L<backup_delvolset(8)>,
293 L<backup_diskrestore(8)>,
294 L<backup_dump(8)>,
295 L<backup_dumpinfo(8)>,
296 L<backup_help(8)>,
297 L<backup_interactive(8)>,
298 L<backup_jobs(8)>,
299 L<backup_kill(8)>,
300 L<backup_labeltape(8)>,
301 L<backup_listdumps(8)>,
302 L<backup_listhosts(8)>,
303 L<backup_listvolsets(8)>,
304 L<backup_quit(8)>,
305 L<backup_readlabel(8)>,
306 L<backup_restoredb(8)>,
307 L<backup_savedb(8)>,
308 L<backup_scantape(8)>,
309 L<backup_setexp(8)>,
310 L<backup_status(8)>,
311 L<backup_volinfo(8)>,
312 L<backup_volrestore(8)>,
313 L<backup_volsetrestore(8)>,
314 L<buserver(8)>,
315 L<butc(8)>
316
317 =head1 COPYRIGHT
318
319 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
320
321 This documentation is covered by the IBM Public License Version 1.0.  It was
322 converted from HTML to POD by software written by Chas Williams and Russ
323 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.