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