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 =item *
  86
  87 A simple character string, which matches volumes whose name begin with the
  88 string. All characters are interpreted literally (that is, characters that
  89 potentially have special meaning to the command shell, such as the period,
  90 have only their literal meaning).
  91
  92 =item *
  93
  94 A regular expression, which matches volumes whose names contain the
  95 expressions. Place a caret (C<^>) at the beginning of the expression, and
  96 enclose the entire string in single quotes (C<''>). Explaining regular
  97 expressions is outside the scope of this reference page; see the UNIX
  98 manual page for regexp(5) or (for a brief introduction)
  99 L<backup_addvolentry(8)>. As an example, the following expression matches
 100 volumes that have the string C<aix> anywhere in their names:
 101
 102    -prefix  '^.*aix'
 103
 104 To display a list of the volumes to be cloned, without actually cloning
 105 them, include the B<-dryrun> flag. To display a statement that summarizes
 106 the criteria being used to select volume, include the B<-verbose> flag.
 107
 108 This command can be used to clone a single read/write volume; specify its
 109 complete name as the B<-prefix> argument. However, it is more efficient to
 110 use the B<vos backup> command, which employs a more streamlined technique
 111 for finding a single volume.
 112
 113 =head1 OPTIONS
 114
 115 =over 4
 116
 117 =item B<-prefix> <I<common prefix>>
 118
 119 Specifies one or more simple character strings or regular expressions of
 120 any length; a volume whose name includes the string is placed on the set
 121 of volumes to be cloned. Include field separators (such as periods) if
 122 appropriate. This argument can be combined with any combination of the
 123 B<-server>, B<-partition>, B<-exclude>, and B<-xprefix> options.
 124
 125 =item B<-server> <I<machine name>>
 126
 127 Identifies the file server machine where each read/write source volume
 128 resides. Provide the machine's IP address or its host name (either fully
 129 qualified or using an unambiguous abbreviation). For details, see
 130 L<vos(1)>.
 131
 132 This argument can be combined with any combination of the B<-prefix>,
 133 B<-partition>, B<-exclude>, and B<-xprefix> options.
 134
 135 =item B<-partition> <I<partition name>>
 136
 137 Identifies the partition where each read/write source volume
 138 resides. Provide the partition's complete name with preceding slash (for
 139 example, C</vicepa>) or use one of the three acceptable abbreviated
 140 forms. For details, see L<vos(1)>.
 141
 142 This argument can be combined with any combination of the B<-prefix>,
 143 B<-server>, B<-exclude>, and B<-xprefix> options.
 144
 145 =item B<-exclude>
 146
 147 Reverses the meaning of the B<-prefix> or B<-xprefix> argument. This flag
 148 can be combined with any combination of the B<-prefix>, B<-server>,
 149 B<-partition>, and B<-xprefix> options.
 150
 151 =item B<-xprefix> <I<negative prefix>>
 152
 153 Specifies a simple character string or regular expression of any length; a
 154 volume whose name includes the string is removed from the set of volumes
 155 to be cloned. Include field separators (such as periods) if
 156 appropriate. This argument can be combined with any combination of the
 157 B<-prefix>, B<-server>, B<-partition>, and B<-exclude> options.
 158
 159 =item B<-dryrun>
 160
 161 Displays on the standard output stream a list of the volumes to be cloned,
 162 without actually cloning them.
 163
 164 =item B<-cell> <I<cell name>>
 165
 166 Names the cell in which to run the command. Do not combine this argument
 167 with the B<-localauth> flag. For more details, see L<vos(1)>.
 168
 169 =item B<-noauth>
 170
 171 Assigns the unprivileged identity C<anonymous> to the issuer. Do not
 172 combine this flag with the B<-localauth> flag. For more details, see
 173 L<vos(1)>.
 174
 175 =item B<-localauth>
 176
 177 Constructs a server ticket using a key from the local
 178 F</usr/afs/etc/KeyFile> file. The B<vos> command interpreter presents it
 179 to the Volume Server and Volume Location Server during mutual
 180 authentication. Do not combine this flag with the B<-cell> argument or
 181 B<-noauth> flag. For more details, see L<vos(1)>.
 182
 183 =item B<-verbose>
 184
 185 Produces on the standard output stream a detailed trace of the command's
 186 execution. If this argument is omitted, only warnings and error messages
 187 appear.
 188
 189 =item B<-help>
 190
 191 Prints the online help for this command. All other valid options are
 192 ignored.
 193
 194 =back
 195
 196 =head1 OUTPUT
 197
 198 The command generates the following messages on the standard output stream
 199 to confirm that the operation was successful:
 200
 201    done
 202    Total volumes backed up: <number_cloned>; failed to backup: <failures>
 203
 204 If the B<-dryrun> flag is included, a list of the volumes to be backed up
 205 precedes the standard confirmation messages.
 206
 207 If the B<-verbose> flag is included but not the B<-dryrun> flag, the
 208 following messages appear for each volume. The output concludes with the
 209 standard confirmation messages.
 210
 211    Creating backup volume for <volume_name> on <date/time>
 212    {Recloning backup volume | Creating a new backup clone} <backup_volumeID> . . .done
 213
 214 If both the B<-dryrun> and B<-verbose> flags are included, the output
 215 begins with a statement summarizing the criteria being used to select the
 216 volumes, followed by a list of the volumes and the standard confirmation
 217 messages. The format of the criteria summary statement depends on which
 218 other options are provided:
 219
 220 =over 4
 221
 222 =item *
 223
 224 If only the B<-prefix> argument is provided, or the B<-xprefix> and
 225 B<-exclude> options are combined:
 226
 227    Would have backed up volumes which are prefixed with <string> [or <string>] . .
 228
 229 =item *
 230
 231 If only the B<-xprefix> argument is provided, or the B<-prefix> and
 232 B<-exclude> options are combined:
 233
 234    Would have backed up volumes which are not prefixed with <string> [nor <string>] . .
 235
 236 =item *
 237
 238 If the B<-prefix> and B<-xprefix> arguments are combined:
 239
 240    Would have backed up volumes which are prefixed with <string> [or <string>] \
 241       removing those which are prefixed with <x_string> [or <x_string>] . .
 242
 243 =item *
 244
 245 If the B<-prefix>, B<-xprefix>, and B<-exclude> options are provided:
 246
 247    Would have backed up volumes which are not prefixed with <string> [nor <string>] \
 248       adding those which are prefixed with <x_string> [or <x_string>] . .
 249
 250 =back
 251
 252 =head1 EXAMPLES
 253
 254 The following example creates a backup version of every read/write volume
 255 listed in the cell's VLDB whose name begins with the string B<user>.
 256
 257    % vos backupsys -prefix user
 258
 259 The following example, appropriate in the ABC Corporation cell, creates a
 260 backup version of every read/write volume on the file server machine
 261 C<fs3.abc.com>.
 262
 263    % vos backupsys -server fs3.abc.com
 264
 265 The following example, appropriate in the State University cell, creates a
 266 backup version of every read/write volume on the file server machine
 267 C<db1.stateu.edu> except those whose name includes the string C<temp>.
 268
 269    % vos backupsys  -server db1.stateu.edu -prefix '^.*temp'
 270
 271 The following example creates a backup version of every volume listed in
 272 the cell's VLDB, excluding those whose names contain the string C<source>,
 273 but including those whose names contain the string C<source.current>.
 274
 275    % vos backupsys  -prefix '^.*source' -exclude -xprefix '^.*source\.current'
 276
 277 =head1 PRIVILEGE REQUIRED
 278
 279 The issuer must be listed in the F</usr/afs/etc/UserList> file on the
 280 machine specified with the B<-server> argument and on each database server
 281 machine. If the B<-localauth> flag is included, the issuer must instead be
 282 logged on to a server machine as the local superuser C<root>.
 283
 284 =head1 SEE ALSO
 285
 286 L<backup_addvolentry(8)>,
 287 L<vos(1)>,
 288 L<vos_backup(1)>
 289
 290 UNIX manual page for regexp(5)
 291
 292 =head1 COPYRIGHT
 293
 294 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
 295
 296 This documentation is covered by the IBM Public License Version 1.0.  It was
 297 converted from HTML to POD by software written by Chas Williams and Russ
 298 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.