=head1 SYNOPSIS
-backup volrestore -server <I<destination machine>>
-B<-partition> <I<destination partition>>
- -volume <I<volume(s) to restore>>+
- [-extension <I<new volume name extension>>]
- [-date <I<date from which to restore>>+]
- [B<-portoffset> <I<TC port offsets>>+] [-n]
- [B<-localauth>] [B<-cell> <I<cell name>>] [-help]
-
-B<backup volr -s> <I<destination machine>> -pa <I<destination partition>>
-B<-v> <I<volume(s) to restore>>+ [B<-e> <I<new volume name extension>>]
- [B<-d> <I<date from which to restore>>+] [-po <I<TC port offsets>>+]
- [B<-n>] [B<-l>] [B<-c> <I<cell name>>] [-h]
+B<backup volrestore> B<-server> <I<destination machine>>
+ B<-partition> <I<destination partition>>
+ B<-volume> <I<volume(s) to restore>>+
+ [B<-extension> <I<new volume name extension>>]
+ [B<-date> <I<date from which to restore>>+]
+ [B<-portoffset> <I<TC port offsets>>+] [B<-n>]
+ [B<-localauth>] [B<-cell> <I<cell name>>] [B<-help>]
+
+B<backup volr> B<-s> <I<destination machine>>
+ B<-pa> <I<destination partition>> B<-v> <I<volume(s) to restore>>+
+ [B<-e> <I<new volume name extension>>]
+ [B<-d> <I<date from which to restore>>+] [B<-po> <I<TC port offsets>>+]
+ [B<-n>] [B<-l>] [B<-c> <I<cell name>>] [B<-h>]
=head1 DESCRIPTION
-The backup volrestore command restores the contents of one or
-more volumes to the site indicated by the B<-server> and
-B<-partition> arguments. Use the command either to overwrite
-the contents of existing volumes with the restored data or to create new
-volumes while retaining the existing ones. The specified site does not
-have to be the current site for the volumes.
-
-(If the FILE YES instruction appears in the
-B</usr/afs/backup/CFG_>I<device_name> file associated with the
-specified port offset, then the B<backup volrestore> command restores
-data from the backup data file listed for that port offset in the Tape
-Coordinator's B</usr/afs/backup/tapeconfig> file, rather than
-from tape. For the sake of clarity, the following text refers to tapes
-only, but the Backup System handles backup data files in much the same
-way.)
+The B<backup volrestore> command restores the contents of one or more
+volumes to the site indicated by the B<-server> and B<-partition>
+arguments. Use the command either to overwrite the contents of existing
+volumes with the restored data or to create new volumes while retaining
+the existing ones. The specified site does not have to be the current site
+for the volumes.
+
+(If the C<FILE YES> instruction appears in the
+F</usr/afs/backup/CFG_I<device_name>> file associated with the specified
+port offset, then the B<backup volrestore> command restores data from the
+backup data file listed for that port offset in the Tape Coordinator's
+F</usr/afs/backup/tapeconfig> file, rather than from tape. For the sake of
+clarity, the following text refers to tapes only, but the Backup System
+handles backup data files in much the same way.)
The command's arguments can be combined as indicated:
=item *
-To preserve a volume's current contents and also create a new volume
-to house the restored version, use the B<-extension> argument.
-The Backup System creates the new volume on the server and partition named by
-the B<-server> and B<-partition> arguments, assigns it the
-same name as the current volume with the addition of the specified extension,
-and creates a new Volume Location Database (VLDB) entry for it.
-Creating a new volume enables the administrator to compare the two
-versions.
-
+To preserve a volume's current contents and also create a new volume to
+house the restored version, use the B<-extension> argument. The Backup
+System creates the new volume on the server and partition named by the
+B<-server> and B<-partition> arguments, assigns it the same name as the
+current volume with the addition of the specified extension, and creates a
+new Volume Location Database (VLDB) entry for it. Creating a new volume
+enables the administrator to compare the two versions.
=item *
-To overwrite a volume's existing contents with the restored version,
-omit the B<-extension> argument, and specify the site as
-indicated:
-
+To overwrite a volume's existing contents with the restored version, omit
+the B<-extension> argument, and specify the site as indicated:
=over 4
=item *
-To retain the current site, specify it with the -server and
+To retain the current site, specify it with the B<-server> and
B<-partition> arguments.
-
=item *
To move the volume to a different site while overwriting it, specify the
-new site with the B<-server> argument, B<-partition> argument,
-or both. The Backup System creates a new volume at that site, removes
-the existing volume, and updates the site information in the volume's
-VLDB entry. The backup version of the volume is not removed
-automatically from the original site, if it exists. Use the B<vos
-remove> command to remove it and the B<vos backup> command to
-create a backup version at the new site.
-
+new site with the B<-server> argument, B<-partition> argument, or
+both. The Backup System creates a new volume at that site, removes the
+existing volume, and updates the site information in the volume's VLDB
+entry. The backup version of the volume is not removed automatically from
+the original site, if it exists. Use the B<vos remove> command to remove
+it and the B<vos backup> command to create a backup version at the new
+site.
=back
=item *
To restore a volume that no longer exists in the file system, specify its
-name with the B<-volume> argument and use the B<-server> and
-B<-partition> arguments to place it at the desired site. The
-Backup System creates a new volume and new VLDB entry.
-
+name with the B<-volume> argument and use the B<-server> and B<-partition>
+arguments to place it at the desired site. The Backup System creates a new
+volume and new VLDB entry.
=back
-In each case, the command sets each volume's creation date to the date
-and time at which it restores it. The creation date appears in the
-C<Creation> field in the output from the B<vos examine> and
-B<vos listvol> commands.
+In each case, the command sets each volume's creation date to the date and
+time at which it restores it. The creation date appears in the C<Creation>
+field in the output from the B<vos examine> and B<vos listvol> commands.
If restoring all of the volumes that resided on a single partition, it is
-usually more efficient to use the B<backup diskrestore>
-command. If restoring multiple volumes to many different sites, it can
-be more efficient to use the B<backup volsetrestore> command.
-
-By default, the backup volrestore command restores the most
-recent full dump and all subsequent incremental dumps for each volume,
-bringing the restored volumes to the most current possible state. To
-restore the volumes to their state at some time in the past, use the
-B<-date> argument. The Backup System restores the most recent
-full dump and each subsequent incremental dump for which the I<clone
-date> of the volume included in the dump is before the indicated date and
-time (the clone date timestamp appears in the C<clone date> field of
-the output from the B<backup volinfo> command). For backup and
-read-only volumes, the clone date represents the time at which the volume was
-copied from its read/write source; for read/write volumes, it represents
-the time at which the volume was locked for inclusion in the dump. The
-resemblance of a restored volume to its actual state at the indicated time
-depends on the amount of time that elapsed between the volume's clone
-date in the last eligible dump and the specified time.
-
-If the -volume argument specifies the base (read/write) form of
-the volume name, the Backup System searches the Backup Database for the newest
-dump set that includes a dump of either the read/write or the backup version
-of the volume. It restores the dumps of that version of the volume,
-starting with the most recent full dump. If, in contrast, the volume
-name explicitly includes the B<.backup> or
-B<.readonly> extension, the Backup System restores dumps of the
-corresponding volume version only.
+usually more efficient to use the B<backup diskrestore> command. If
+restoring multiple volumes to many different sites, it can be more
+efficient to use the B<backup volsetrestore> command.
+
+By default, the backup volrestore command restores the most recent full
+dump and all subsequent incremental dumps for each volume, bringing the
+restored volumes to the most current possible state. To restore the
+volumes to their state at some time in the past, use the B<-date>
+argument. The Backup System restores the most recent full dump and each
+subsequent incremental dump for which the I<clone date> of the volume
+included in the dump is before the indicated date and time (the clone date
+timestamp appears in the C<clone date> field of the output from the
+B<backup volinfo> command). For backup and read-only volumes, the clone
+date represents the time at which the volume was copied from its
+read/write source; for read/write volumes, it represents the time at which
+the volume was locked for inclusion in the dump. The resemblance of a
+restored volume to its actual state at the indicated time depends on the
+amount of time that elapsed between the volume's clone date in the last
+eligible dump and the specified time.
+
+If the B<-volume> argument specifies the base (read/write) form of the
+volume name, the Backup System searches the Backup Database for the newest
+dump set that includes a dump of either the read/write or the backup
+version of the volume. It restores the dumps of that version of the
+volume, starting with the most recent full dump. If, in contrast, the
+volume name explicitly includes the C<.backup> or C<.readonly> extension,
+the Backup System restores dumps of the corresponding volume version only.
To generate a list of the tapes the Backup System needs to perform the
-restore operation, without actually performing it, combine the B<-n>
-flag with the options to be used on the actual command.
+restore operation, without actually performing it, combine the B<-n> flag
+with the options to be used on the actual command.
If all of the full and incremental dumps of all relevant volumes were not
written to a type of tape that a single Tape Coordinator can read, use the
-B<-portoffset> argument to list multiple port offset numbers in the
-order in which the tapes are needed (first list the port offset for the full
+B<-portoffset> argument to list multiple port offset numbers in the order
+in which the tapes are needed (first list the port offset for the full
dump, second the port offset for the level 1 incremental dump, and so
-on). If restoring multiple volumes, the same ordered list of port
-offsets must apply to all of them. If not, either issue this command
-separately for each volume, or use the B<vos volsetrestore> command
-after defining groups of volumes that were dumped to compatible tape
-types. For further discussion, see the I<IBM AFS Administration
-Guide>.
-
-The Tape Coordinator's default response to this command is to access
-the first tape it needs by invoking the B<MOUNT> instruction in the
-local B</usr/afs/backup/CFG_>I<device_name> file, or by
-prompting the backup operator to insert the tape if there is no
-B<MOUNT> instruction. However, if the B<AUTOQUERY NO>
-instruction appears in the B<CFG_>I<device_name> file, or if the
-issuer of the B<butc> command included the B<-noautoquery>
+on). If restoring multiple volumes, the same ordered list of port offsets
+must apply to all of them. If not, either issue this command separately
+for each volume, or use the B<vos volsetrestore> command after defining
+groups of volumes that were dumped to compatible tape types. For further
+discussion, see the I<IBM AFS Administration Guide>.
+
+The Tape Coordinator's default response to this command is to access the
+first tape it needs by invoking the B<MOUNT> instruction in the local
+F</usr/afs/backup/CFG_I<device_name>> file, or by prompting the backup
+operator to insert the tape if there is no C<MOUNT> instruction. However,
+if the C<AUTOQUERY NO> instruction appears in the F<CFG_I<device_name>>
+file, or if the issuer of the B<butc> command included the B<-noautoquery>
flag, the Tape Coordinator instead expects the tape to be in the device
-already. If it is not, or is the wrong tape, the Tape Coordinator
-invokes the B<MOUNT> instruction or prompts the operator. It
-also invokes the B<MOUNT> instruction or prompts for any additional
-tapes needed to complete the restore operation; the backup operator must
-arrange to provide them.
+already. If it is not, or is the wrong tape, the Tape Coordinator invokes
+the C<MOUNT> instruction or prompts the operator. It also invokes the
+C<MOUNT> instruction or prompts for any additional tapes needed to
+complete the restore operation; the backup operator must arrange to
+provide them.
=head1 OPTIONS
=over 4
-=item -server
+=item B<-server> <I<destination machine>>
-Names the file server machine on which to restore each volume. If
-this argument and the B<-partition> argument indicate a site other
-than the current site for each volume, and the B<-extension> argument
-is not also provided, the Backup System removes the existing volumes from
-their current sites, places the restored contents at the specified site, and
+Names the file server machine on which to restore each volume. If this
+argument and the B<-partition> argument indicate a site other than the
+current site for each volume, and the B<-extension> argument is not also
+provided, the Backup System removes the existing volumes from their
+current sites, places the restored contents at the specified site, and
changes the site information in the volume's VLDB entry.
-=item -partition
+=item B<-partition> <I<destination partition>>
-Names the partition to which to restore each volume. If this
-argument and the B<-server> argument indicate a site other than the
-current site for each volume, and the B<-extension> argument is not
-also provided, the Backup System removes the existing volumes from their
-current sites, places the restored contents at the specified site, and changes
-the site information in the volume's VLDB entry.
+Names the partition to which to restore each volume. If this argument and
+the B<-server> argument indicate a site other than the current site for
+each volume, and the B<-extension> argument is not also provided, the
+Backup System removes the existing volumes from their current sites,
+places the restored contents at the specified site, and changes the site
+information in the volume's VLDB entry.
-=item -volume
+=item B<-volume> <I<volume to restore>>+
Names one or more volumes to restore, using the volume name as listed in
-the Backup Database. Provide the base (read/write) name of each volume
-to have the Backup System search the Backup Database for the newest dump set
+the Backup Database. Provide the base (read/write) name of each volume to
+have the Backup System search the Backup Database for the newest dump set
that includes a dump of either the read/write or the backup version of the
-volume; it restores the dumps of that version of the volume, starting
-with the most recent full dump. If, in contrast, a volume name
-explicitly includes the B<.backup> or
-B<.readonly> extension, the Backup System restores dumps of the
-corresponding volume version only.
+volume; it restores the dumps of that version of the volume, starting with
+the most recent full dump. If, in contrast, a volume name explicitly
+includes the C<.backup> or C<.readonly> extension, the Backup System
+restores dumps of the corresponding volume version only.
-=item -extension
+=item B<-extension> <I<new volume name extension>>
Creates a new volume to house the restored data, with a name derived by
appending the specified string to each volume named by the B<-volume>
-argument. The Backup System creates a new VLDB entry for the
-volume. Any string other than B<.readonly> or
-B<.backup> is acceptable, but the combination of the existing
-volume name and extension cannot exceed 22 characters in length. To use
-a period to separate the extension from the name, specify it as the first
-character of the string (as in B<.rst>, for example).
-
-=item -date
-
-Specifies a date and optionally time; the restored volume includes
-data from dumps performed before the date only. Provide a value in the
-format I<mm>/I<dd>/I<yyyy> [I<hh>:I<MM>],
-where the required I<mm/dd/yyyy> portion indicates the month
-(I<mm>), day (I<dd>), and year (I<yyyy>), and the optional
-I<hh:MM> portion indicates the hour and minutes in 24-hour format
-(for example, the value B<14:36> represents 2:36
-p.m.). If omitted, the time defaults to 59 seconds after
-midnight (00:00:59 hours).
-
-Valid values for the year range from 1970 to
-B<2037>; higher values are not valid because the latest possible
-date in the standard UNIX representation is in February 2038. The
-command interpreter automatically reduces any later date to the maximum
-value.
+argument. The Backup System creates a new VLDB entry for the volume. Any
+string other than C<.readonly> or C<.backup> is acceptable, but the
+combination of the existing volume name and extension cannot exceed 22
+characters in length. To use a period to separate the extension from the
+name, specify it as the first character of the string (as in C<.rst>, for
+example).
+
+=item B<-date> <I<date from which to restore>>+
+
+Specifies a date and optionally time; the restored volume includes data
+from dumps performed before the date only. Provide a value in the format
+I<mm/dd/yyyy> [I<hh>:I<MM>], where the required I<mm/dd/yyyy> portion
+indicates the month (I<mm>), day (I<dd>), and year (I<yyyy>), and the
+optional I<hh:MM> portion indicates the hour and minutes in 24-hour format
+(for example, the value C<14:36> represents 2:36 p.m.). If omitted, the
+time defaults to 59 seconds after midnight (00:00:59 hours).
+
+Valid values for the year range from C<1970> to C<2037>; higher values are
+not valid because the latest possible date in the standard UNIX
+representation is in February 2038. The command interpreter automatically
+reduces any later date to the maximum value.
If this argument is omitted, the Backup System restores all possible dumps
including the most recently created.
-=item -portoffset
+=item B<-portoffset> <I<TC port offest>>+
Specifies one or more port offset numbers (up to a maximum of 128), each
-corresponding to a Tape Coordinator to use in the operation. If there
-is more than one value, the Backup System uses the first one when restoring
+corresponding to a Tape Coordinator to use in the operation. If there is
+more than one value, the Backup System uses the first one when restoring
the full dump of each volume, the second one when restoring the level 1
-incremental dump of each volume, and so on. It uses the final value in
-the list when restoring dumps at the corresponding depth in the dump hierarchy
+incremental dump of each volume, and so on. It uses the final value in the
+list when restoring dumps at the corresponding depth in the dump hierarchy
and all dumps at lower levels.
Provide this argument unless the default value of 0 (zero) is appropriate
-for all dumps. If B<0> is just one of the values in the list,
-provide it explicitly in the appropriate order.
+for all dumps. If C<0> is just one of the values in the list, provide it
+explicitly in the appropriate order.
-=item -n
+=item B<-n>
Displays the list of tapes that contain the dumps required by the restore
operation, without actually performing the operation.
-=item -localauth
+=item B<-localauth>
Constructs a server ticket using a key from the local
-B</usr/afs/etc/KeyFile> file. The B<backup> command
-interpreter presents it to the Backup Server, Volume Server and VL Server
-during mutual authentication. Do not combine this flag with the
-B<-cell> argument. For more details, see the introductory
-B<backup> reference page.
+F</usr/afs/etc/KeyFile> file. The B<backup> command interpreter presents
+it to the Backup Server, Volume Server and VL Server during mutual
+authentication. Do not combine this flag with the B<-cell> argument. For
+more details, see L<backup(8)>.
-=item -cell
+=item B<-cell> <I<cell name>>
-Names the cell in which to run the command. Do not combine this
-argument with the B<-localauth> flag. For more details, see the
-introductory B<backup> reference page.
+Names the cell in which to run the command. Do not combine this argument
+with the B<-localauth> flag. For more details, see L<backup(8)>.
-=item -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
=head1 OUTPUT
-If the issuer includes the -n flag with the command, the
-following string appears at the head of the list of the tapes necessary to
-complete the restore operation.
+If the issuer includes the B<-n> flag with the command, the following
+string appears at the head of the list of the tapes necessary to complete
+the restore operation.
Tapes needed:
=head1 EXAMPLES
-The following command restores the volume user.pat to
-partition B</vicepa> on machine
-B<fs5.abc.com>:
+The following command restores the volume user.pat to partition F</vicepa>
+on machine C<fs5.abc.com>:
% backup volrestore -server fs5.abc.com -partition a -volume user.pat
-The following command restores the volumes user.smith and
-B<user.terry> to partition B</vicepb> on machine
-B<fs4.abc.com>, adding a B<.rst>
-extension to each volume name and preserving the existing
-B<user.smith> and B<user.terry> volumes.
-Only dumps created before 5:00 p.m. on 31 January 1998 are
-restored. (The command is shown here on multiple lines only for
-legibility reasons.)
+The following command restores the volumes C<user.smith> and C<user.terry>
+to partition F</vicepb> on machine C<fs4.abc.com>, adding a C<.rst>
+extension to each volume name and preserving the existing C<user.smith>
+and C<user.terry> volumes. Only dumps created before 5:00 p.m. on 31
+January 1998 are restored. (The command is shown here on multiple lines
+only for legibility reasons.)
% backup volrestore -server fs4.abc.com -partition b \
-volume user.smith user.terry \
-extension .rst -date 1/31/1998 17:00
-The following command restores the volume user.pat to
-partition B</vicepb> on machine
-B<fs4.abc.com>. The Tape Coordinator with port
-offset 1 handles the tape containing the full dump; the Tape Coordinator
-with port offset 0 handles all tapes containing incremental dumps. (The
-command is shown here on two lines only for legibility reasons.)
+The following command restores the volume user.pat to partition F</vicepb>
+on machine C<fs4.abc.com>. The Tape Coordinator with port offset 1 handles
+the tape containing the full dump; the Tape Coordinator with port offset 0
+handles all tapes containing incremental dumps. (The command is shown here
+on two lines only for legibility reasons.)
% backup volrestore -server fs5.abc.com -partition a \
-volume user.pat -portoffset 1 0
=head1 PRIVILEGE REQUIRED
-The issuer must be listed in the /usr/afs/etc/UserList file on
-every machine where the Backup Server or Volume Location (VL) Server is
-running, and on every file server machine that houses an affected
-volume. If the B<-localauth> flag is included, the issuer must
-instead be logged on to a server machine as the local superuser
-B<root>.
+The issuer must be listed in the F</usr/afs/etc/UserList> file on every
+machine where the Backup Server or Volume Location (VL) Server is running,
+and on every file server machine that houses an affected volume. If the
+B<-localauth> flag is included, the issuer must instead be logged on to a
+server machine as the local superuser C<root>.
=head1 SEE ALSO
-L<backup(1)>,
-L<backup_dump(1)>,
-L<backup_diskrestore(1)>,
-L<backup_volsetrestore(1)>,
-L<butc(1)>,
+L<backup(8)>,
+L<backup_dump(8)>,
+L<backup_diskrestore(8)>,
+L<backup_volsetrestore(8)>,
+L<butc(8)>,
L<vos_backup(1)>,
L<vos_remove(1)>
git://git.openafs.org / openafs.git / blobdiff