1.\" Copyright (c) 1985, 1991, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 3. All advertising materials mentioning features or use of this software 13.\" must display the following acknowledgement: 14.\" This product includes software developed by the University of 15.\" California, Berkeley and its contributors. 16.\" 4. Neither the name of the University nor the names of its contributors 17.\" may be used to endorse or promote products derived from this software 18.\" without specific prior written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" SUCH DAMAGE. 31.\" 32.\" @(#)restore.8 8.2 (Berkeley) 12/11/93 33.\" 34.Dd December 11, 1993 35.Dt RESTORE 8 36.Os BSD 4 37.Sh NAME 38.Nm restore 39.Nd "restore files or file systems from backups made with dump" 40.Sh SYNOPSIS 41.Nm restore 42.Ar key 43.Op Ar name Ar ... 44.Sh DESCRIPTION 45The 46.Nm restore 47command performs the inverse function of 48.Xr dump 8 . 49A full backup of a file system may be restored and 50subsequent incremental backups layered on top of it. 51Single files and 52directory subtrees may be restored from full or partial 53backups. 54.Nm Restore 55works across a network; 56to do this see the 57.Fl f 58flag described below. 59The actions 60of 61.Nm restore 62are controlled by the given 63.Cm key , 64which 65is a string of characters containing 66at most one function letter and possibly 67one or more function modifiers. 68Other arguments to the command are file or directory 69names specifying the files that are to be restored. 70Unless the 71.Cm h 72key is specified (see below), 73the appearance of a directory name refers to 74the files and (recursively) subdirectories of that directory. 75.Pp 76The function portion of 77the key is specified by one of the following letters: 78.Bl -tag -width Ds 79.It Cm r 80Restore (rebuild a file system). 81The target file system should be made pristine with 82.Xr newfs 8 , 83mounted and the 84user 85.Xr cd Ns 'd 86into the pristine file system 87before starting the restoration of the initial level 0 backup. If the 88level 0 restores successfully, the 89.Cm r 90key may be used to restore 91any necessary incremental backups on top of the level 0. 92The 93.Cm r 94key precludes an interactive file extraction and can be 95detrimental to one's health if not used carefully (not to mention 96the disk). An example: 97.Bd -literal -offset indent 98newfs /dev/rrp0g eagle 99mount /dev/rp0g /mnt 100cd /mnt 101 102restore rf /dev/rst8 103.Ed 104.Pp 105Note that 106.Nm restore 107leaves a file 108.Pa restoresymtable 109in the root directory to pass information between incremental 110restore passes. 111This file should be removed when the last incremental has been 112restored. 113.Pp 114.Nm Restore , 115in conjunction with 116.Xr newfs 8 117and 118.Xr dump 8 , 119may be used to modify file system parameters 120such as size or block size. 121.It Cm R 122.Nm Restore 123requests a particular tape of a multi volume set on which to restart 124a full restore 125(see the 126.Cm r 127key above). 128This is useful if the restore has been interrupted. 129.It Cm x 130The named files are read from the given media. 131If a named file matches a directory whose contents 132are on the backup 133and the 134.Cm h 135key is not specified, 136the directory is recursively extracted. 137The owner, modification time, 138and mode are restored (if possible). 139If no file argument is given, 140then the root directory is extracted, 141which results in the entire content of the 142backup being extracted, 143unless the 144.Cm h 145key has been specified. 146.It Cm t 147The names of the specified files are listed if they occur 148on the backup. 149If no file argument is given, 150then the root directory is listed, 151which results in the entire content of the 152backup being listed, 153unless the 154.Cm h 155key has been specified. 156Note that the 157.Cm t 158key replaces the function of the old 159.Xr dumpdir 8 160program. 161.It Cm i 162This mode allows interactive restoration of files from a dump. 163After reading in the directory information from the dump, 164.Nm restore 165provides a shell like interface that allows the user to move 166around the directory tree selecting files to be extracted. 167The available commands are given below; 168for those commands that require an argument, 169the default is the current directory. 170.Bl -tag -width Fl 171.It Ic add Op Ar arg 172The current directory or specified argument is added to the list of 173files to be extracted. 174If a directory is specified, then it and all its descendents are 175added to the extraction list 176(unless the 177.Cm h 178key is specified on the command line). 179Files that are on the extraction list are prepended with a ``*'' 180when they are listed by 181.Ic ls . 182.It Ic \&cd Ar arg 183Change the current working directory to the specified argument. 184.It Ic delete Op Ar arg 185The current directory or specified argument is deleted from the list of 186files to be extracted. 187If a directory is specified, then it and all its descendents are 188deleted from the extraction list 189(unless the 190.Cm h 191key is specified on the command line). 192The most expedient way to extract most of the files from a directory 193is to add the directory to the extraction list and then delete 194those files that are not needed. 195.It Ic extract 196All the files that are on the extraction list are extracted 197from the dump. 198.Nm Restore 199will ask which volume the user wishes to mount. 200The fastest way to extract a few files is to 201start with the last volume, and work towards the first volume. 202.It Ic help 203List a summary of the available commands. 204.It Ic \&ls Op Ar arg 205List the current or specified directory. 206Entries that are directories are appended with a ``/''. 207Entries that have been marked for extraction are prepended with a ``*''. 208If the verbose key is set the inode number of each entry is also listed. 209.It Ic pwd 210Print the full pathname of the current working directory. 211.It Ic quit 212Restore immediately exits, 213even if the extraction list is not empty. 214.It Ic setmodes 215All the directories that have been added to the extraction list 216have their owner, modes, and times set; 217nothing is extracted from the dump. 218This is useful for cleaning up after a restore has been prematurely aborted. 219.It Ic verbose 220The sense of the 221.Cm v 222key is toggled. 223When set, the verbose key causes the 224.Ic ls 225command to list the inode numbers of all entries. 226It also causes 227.Nm restore 228to print out information about each file as it is extracted. 229.El 230.El 231.Pp 232The following characters may be used in addition to the letter 233that selects the function desired. 234.Bl -tag -width Ds 235.It Cm b 236The next argument to 237.Nm restore 238is used as the block size of the media (in kilobytes). 239If the 240.Fl b 241option is not specified, 242.Nm restore 243tries to determine the media block size dynamically. 244.It Cm f 245The next argument to 246.Nm restore 247is used as the name of the archive instead 248of 249.Pa /dev/rmt? . 250If the name of the file is of the form 251.Dq host:file , 252.Nm restore 253reads from the named file on the remote host using 254.Xr rmt 8 . 255If the name of the file is 256.Ql Fl , 257.Nm restore 258reads from standard input. 259Thus, 260.Xr dump 8 261and 262.Nm restore 263can be used in a pipeline to dump and restore a file system 264with the command 265.Bd -literal -offset indent 266dump 0f - /usr | (cd /mnt; restore xf -) 267.Ed 268.Pp 269.It Cm h 270.Nm Restore 271extracts the actual directory, 272rather than the files that it references. 273This prevents hierarchical restoration of complete subtrees 274from the dump. 275.It Cm m 276.Nm Restore 277will extract by inode numbers rather than by file name. 278This is useful if only a few files are being extracted, 279and one wants to avoid regenerating the complete pathname 280to the file. 281.It Cm s 282The next argument to 283.Nm restore 284is a number which 285selects the file on a multi-file dump tape. File numbering 286starts at 1. 287.It Cm v 288Normally 289.Nm restore 290does its work silently. 291The 292.Cm v 293(verbose) 294key causes it to type the name of each file it treats 295preceded by its file type. 296.It Cm y 297.Nm Restore 298will not ask whether it should abort the restore if it gets an error. 299It will always try to skip over the bad block(s) and continue as 300best it can. 301.El 302.Sh DIAGNOSTICS 303Complaints about bad key characters. 304.Pp 305Complaints if it gets a read error. 306If 307.Cm y 308has been specified, or the user responds 309.Ql y , 310.Nm restore 311will attempt to continue the restore. 312.Pp 313If a backup was made using more than one tape volume, 314.Nm restore 315will notify the user when it is time to mount the next volume. 316If the 317.Cm x 318or 319.Cm i 320key has been specified, 321.Nm restore 322will also ask which volume the user wishes to mount. 323The fastest way to extract a few files is to 324start with the last volume, and work towards the first volume. 325.Pp 326There are numerous consistency checks that can be listed by 327.Nm restore . 328Most checks are self-explanatory or can ``never happen''. 329Common errors are given below. 330.Pp 331.Bl -tag -width Ds -compact 332.It Converting to new file system format. 333A dump tape created from the old file system has been loaded. 334It is automatically converted to the new file system format. 335.Pp 336.It <filename>: not found on tape 337The specified file name was listed in the tape directory, 338but was not found on the tape. 339This is caused by tape read errors while looking for the file, 340and from using a dump tape created on an active file system. 341.Pp 342.It expected next file <inumber>, got <inumber> 343A file that was not listed in the directory showed up. 344This can occur when using a dump created on an active file system. 345.Pp 346.It Incremental dump too low 347When doing incremental restore, 348a dump that was written before the previous incremental dump, 349or that has too low an incremental level has been loaded. 350.Pp 351.It Incremental dump too high 352When doing incremental restore, 353a dump that does not begin its coverage where the previous incremental 354dump left off, 355or that has too high an incremental level has been loaded. 356.Pp 357.It Tape read error while restoring <filename> 358.It Tape read error while skipping over inode <inumber> 359.It Tape read error while trying to resynchronize 360A tape (or other media) read error has occurred. 361If a file name is specified, 362then its contents are probably partially wrong. 363If an inode is being skipped or the tape is trying to resynchronize, 364then no extracted files have been corrupted, 365though files may not be found on the tape. 366.Pp 367.It resync restore, skipped <num> blocks 368After a dump read error, 369.Nm restore 370may have to resynchronize itself. 371This message lists the number of blocks that were skipped over. 372.El 373.Sh FILES 374.Bl -tag -width "./restoresymtable" -compact 375.It Pa /dev/rmt? 376the default tape drive 377.It Pa /tmp/rstdir* 378file containing directories on the tape. 379.It Pa /tmp/rstmode* 380owner, mode, and time stamps for directories. 381.It Pa \&./restoresymtable 382information passed between incremental restores. 383.El 384.Sh SEE ALSO 385.Xr dump 8 , 386.Xr newfs 8 , 387.Xr mount 8 , 388.Xr mkfs 8 , 389.Xr rmt 8 390.Sh BUGS 391.Nm Restore 392can get confused when doing incremental restores from 393dump that were made on active file systems. 394.Pp 395A level zero dump must be done after a full restore. 396Because restore runs in user code, 397it has no control over inode allocation; 398thus a full restore must be done to get a new set of directories 399reflecting the new inode numbering, 400even though the contents of the files is unchanged. 401.Sh HISTORY 402The 403.Nm restore 404command appeared in 405.Bx 4.2 . 406