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