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