-A archive file implementation

[dump.git] / restore / restore.8.in

diff --git a/restore/restore.8.in b/restore/restore.8.in
index 43954662dbd093b9d8cf26e83614059a0ae9b923..54f289e4fa4e77bd32d9b160b47f1b4c3c11a07a 100644 (file)
--- a/restore/restore.8.in
+++ b/restore/restore.8.in
@@ -29,7 +29,7 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"

-.\"    $Id: restore.8.in,v 1.5 1999/12/05 18:54:25 tiniou Exp $
+.\"    $Id: restore.8.in,v 1.24 2002/01/25 14:59:53 stelian Exp $

 .\"
 .Dd __DATE__
 .Dt RESTORE 8
 .\"
 .Dd __DATE__
 .Dt RESTORE 8


@@ -40,48 +40,63 @@
 .Sh SYNOPSIS
 .Nm restore
 .Fl C
 .Sh SYNOPSIS
 .Nm restore
 .Fl C

-.Op Fl ckMvy
+.Op Fl cklMvVy

 .Op Fl b Ar blocksize
 .Op Fl D Ar filesystem
 .Op Fl f Ar file
 .Op Fl b Ar blocksize
 .Op Fl D Ar filesystem
 .Op Fl f Ar file

+.Op Fl F Ar script
+.Op Fl L Ar limit

 .Op Fl s Ar fileno
 .Op Fl T Ar directory
 .Nm restore
 .Fl i
 .Op Fl s Ar fileno
 .Op Fl T Ar directory
 .Nm restore
 .Fl i

-.Op Fl chkmMNuvy
+.Op Fl achklmMNuvVy
+.Op Fl A Ar file

 .Op Fl b Ar blocksize
 .Op Fl f Ar file
 .Op Fl b Ar blocksize
 .Op Fl f Ar file

+.Op Fl F Ar script
+.Op Fl Q Ar file

 .Op Fl s Ar fileno
 .Op Fl T Ar directory
 .Nm restore
 .Fl R
 .Op Fl s Ar fileno
 .Op Fl T Ar directory
 .Nm restore
 .Fl R

-.Op Fl ckMNuvy
+.Op Fl cklMNuvVy

 .Op Fl b Ar blocksize
 .Op Fl f Ar file
 .Op Fl b Ar blocksize
 .Op Fl f Ar file

+.Op Fl F Ar script

 .Op Fl s Ar fileno
 .Op Fl T Ar directory
 .Nm restore
 .Fl r
 .Op Fl s Ar fileno
 .Op Fl T Ar directory
 .Nm restore
 .Fl r

-.Op Fl ckMNuvy
+.Op Fl cklMNuvVy

 .Op Fl b Ar blocksize
 .Op Fl f Ar file
 .Op Fl b Ar blocksize
 .Op Fl f Ar file

+.Op Fl F Ar script

 .Op Fl s Ar fileno
 .Op Fl T Ar directory
 .Nm restore
 .Fl t
 .Op Fl s Ar fileno
 .Op Fl T Ar directory
 .Nm restore
 .Fl t

-.Op Fl chkMNuvy
+.Op Fl chklMNuvVy
+.Op Fl A Ar file

 .Op Fl b Ar blocksize
 .Op Fl f Ar file
 .Op Fl b Ar blocksize
 .Op Fl f Ar file

+.Op Fl F Ar script
+.Op Fl Q Ar file

 .Op Fl s Ar fileno
 .Op Fl T Ar directory
 .Op Fl s Ar fileno
 .Op Fl T Ar directory

+.Op Fl X Ar filelist

 .Op file ...
 .Nm restore
 .Fl x
 .Op file ...
 .Nm restore
 .Fl x

-.Op Fl chkmMNuvy
+.Op Fl achklmMNuvVy
+.Op Fl A Ar file

 .Op Fl b Ar blocksize
 .Op Fl f Ar file
 .Op Fl b Ar blocksize
 .Op Fl f Ar file

+.Op Fl F Ar script
+.Op Fl Q Ar file

 .Op Fl s Ar fileno
 .Op Fl T Ar directory
 .Op Fl s Ar fileno
 .Op Fl T Ar directory

+.Op Fl X Ar filelist

 .Op file ...
 .Pp
 .in
 .Op file ...
 .Pp
 .in


@@ -122,6 +137,9 @@ disk.
 It first changes its working directory to the root of the filesystem
 that was dumped and compares the tape with the files in its new
 current directory.
 It first changes its working directory to the root of the filesystem
 that was dumped and compares the tape with the files in its new
 current directory.

+See also the
+.Fl L
+flag described below.

 .It Fl i
 This mode allows interactive restoration of files from a dump.
 After reading in the directory information from the dump,
 .It Fl i
 This mode allows interactive restoration of files from a dump.
 After reading in the directory information from the dump,


@@ -258,6 +276,9 @@ Note that the
 flag replaces the function of the old
 .Xr dumpdir 8
 program.
 flag replaces the function of the old
 .Xr dumpdir 8
 program.

+See also the
+.Fl X
+option below.

 .ne 1i
 .It Fl x
 The named files are read from the given media.
 .ne 1i
 .It Fl x
 The named files are read from the given media.


@@ -276,10 +297,38 @@ backup being extracted,
 unless the
 .Fl h
 flag has been specified.
 unless the
 .Fl h
 flag has been specified.

+See also the
+.Fl X
+option below.

 .El
 .Pp
 The following additional options may be specified:
 .Bl -tag -width Ds
 .El
 .Pp
 The following additional options may be specified:
 .Bl -tag -width Ds

+.It Fl a
+In 
+.Fl i
+or
+.Fl x
+mode, 
+.Nm restore 
+does ask the user for the volume number on which the files to
+be extracted are supposed to be (in order to minimise the time
+be reading only the interesting volumes). The 
+.Fl a
+option disables this behaviour and reads all the volumes starting
+with 1. This option is useful when the operator does not know on which
+volume the files to be extracted are and/or when he prefers the
+longer unattended mode rather than the shorter interactive mode.
+.It Fl A Ar archive_file
+Read the table of contents from
+.Ar archive_file
+instead of the media. This option can be used in combination with the 
+.Fl t, 
+.Fl i, 
+or 
+.Fl x 
+options, making it possible to check whether files are on the media 
+without having to mount the media. 

 .It Fl b Ar blocksize
 The number of kilobytes per dump record.
 If the
 .It Fl b Ar blocksize
 The number of kilobytes per dump record.
 If the


@@ -325,17 +374,50 @@ or
 reads from the named file on the remote host using
 .Xr rmt 8 .
 .Pp
 reads from the named file on the remote host using
 .Xr rmt 8 .
 .Pp

-.It Fl k
-Use Kerberos authentication when contacting the remote tape server.
-(Only available if this options was enabled when
-.Nm restore
-was compiled.)
-.Pp
+.It Fl F Ar script
+Run script at the beginning of each tape. The device name and the
+current volume number are passed on the command line.
+The script must return 0 if 
+.Nm
+should continue without asking the user to change the tape, 1 if 
+.Nm
+should continue but ask the user to change the tape. 
+Any other exit code will cause
+.Nm
+to abort.
+For security reasons,
+.Nm
+reverts back to the real user ID and the real group ID before 
+running the script.

 .It Fl h
 Extract the actual directory, 
 rather than the files that it references.
 This prevents hierarchical restoration of complete subtrees
 from the dump.
 .It Fl h
 Extract the actual directory, 
 rather than the files that it references.
 This prevents hierarchical restoration of complete subtrees
 from the dump.

+.It Fl k
+Use Kerberos authentication when contacting the remote tape server.
+(Only available if this options was enabled when
+.Nm restore
+was compiled.)
+.It Fl l
+When doing remote restores, assume the remote file is a
+regular file (instead of a tape device). If you're restoring
+a remote compressed file, you will need to specify this 
+option or 
+.Nm restore
+will fail to access it correctly.
+.It Fl L Ar limit
+The
+.Fl L
+flag allows the user to specify a maximal number of miscompares
+when using
+.Nm restore
+with the
+.Fl C
+option to check the backup. If this limit is reached, 
+.Nm restore
+will abort with an error message. A value of 0 (the default value) 
+disables the check.

 .It Fl m
 Extract by inode numbers rather than by file name.
 This is useful if only a few files are being extracted,
 .It Fl m
 Extract by inode numbers rather than by file name.
 This is useful if only a few files are being extracted,


@@ -355,7 +437,39 @@ The
 .Fl N
 flag causes
 .Nm
 .Fl N
 flag causes
 .Nm

-to only print file names. Files are not extracted.
+to perform a full execution as requested by one of
+.Fl i,
+.Fl R,
+.Fl r,
+.Fl t
+or
+.Fl x
+command without actually writing any file on disk.
+.It Fl Q Ar file
+Use the file
+.Ar file
+in order to read tape position as stored using the dump Quick File
+Access mode, in one of 
+.Fl i,
+.Fl x
+or
+.Fl t
+mode.
+.Pp
+It is recommended to set up the st driver to return logical tape 
+positions rather than physical before calling dump/restore with 
+parameter Q.  Since not all tape devices support physical tape 
+positions those tape devices return an error during dump/restore when
+the st driver is set to the default physical setting.
+Please see the st man page, option MTSETDRVBUFFER, or the mt man
+page, on how to set the driver to return logical tape positions.
+.Pp
+Before calling restore with parameter Q, always make sure the st
+driver is set to return the same type of tape position used during the 
+call to dump. Otherwise restore may be confused.
+.Pp
+This option can be used when restoring from local or remote tapes 
+(see above) or from local or remote files.

 .It Fl s Ar fileno
 Read from the specified
 .Ar fileno
 .It Fl s Ar fileno
 Read from the specified
 .Ar fileno


@@ -384,6 +498,23 @@ The
 (verbose)
 flag causes it to type the name of each file it treats
 preceded by its file type.
 (verbose)
 flag causes it to type the name of each file it treats
 preceded by its file type.

+.It Fl V
+Enables reading multi-volume non-tape mediums like CDROMs.
+.It Fl X Ar filelist
+Read list of files to be listed or extracted from the text file
+.Ar filelist
+in addition to those specified on the command line. This can be used in 
+conjunction with the
+.Fl t
+or
+.Fl x
+commands. The file
+.Ar filelist
+should contain file names separated by newlines.
+.Ar filelist
+may be an ordinary file or
+.Ql Fl
+(the standard input).

 .It Fl y
 Do not ask the user whether to abort the restore in the event of an error.
 Always try to skip over the bad block(s) and continue.
 .It Fl y
 Do not ask the user whether to abort the restore in the event of an error.
 Always try to skip over the bad block(s) and continue.


@@ -458,6 +589,14 @@ After a dump read error,
 may have to resynchronize itself.
 This message lists the number of blocks that were skipped over.
 .El
 may have to resynchronize itself.
 This message lists the number of blocks that were skipped over.
 .El

+.Pp
+.Nm Restore
+exits with zero status on success.
+Tape errors are indicated with an exit code of 1.
+.Pp
+When doing a comparison of files from a dump, an exit code
+of 2 indicates that some files were modified or deleted since
+the dump was made.

 .Sh ENVIRONMENT
 If the following environment variable exists it will be utilized by
 .Nm restore :
 .Sh ENVIRONMENT
 If the following environment variable exists it will be utilized by
 .Nm restore :


@@ -495,6 +634,7 @@ remote shell command to use when doing a network restore (rsh, ssh etc.).
 If this variable is not set,
 .Xr rcmd 3
 will be used, but only root will be able to do a network restore.
 If this variable is not set,
 .Xr rcmd 3
 will be used, but only root will be able to do a network restore.

+.El

 .Sh FILES
 .Bl -tag -width "./restoresymtable" -compact
 .It Pa /dev/st0
 .Sh FILES
 .Bl -tag -width "./restoresymtable" -compact
 .It Pa /dev/st0


@@ -555,21 +695,19 @@ from the restore code - run setuid at your own risk.)
 .Sh AUTHOR
 The
 .Nm dump/restore
 .Sh AUTHOR
 The
 .Nm dump/restore

-backup suit was ported to Linux's Second Extended File System
+backup suite was ported to Linux's Second Extended File System

 by Remy Card <card@Linux.EU.Org>. He maintained the initial versions
 of dump (up and including 0.4b4, released in january 1997).
 .Pp
 Starting with 0.4b5, the new maintainer is Stelian Pop
 .br
 by Remy Card <card@Linux.EU.Org>. He maintained the initial versions
 of dump (up and including 0.4b4, released in january 1997).
 .Pp
 Starting with 0.4b5, the new maintainer is Stelian Pop
 .br

-<pop@cybercable.fr>.
+<stelian@popies.net>.

 .Sh AVAILABILITY
 The
 .Nm dump/restore
 .Sh AVAILABILITY
 The
 .Nm dump/restore

-backup suit is available for anonymous ftp from tsx-11.mit.edu
-in /pub/linux/ALPHA/ext2fs (development versions) or
-/pub/linux/packages/ext2fs (stable versions).
-.Pp
-An alternate downloading location is http://perso.cybercable.fr/pop/dump.
+backup suite is available from 
+.br
+http://dump.sourceforge.net

 .Sh HISTORY
 The
 .Nm restore
 .Sh HISTORY
 The
 .Nm restore