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