diff options
Diffstat (limited to 'sbin/restore/restore.8')
| -rw-r--r-- | sbin/restore/restore.8 | 405 |
1 files changed, 405 insertions, 0 deletions
diff --git a/sbin/restore/restore.8 b/sbin/restore/restore.8 new file mode 100644 index 000000000000..dfe7d681ee95 --- /dev/null +++ b/sbin/restore/restore.8 @@ -0,0 +1,405 @@ +.\" Copyright (c) 1985, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)restore.8 8.2 (Berkeley) 12/11/93 +.\" +.Dd December 11, 1993 +.Dt RESTORE 8 +.Os BSD 4 +.Sh NAME +.Nm restore +.Nd "restore files or file systems from backups made with dump" +.Sh SYNOPSIS +.Nm restore +.Ar key +.Op Ar name Ar ... +.Sh DESCRIPTION +The +.Nm restore +command performs the inverse function of +.Xr dump 8 . +A full backup of a file system may be restored and +subsequent incremental backups layered on top of it. +Single files and +directory subtrees may be restored from full or partial +backups. +.Nm Restore +works across a network; +to do this see the +.Fl f +flag described below. +The actions +of +.Nm restore +are controlled by the given +.Cm key , +which +is a string of characters containing +at most one function letter and possibly +one or more function modifiers. +Other arguments to the command are file or directory +names specifying the files that are to be restored. +Unless the +.Cm h +key is specified (see below), +the appearance of a directory name refers to +the files and (recursively) subdirectories of that directory. +.Pp +The function portion of +the key is specified by one of the following letters: +.Bl -tag -width Ds +.It Cm r +Restore (rebuild a file system). +The target file system should be made pristine with +.Xr newfs 8 , +mounted and the +user +.Xr cd Ns 'd +into the pristine file system +before starting the restoration of the initial level 0 backup. If the +level 0 restores successfully, the +.Cm r +key may be used to restore +any necessary incremental backups on top of the level 0. +The +.Cm r +key precludes an interactive file extraction and can be +detrimental to one's health if not used carefully (not to mention +the disk). An example: +.Bd -literal -offset indent +newfs /dev/rrp0g eagle +mount /dev/rp0g /mnt +cd /mnt + +restore rf /dev/rst8 +.Ed +.Pp +Note that +.Nm restore +leaves a file +.Pa restoresymtable +in the root directory to pass information between incremental +restore passes. +This file should be removed when the last incremental has been +restored. +.Pp +.Nm Restore , +in conjunction with +.Xr newfs 8 +and +.Xr dump 8 , +may be used to modify file system parameters +such as size or block size. +.It Cm R +.Nm Restore +requests a particular tape of a multi volume set on which to restart +a full restore +(see the +.Cm r +key above). +This is useful if the restore has been interrupted. +.It Cm x +The named files are read from the given media. +If a named file matches a directory whose contents +are on the backup +and the +.Cm h +key is not specified, +the directory is recursively extracted. +The owner, modification time, +and mode are restored (if possible). +If no file argument is given, +then the root directory is extracted, +which results in the entire content of the +backup being extracted, +unless the +.Cm h +key has been specified. +.It Cm t +The names of the specified files are listed if they occur +on the backup. +If no file argument is given, +then the root directory is listed, +which results in the entire content of the +backup being listed, +unless the +.Cm h +key has been specified. +Note that the +.Cm t +key replaces the function of the old +.Xr dumpdir 8 +program. +.It Cm i +This mode allows interactive restoration of files from a dump. +After reading in the directory information from the dump, +.Nm restore +provides a shell like interface that allows the user to move +around the directory tree selecting files to be extracted. +The available commands are given below; +for those commands that require an argument, +the default is the current directory. +.Bl -tag -width Fl +.It Ic add Op Ar arg +The current directory or specified argument is added to the list of +files to be extracted. +If a directory is specified, then it and all its descendents are +added to the extraction list +(unless the +.Cm h +key is specified on the command line). +Files that are on the extraction list are prepended with a ``*'' +when they are listed by +.Ic ls . +.It Ic \&cd Ar arg +Change the current working directory to the specified argument. +.It Ic delete Op Ar arg +The current directory or specified argument is deleted from the list of +files to be extracted. +If a directory is specified, then it and all its descendents are +deleted from the extraction list +(unless the +.Cm h +key is specified on the command line). +The most expedient way to extract most of the files from a directory +is to add the directory to the extraction list and then delete +those files that are not needed. +.It Ic extract +All the files that are on the extraction list are extracted +from the dump. +.Nm Restore +will ask which volume the user wishes to mount. +The fastest way to extract a few files is to +start with the last volume, and work towards the first volume. +.It Ic help +List a summary of the available commands. +.It Ic \&ls Op Ar arg +List the current or specified directory. +Entries that are directories are appended with a ``/''. +Entries that have been marked for extraction are prepended with a ``*''. +If the verbose key is set the inode number of each entry is also listed. +.It Ic pwd +Print the full pathname of the current working directory. +.It Ic quit +Restore immediately exits, +even if the extraction list is not empty. +.It Ic setmodes +All the directories that have been added to the extraction list +have their owner, modes, and times set; +nothing is extracted from the dump. +This is useful for cleaning up after a restore has been prematurely aborted. +.It Ic verbose +The sense of the +.Cm v +key is toggled. +When set, the verbose key causes the +.Ic ls +command to list the inode numbers of all entries. +It also causes +.Nm restore +to print out information about each file as it is extracted. +.El +.El +.Pp +The following characters may be used in addition to the letter +that selects the function desired. +.Bl -tag -width Ds +.It Cm b +The next argument to +.Nm restore +is used as the block size of the media (in kilobytes). +If the +.Fl b +option is not specified, +.Nm restore +tries to determine the media block size dynamically. +.It Cm f +The next argument to +.Nm restore +is used as the name of the archive instead +of +.Pa /dev/rmt? . +If the name of the file is of the form +.Dq host:file , +.Nm restore +reads from the named file on the remote host using +.Xr rmt 8 . +If the name of the file is +.Ql Fl , +.Nm restore +reads from standard input. +Thus, +.Xr dump 8 +and +.Nm restore +can be used in a pipeline to dump and restore a file system +with the command +.Bd -literal -offset indent +dump 0f - /usr | (cd /mnt; restore xf -) +.Ed +.Pp +.It Cm h +.Nm Restore +extracts the actual directory, +rather than the files that it references. +This prevents hierarchical restoration of complete subtrees +from the dump. +.It Cm m +.Nm Restore +will extract by inode numbers rather than by file name. +This is useful if only a few files are being extracted, +and one wants to avoid regenerating the complete pathname +to the file. +.It Cm s +The next argument to +.Nm restore +is a number which +selects the file on a multi-file dump tape. File numbering +starts at 1. +.It Cm v +Normally +.Nm restore +does its work silently. +The +.Cm v +(verbose) +key causes it to type the name of each file it treats +preceded by its file type. +.It Cm y +.Nm Restore +will not ask whether it should abort the restore if it gets an error. +It will always try to skip over the bad block(s) and continue as +best it can. +.El +.Sh DIAGNOSTICS +Complaints about bad key characters. +.Pp +Complaints if it gets a read error. +If +.Cm y +has been specified, or the user responds +.Ql y , +.Nm restore +will attempt to continue the restore. +.Pp +If a backup was made using more than one tape volume, +.Nm restore +will notify the user when it is time to mount the next volume. +If the +.Cm x +or +.Cm i +key has been specified, +.Nm restore +will also ask which volume the user wishes to mount. +The fastest way to extract a few files is to +start with the last volume, and work towards the first volume. +.Pp +There are numerous consistency checks that can be listed by +.Nm restore . +Most checks are self-explanatory or can ``never happen''. +Common errors are given below. +.Pp +.Bl -tag -width Ds -compact +.It Converting to new file system format. +A dump tape created from the old file system has been loaded. +It is automatically converted to the new file system format. +.Pp +.It <filename>: not found on tape +The specified file name was listed in the tape directory, +but was not found on the tape. +This is caused by tape read errors while looking for the file, +and from using a dump tape created on an active file system. +.Pp +.It expected next file <inumber>, got <inumber> +A file that was not listed in the directory showed up. +This can occur when using a dump created on an active file system. +.Pp +.It Incremental dump too low +When doing incremental restore, +a dump that was written before the previous incremental dump, +or that has too low an incremental level has been loaded. +.Pp +.It Incremental dump too high +When doing incremental restore, +a dump that does not begin its coverage where the previous incremental +dump left off, +or that has too high an incremental level has been loaded. +.Pp +.It Tape read error while restoring <filename> +.It Tape read error while skipping over inode <inumber> +.It Tape read error while trying to resynchronize +A tape (or other media) read error has occurred. +If a file name is specified, +then its contents are probably partially wrong. +If an inode is being skipped or the tape is trying to resynchronize, +then no extracted files have been corrupted, +though files may not be found on the tape. +.Pp +.It resync restore, skipped <num> blocks +After a dump read error, +.Nm restore +may have to resynchronize itself. +This message lists the number of blocks that were skipped over. +.El +.Sh FILES +.Bl -tag -width "./restoresymtable" -compact +.It Pa /dev/rmt? +the default tape drive +.It Pa /tmp/rstdir* +file containing directories on the tape. +.It Pa /tmp/rstmode* +owner, mode, and time stamps for directories. +.It Pa \&./restoresymtable +information passed between incremental restores. +.El +.Sh SEE ALSO +.Xr dump 8 , +.Xr newfs 8 , +.Xr mount 8 , +.Xr mkfs 8 , +.Xr rmt 8 +.Sh BUGS +.Nm Restore +can get confused when doing incremental restores from +dump that were made on active file systems. +.Pp +A level zero dump must be done after a full restore. +Because restore runs in user code, +it has no control over inode allocation; +thus a full restore must be done to get a new set of directories +reflecting the new inode numbering, +even though the contents of the files is unchanged. +.Sh HISTORY +The +.Nm restore +command appeared in +.Bx 4.2 . |