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 4
 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.