doc: vos manpage fixes
[openafs.git] / doc / man-pages / pod1 / vos_backupsys.pod.in
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 =include fragments/vos-common.pod
182
183 =back
184
185 =head1 OUTPUT
186
187 The command generates the following messages on the standard output stream
188 to confirm that the operation was successful:
189
190    done
191    Total volumes backed up: <number_cloned>; failed to backup: <failures>
192
193 If the B<-dryrun> flag is included, a list of the volumes to be backed up
194 precedes the standard confirmation messages.
195
196 If the B<-verbose> flag is included but not the B<-dryrun> flag, the
197 following messages appear for each volume. The output concludes with the
198 standard confirmation messages.
199
200    Creating backup volume for <volume_name> on <date/time>
201    {Recloning backup volume | Creating a new backup clone} <backup_volumeID> . . .done
202
203 If both the B<-dryrun> and B<-verbose> flags are included, the output
204 begins with a statement summarizing the criteria being used to select the
205 volumes, followed by a list of the volumes and the standard confirmation
206 messages. The format of the criteria summary statement depends on which
207 other options are provided:
208
209 =over 4
210
211 =item *
212
213 If only the B<-prefix> argument is provided, or the B<-xprefix> and
214 B<-exclude> options are combined:
215
216    Would have backed up volumes which are prefixed with <string> [or <string>] . .
217
218 =item *
219
220 If only the B<-xprefix> argument is provided, or the B<-prefix> and
221 B<-exclude> options are combined:
222
223    Would have backed up volumes which are not prefixed with <string> [nor <string>] . .
224
225 =item *
226
227 If the B<-prefix> and B<-xprefix> arguments are combined:
228
229    Would have backed up volumes which are prefixed with <string> [or <string>] \
230       removing those which are prefixed with <x_string> [or <x_string>] . .
231
232 =item *
233
234 If the B<-prefix>, B<-xprefix>, and B<-exclude> options are provided:
235
236    Would have backed up volumes which are not prefixed with <string> [nor <string>] \
237       adding those which are prefixed with <x_string> [or <x_string>] . .
238
239 =back
240
241 =head1 EXAMPLES
242
243 The following example creates a backup version of every read/write volume
244 listed in the cell's VLDB whose name begins with the string B<user>.
245
246    % vos backupsys -prefix user
247
248 The following example, appropriate in the Example Corporation cell, creates a
249 backup version of every read/write volume on the file server machine
250 C<fs3.example.com>.
251
252    % vos backupsys -server fs3.example.com
253
254 The following example, appropriate in the Example Organization cell, creates a
255 backup version of every read/write volume on the file server machine
256 C<db1.example.org> except those whose name includes the string C<temp>.
257
258    % vos backupsys  -server db1.example.org -prefix '^.*temp'
259
260 The following example creates a backup version of every volume listed in
261 the cell's VLDB, excluding those whose names contain the string C<source>,
262 but including those whose names contain the string C<source.current>.
263
264    % vos backupsys  -prefix '^.*source' -exclude -xprefix '^.*source\.current'
265
266 =head1 PRIVILEGE REQUIRED
267
268 The issuer must be listed in the F</usr/afs/etc/UserList> file on the
269 machine specified with the B<-server> argument and on each database server
270 machine. If the B<-localauth> flag is included, the issuer must instead be
271 logged on to a server machine as the local superuser C<root>.
272
273 =head1 SEE ALSO
274
275 L<backup_addvolentry(8)>,
276 L<vos(1)>,
277 L<vos_backup(1)>
278
279 UNIX manual page for regexp(5)
280
281 =head1 COPYRIGHT
282
283 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
284
285 This documentation is covered by the IBM Public License Version 1.0.  It was
286 converted from HTML to POD by software written by Chas Williams and Russ
287 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.