doc/man-pages/pod1/vos_restore.pod

   1 =head1 NAME
   2
   3 vos_restore - Converts an ASCII dump file into an AFS volume
   4
   5 =head1 SYNOPSIS
   6
   7 =for html
   8 <div class="synopsis">
   9
  10 B<vos restore> S<<< B<-server> <I<machine name>> >>>
  11     S<<< B<-partition> <I<partition name>> >>>
  12     S<<< B<-name> <I<name of volume to be restored>> >>>
  13     S<<< [B<-file> <I<dump file>>] >>>
  14     S<<< [B<-id> <I<volume ID>>] >>>
  15     S<<< [B<-overwrite> (abort | full | incremental)] >>>
  16     [B<-offline>] [B<-readonly>]
  17     S<<< [B<-creation> (dump | keep | new)] >>>
  18     S<<< [B<-lastupdate> (dump | keep | new)] >>>
  19     [B<-nodelete>] S<<< [B<-cell> <I<cell name>>] >>>
  20     [B<-noauth>] [B<-localauth>]
  21     [-verbose] [B<-encrypt>] [B<-noresolve>] [B<-help>]
  22
  23 B<vos res> S<<< B<-s> <I<machine name>> >>>
  24     S<<< B<-p> <I<partition name>> >>>
  25     S<<< B<-na> <I<name of volume to be restored>> >>>
  26     S<<< [B<-f> <I<dump file>>] >>>
  27     S<<< [B<-i> <I<volume ID>>] >>>
  28     S<<< [B<-ov> (a | f | i)] >>>
  29     [B<-of>] [B<-r>]
  30     S<<< [B<-cr> (d | k | n)] >>>
  31     S<<< [B<-la> (d | k | n)] >>>
  32     [B<-nod>] S<<< [B<-c> <I<cell name>>] >>>
  33     [B<-noa>] [B<-lo>] [B<-v>] [B<-e>] [B<-nor>] [B<-h>]
  34
  35 =for html
  36 </div>
  37
  38 =head1 DESCRIPTION
  39
  40 The B<vos restore> command converts a volume dump file previously created
  41 with the B<vos dump> command from ASCII into the volume format appropriate
  42 for the machine type indicated by the B<-server> argument, and restores it
  43 as a read/write volume to the partition named by the B<-partition>
  44 argument on that machine. The Volume Server assigns the volume name
  45 indicated with the B<-name> argument, and resets the volume's creation
  46 timestamp to the time at which the restore operation begins (the creation
  47 timestamp is stored in the volume header and reported in the C<Creation>
  48 field in the output from the B<vos examine> and B<vos listvol> commands.)
  49
  50 Use the B<-file> argument to name the dump file, or omit the argument to
  51 provide the file via the standard input stream, presumably through a
  52 pipe. The pipe can be named, which enables interoperation with third-party
  53 backup utilities.
  54
  55 As described in the following list, the command can create a completely
  56 new volume or overwrite an existing volume. In all cases, the full dump of
  57 the volume must be restored before any incremental dumps. If there are
  58 multiple incremental dump files, they must be restored in the order they
  59 were created.
  60
  61 =over 4
  62
  63 =item *
  64
  65 To create a new read/write volume, use the B<-name> argument to specify a
  66 volume name that does not already exist in the Volume Location Database
  67 (VLDB), and the B<-server> and B<-partition> arguments to specify the new
  68 volume's site. It is best to omit the B<-id> argument so that the Volume
  69 Location (VL) Server allocates a volume ID automatically. Do not include
  70 the B<-overwrite> argument, because there is no existing volume to
  71 overwrite.
  72
  73 =item *
  74
  75 To overwrite an existing volume at its current site, specify its name and
  76 site with the B<-name>, B<-server>, and B<-partition> arguments. The
  77 volume retains its current volume ID number unless the B<-id> argument is
  78 provided. Specify the value C<f> or C<i> for the B<-overwrite> argument to
  79 indicate whether the dump file is full or incremental, respectively.
  80
  81 =item *
  82
  83 To overwrite an existing volume and move it to a new site, specify its
  84 name and the new site with the B<-name>, B<-server>, and B<-partition>
  85 arguments. The volume retains its current volume ID number unless the
  86 B<-id> argument is provided. The volume is removed from its original
  87 site. Specify the value C<f> for the B<-overwrite> argument to indicate
  88 that the dump file is a full dump (it is not possible to restore an
  89 incremental dump and move the volume at the same time).
  90
  91 =back
  92
  93 If the volume named by the B<-name> argument already exists and the
  94 B<-overwrite> argument is omitted, the command interpreter produces the
  95 following prompt:
  96
  97    Do you want to do a full/incremental restore or abort? [fia](a):
  98
  99 Respond by entering one of the following values:
 100
 101 =over 4
 102
 103 =item *
 104
 105 C<f> if restoring a full dump file
 106
 107 =item *
 108
 109 C<i> if restoring an incremental dump file
 110
 111 =item *
 112
 113 C<a> or Return to cancel the restore operation
 114
 115 =back
 116
 117 =head1 CAUTIONS
 118
 119 If the B<-file> argument is omitted, the issuer must provide all other
 120 necessary arguments, because the standard input stream is unavailable for
 121 responding to the command interpreter's prompts for missing
 122 information. In particular, the issuer must provide the B<-overwrite>
 123 argument if overwriting an existing volume.
 124
 125 =head1 OPTIONS
 126
 127 =over 4
 128
 129 =item B<-server> <I<server name>>
 130
 131 Identifies the file server machine onto which to restore the
 132 volume. Provide the machine's IP address or its host name (either fully
 133 qualified or using an unambiguous abbreviation). For details, see
 134 L<vos(1)>.
 135
 136 =item B<-partition> <I<partition name>>
 137
 138 Identifies the partition (on the file server machine specified by the
 139 B<-server> argument) onto which to restore the volume. Provide the
 140 partition's complete name with preceding slash (for example, F</vicepa>)
 141 or use one of the three acceptable abbreviated forms. For details, see
 142 L<vos(1)>.
 143
 144 =item B<-name> <I<name of volume>>
 145
 146 Specifies the name under which to restore the volume. It can be up to 22
 147 characters long, but cannot end with a C<.readonly> or C<.backup>
 148 extension. If the volume already exists, it is overwritten subject to the
 149 value of the B<-overwrite> argument.
 150
 151 =item B<-file> <I<dump file>>
 152
 153 Names the dump file to restore. Incomplete pathnames are interpreted
 154 relative to the current working directory. Omit this argument to provide
 155 the dump file via the standard input stream.
 156
 157 =item B<-id> <I<volume ID>>
 158
 159 Specifies the volume ID number to assign to the restored volume.
 160
 161 =item B<-overwrite> (a | f | i)
 162
 163 Specifies which type of dump file is being restored when overwriting an
 164 existing volume. Provide one of the following values:
 165
 166 =over 4
 167
 168 =item *
 169
 170 C<a> to terminate the restore operation.
 171
 172 =item *
 173
 174 C<f> if restoring a full dump file.
 175
 176 =item *
 177
 178 C<i> if restoring an incremental dump file. This value is not acceptable
 179 if the B<-server> and B<-partition> arguments do not indicate the volume's
 180 current site.
 181
 182 =back
 183
 184 This argument is mandatory if the B<-file> argument is not provided.
 185
 186 =item B<-offline>
 187
 188 Leaves the new volume flagged as off-line in the volume database.
 189
 190 =item B<-readonly>
 191
 192 Flags the new volume as read-only in the volume database.
 193
 194 =item B<-nodelete>
 195
 196 This option is available in OpenAFS clients 1.4.7 or
 197 later and 1.5.31 or later. This option can be used with OpenAFS server
 198 versions 1.4.1 or later and 1.5.0 or later.
 199
 200 =item B<-cell> <I<cell name>>
 201
 202 Names the cell in which to run the command. Do not combine this argument
 203 with the B<-localauth> flag. For more details, see L<vos(1)>.
 204
 205 =item B<-noauth>
 206
 207 Assigns the unprivileged identity C<anonymous> to the issuer. Do not
 208 combine this flag with the B<-localauth> flag. For more details, see
 209 L<vos(1)>.
 210
 211 =item B<-localauth>
 212
 213 Constructs a server ticket using a key from the local
 214 F</usr/afs/etc/KeyFile> file. The B<vos> command interpreter presents it
 215 to the Volume Server and Volume Location Server during mutual
 216 authentication. Do not combine this flag with the B<-cell> argument or
 217 B<-noauth> flag. For more details, see L<vos(1)>.
 218
 219 =item B<-verbose>
 220
 221 Produces on the standard output stream a detailed trace of the command's
 222 execution. If this argument is omitted, only warnings and error messages
 223 appear.
 224
 225 =item B<-encrypt>
 226
 227 Encrypts the command so that the operation's results are not transmitted
 228 across the network in clear text. This option is available in OpenAFS
 229 versions 1.4.11 or later and 1.5.60 or later.
 230
 231 =item B<-noresolve>
 232
 233 Shows all servers as IP addresses instead of the DNS name. This is very
 234 useful when the server address is registered as 127.0.0.1 or when dealing
 235 with multi-homed servers. This option is available in OpenAFS
 236 versions 1.4.8 or later and 1.5.35 or later.
 237
 238 =item B<-help>
 239
 240 Prints the online help for this command. All other valid options are
 241 ignored.
 242
 243 =back
 244
 245 =head1 EXAMPLES
 246
 247 The following command restores the contents of the dump file
 248 F</afs/abc.com/common/dumps/terry.dump> to the F</vicepc> partition on the
 249 file server machine C<fs3.abc.com>. The restored volume is named
 250 C<user.terry>.
 251
 252    % cd /afs/abc.com/common/dumps
 253    % vos restore -file terry.dump -server fs3.abc.com -partition c \
 254        -name user.terry
 255
 256 =head1 PRIVILEGE REQUIRED
 257
 258 The issuer must be listed in the F</usr/afs/etc/UserList> file on the
 259 machine specified with the B<-server> argument and on each database server
 260 machine. If the B<-localauth> flag is included, the issuer must instead be
 261 logged on to a server machine as the local superuser C<root>.
 262
 263 =head1 SEE ALSO
 264
 265 L<restorevol(1)>,
 266 L<vos(1)>,
 267 L<vos_dump(1)>,
 268 L<vos_examine(1)>,
 269 L<vos_listvol(1)>
 270
 271 =head1 COPYRIGHT
 272
 273 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
 274
 275 This documentation is covered by the IBM Public License Version 1.0.  It was
 276 converted from HTML to POD by software written by Chas Williams and Russ
 277 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.