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.