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