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