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