doc: vos manpage fixes
[openafs.git] / doc / man-pages / pod1 / vos_backupsys.pod
1 =head1 NAME
2
3 vos_backupsys - Creates a backup volume for several read/write volumes
4
5 =head1 SYNOPSIS
6
7 =for html
8 <div class="synopsis">
9
10 B<vos backupsys> S<<< [B<-prefix> <I<common prefix on volume(s)>>+] >>>
11     S<<< [B<-server> <I<machine name>>] >>>
12     S<<< [B<-partition> <I<partition name>>] >>>
13     [B<-exclude>] S<<< [B<-xprefix> <I<negative prefix on volume(s)>>+] >>>
14     [B<-dryrun>] S<<< [B<-cell> <I<cell name>>] >>>
15     [B<-noauth>] [B<-localauth>]
16     [B<-verbose>] [B<-encrypt>] [B<-noresolve>]
17     S<<< [B<-config> <I<config directory>>] >>>
18     [B<-help>]
19
20 B<vos backups> S<<< [B<-pr> <I<common prefix on volume(s)>>+] >>>
21     S<<< [B<-s> <I<machine name>>] >>> S<<< [B<-pa> <I<partition name>>] >>>
22     [B<-ex>] S<<< [B<-x> <I<negative prefix on volume(s)>>+] >>> [B<-d>]
23     S<<< [B<-c> <I<cell name>>] >>> [B<-noa>] [B<-l>] [B<-v>]
24     [B<-en>] [B<-nor>]
25     S<<< [B<-co> <I<config directory>>] >>>
26     [B<-h>]
27
28 =for html
29 </div>
30
31 =head1 DESCRIPTION
32
33 The B<vos backupsys> command clones each indicated read/write volume to
34 create a backup version, placing each clone at the same site as its
35 read/write source version. It assigns each clone the same name as the
36 read/write source, adding a C<.backup> extension. It assigns the volume ID
37 number already allocated for the backup version in the Volume Location
38 Database (VLDB). If a backup version already exists for a given volume,
39 the new clone replaces it.
40
41 To clone every read/write volume listed in the VLDB, omit all of the
42 command's options. Otherwise, combine the command's options to clone
43 various groups of volumes. The options use one of two basic criteria to
44 select volumes: location (the B<-server> and B<-partition> arguments) or
45 presence in the volume name of one of a set of specified character strings
46 (the B<-prefix>, B<-exclude>, and B<-xprefix> options).
47
48 To clone only volumes that reside on one file server machine, include the
49 B<-server> argument. To clone only volumes that reside on one partition,
50 combine the B<-server> and B<-partition> arguments. The B<-partition>
51 argument can also be used alone to clone volumes that reside on the
52 indicated partition on every file server machine. These arguments can be
53 combined with those that select volumes based on their names.
54
55 Combine the B<-prefix>, -exclude, and B<-xprefix> options (with or without
56 the B<-server> and B<-partition> arguments) in the indicated ways to
57 select volumes based on character strings contained in their names:
58
59 =over 4
60
61 =item *
62
63 To clone every read/write volume at the specified location whose name
64 includes one of a set of specified character strings (for example, begins
65 with C<user.> or includes the string C<afs>), use the B<-prefix> argument
66 or combine the B<-xprefix> and B<-exclude> options.
67
68 =item *
69
70 To clone every read/write volume at the specified location except those
71 whose name includes one of a set of specified character strings, use the
72 B<-xprefix> argument or combine the B<-prefix> and B<-exclude> options.
73
74 =item *
75
76 To clone every read/write volume at the specified location whose name
77 includes one of one of a set of specified character strings, except those
78 whose names include one of a different set of specified character strings,
79 combine the B<-prefix> and B<-xprefix> arguments. The command creates a
80 list of all volumes that match the B<-prefix> argument and then removes
81 from the list the volumes that match the B<-xprefix> argument. For
82 effective results, the strings specified by the B<-xprefix> argument must
83 designate a subset of the volumes specified by the B<-prefix> argument.
84
85 If the B<-exclude> flag is combined with the B<-prefix> and B<-xprefix>
86 arguments, the command creates a list of all volumes that do not match the
87 B<-prefix> argument and then adds to the list any volumes that match the
88 B<-xprefix> argument. As when the B<-exclude> flag is not used, the result
89 is effective only if the strings specified by the B<-xprefix> argument
90 designate a subset of the volumes specified by the B<-prefix> argument.
91
92 =back
93
94 The B<-prefix> and B<-xprefix> arguments both accept multiple values,
95 which can be used to define disjoint groups of volumes. Each value can be
96 one of two types:
97
98 =over 4
99
100 =item *
101
102 A simple character string, which matches volumes whose name begin with the
103 string. All characters are interpreted literally (that is, characters that
104 potentially have special meaning to the command shell, such as the period,
105 have only their literal meaning).
106
107 =item *
108
109 A regular expression, which matches volumes whose names contain the
110 expressions. Place a caret (C<^>) at the beginning of the expression, and
111 enclose the entire string in single quotes (C<''>). Explaining regular
112 expressions is outside the scope of this reference page; see the UNIX
113 manual page for regexp(5) or (for a brief introduction)
114 L<backup_addvolentry(8)>. As an example, the following expression matches
115 volumes that have the string C<aix> anywhere in their names:
116
117    -prefix  '^.*aix'
118
119 =back
120
121 To display a list of the volumes to be cloned, without actually cloning
122 them, include the B<-dryrun> flag. To display a statement that summarizes
123 the criteria being used to select volume, include the B<-verbose> flag.
124
125 This command can be used to clone a single read/write volume; specify its
126 complete name as the B<-prefix> argument. However, it is more efficient to
127 use the B<vos backup> command, which employs a more streamlined technique
128 for finding a single volume.
129
130 =head1 OPTIONS
131
132 =over 4
133
134 =item B<-prefix> <I<common prefix>>
135
136 Specifies one or more simple character strings or regular expressions of
137 any length; a volume whose name includes the string is placed on the set
138 of volumes to be cloned. Include field separators (such as periods) if
139 appropriate. This argument can be combined with any combination of the
140 B<-server>, B<-partition>, B<-exclude>, and B<-xprefix> options.
141
142 =item B<-server> <I<machine name>>
143
144 Identifies the file server machine where each read/write source volume
145 resides. Provide the machine's IP address or its host name (either fully
146 qualified or using an unambiguous abbreviation). For details, see
147 L<vos(1)>.
148
149 This argument can be combined with any combination of the B<-prefix>,
150 B<-partition>, B<-exclude>, and B<-xprefix> options.
151
152 =item B<-partition> <I<partition name>>
153
154 Identifies the partition where each read/write source volume
155 resides. Provide the partition's complete name with preceding slash (for
156 example, C</vicepa>) or use one of the three acceptable abbreviated
157 forms. For details, see L<vos(1)>.
158
159 This argument can be combined with any combination of the B<-prefix>,
160 B<-server>, B<-exclude>, and B<-xprefix> options.
161
162 =item B<-exclude>
163
164 Reverses the meaning of the B<-prefix> or B<-xprefix> argument. This flag
165 can be combined with any combination of the B<-prefix>, B<-server>,
166 B<-partition>, and B<-xprefix> options.
167
168 =item B<-xprefix> <I<negative prefix>>
169
170 Specifies a simple character string or regular expression of any length; a
171 volume whose name includes the string is removed from the set of volumes
172 to be cloned. Include field separators (such as periods) if
173 appropriate. This argument can be combined with any combination of the
174 B<-prefix>, B<-server>, B<-partition>, and B<-exclude> options.
175
176 =item B<-dryrun>
177
178 Displays on the standard output stream a list of the volumes to be cloned,
179 without actually cloning them.
180
181 =item B<-cell> <I<cell name>>
182
183 Names the cell in which to run the command. Do not combine this argument
184 with the B<-localauth> flag. For more details, see L<vos(1)>.
185
186 =item B<-noauth>
187
188 Assigns the unprivileged identity C<anonymous> to the issuer. Do not
189 combine this flag with the B<-localauth> flag. For more details, see
190 L<vos(1)>.
191
192 =item B<-localauth>
193
194 Constructs a server ticket using a key from the local
195 F</usr/afs/etc/KeyFile> file. The B<vos> command interpreter presents it
196 to the Volume Server and Volume Location Server during mutual
197 authentication. Do not combine this flag with the B<-cell> argument or
198 B<-noauth> flag. For more details, see L<vos(1)>.
199
200 =item B<-verbose>
201
202 Produces on the standard output stream a detailed trace of the command's
203 execution. If this argument is omitted, only warnings and error messages
204 appear.
205
206 =item B<-encrypt>
207
208 Encrypts the command so that the operation's results are not transmitted
209 across the network in clear text. This option is available in OpenAFS
210 versions 1.4.11 or later and 1.5.60 or later.
211
212 =item B<-noresolve>
213
214 Shows all servers as IP addresses instead of the DNS name. This is very
215 useful when the server address is registered as 127.0.0.1 or when dealing
216 with multi-homed servers. This option is available in OpenAFS
217 versions 1.4.8 or later and 1.5.35 or later.
218
219 =item B<-help>
220
221 Prints the online help for this command. All other valid options are
222 ignored.
223
224 =back
225
226 =head1 OUTPUT
227
228 The command generates the following messages on the standard output stream
229 to confirm that the operation was successful:
230
231    done
232    Total volumes backed up: <number_cloned>; failed to backup: <failures>
233
234 If the B<-dryrun> flag is included, a list of the volumes to be backed up
235 precedes the standard confirmation messages.
236
237 If the B<-verbose> flag is included but not the B<-dryrun> flag, the
238 following messages appear for each volume. The output concludes with the
239 standard confirmation messages.
240
241    Creating backup volume for <volume_name> on <date/time>
242    {Recloning backup volume | Creating a new backup clone} <backup_volumeID> . . .done
243
244 If both the B<-dryrun> and B<-verbose> flags are included, the output
245 begins with a statement summarizing the criteria being used to select the
246 volumes, followed by a list of the volumes and the standard confirmation
247 messages. The format of the criteria summary statement depends on which
248 other options are provided:
249
250 =over 4
251
252 =item *
253
254 If only the B<-prefix> argument is provided, or the B<-xprefix> and
255 B<-exclude> options are combined:
256
257    Would have backed up volumes which are prefixed with <string> [or <string>] . .
258
259 =item *
260
261 If only the B<-xprefix> argument is provided, or the B<-prefix> and
262 B<-exclude> options are combined:
263
264    Would have backed up volumes which are not prefixed with <string> [nor <string>] . .
265
266 =item *
267
268 If the B<-prefix> and B<-xprefix> arguments are combined:
269
270    Would have backed up volumes which are prefixed with <string> [or <string>] \
271       removing those which are prefixed with <x_string> [or <x_string>] . .
272
273 =item *
274
275 If the B<-prefix>, B<-xprefix>, and B<-exclude> options are provided:
276
277    Would have backed up volumes which are not prefixed with <string> [nor <string>] \
278       adding those which are prefixed with <x_string> [or <x_string>] . .
279
280 =back
281
282 =head1 EXAMPLES
283
284 The following example creates a backup version of every read/write volume
285 listed in the cell's VLDB whose name begins with the string B<user>.
286
287    % vos backupsys -prefix user
288
289 The following example, appropriate in the Example Corporation cell, creates a
290 backup version of every read/write volume on the file server machine
291 C<fs3.example.com>.
292
293    % vos backupsys -server fs3.example.com
294
295 The following example, appropriate in the Example Organization cell, creates a
296 backup version of every read/write volume on the file server machine
297 C<db1.example.org> except those whose name includes the string C<temp>.
298
299    % vos backupsys  -server db1.example.org -prefix '^.*temp'
300
301 The following example creates a backup version of every volume listed in
302 the cell's VLDB, excluding those whose names contain the string C<source>,
303 but including those whose names contain the string C<source.current>.
304
305    % vos backupsys  -prefix '^.*source' -exclude -xprefix '^.*source\.current'
306
307 =head1 PRIVILEGE REQUIRED
308
309 The issuer must be listed in the F</usr/afs/etc/UserList> file on the
310 machine specified with the B<-server> argument and on each database server
311 machine. If the B<-localauth> flag is included, the issuer must instead be
312 logged on to a server machine as the local superuser C<root>.
313
314 =head1 SEE ALSO
315
316 L<backup_addvolentry(8)>,
317 L<vos(1)>,
318 L<vos_backup(1)>
319
320 UNIX manual page for regexp(5)
321
322 =head1 COPYRIGHT
323
324 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
325
326 This documentation is covered by the IBM Public License Version 1.0.  It was
327 converted from HTML to POD by software written by Chas Williams and Russ
328 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.