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