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