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.1 (Berkeley) 06/05/93 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 ones 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.It Cm i 136This mode allows interactive restoration of files from a dump. 137After reading in the directory information from the dump, 138.Nm restore 139provides a shell like interface that allows the user to move 140around the directory tree selecting files to be extracted. 141The available commands are given below; 142for those commands that require an argument, 143the default is the current directory. 144.Bl -tag -width Fl 145.It Ic add Op Ar arg 146The current directory or specified argument is added to the list of 147files to be extracted. 148If a directory is specified, then it and all its descendents are 149added to the extraction list 150(unless the 151.Cm h 152key is specified on the command line). 153Files that are on the extraction list are prepended with a ``*'' 154when they are listed by 155.Ic ls . 156.It Ic \&cd Ar arg 157Change the current working directory to the specified argument. 158.It Ic delete Op Ar arg 159The current directory or specified argument is deleted from the list of 160files to be extracted. 161If a directory is specified, then it and all its descendents are 162deleted from the extraction list 163(unless the 164.Cm h 165key is specified on the command line). 166The most expedient way to extract most of the files from a directory 167is to add the directory to the extraction list and then delete 168those files that are not needed. 169.It Ic extract 170All the files that are on the extraction list are extracted 171from the dump. 172.Nm Restore 173will ask which volume the user wishes to mount. 174The fastest way to extract a few files is to 175start with the last volume, and work towards the first volume. 176.It Ic help 177List a summary of the available commands. 178.It Ic \&ls Op Ar arg 179List the current or specified directory. 180Entries that are directories are appended with a ``/''. 181Entries that have been marked for extraction are prepended with a ``*''. 182If the verbose key is set the inode number of each entry is also listed. 183.It Ic pwd 184Print the full pathname of the current working directory. 185.It Ic quit 186Restore immediately exits, 187even if the extraction list is not empty. 188.It Ic setmodes 189All the directories that have been added to the extraction list 190have their owner, modes, and times set; 191nothing is extracted from the dump. 192This is useful for cleaning up after a restore has been prematurely aborted. 193.It Ic verbose 194The sense of the 195.Cm v 196key is toggled. 197When set, the verbose key causes the 198.Ic ls 199command to list the inode numbers of all entries. 200It also causes 201.Nm restore 202to print out information about each file as it is extracted. 203.El 204.El 205.Pp 206The following characters may be used in addition to the letter 207that selects the function desired. 208.Bl -tag -width Ds 209.It Cm b 210The next argument to 211.Nm restore 212is used as the block size of the media (in kilobytes). 213If the 214.Fl b 215option is not specified, 216.Nm restore 217tries to determine the media block size dynamically. 218.It Cm f 219The next argument to 220.Nm restore 221is used as the name of the archive instead 222of 223.Pa /dev/rmt? . 224If the name of the file is of the form 225.Dq host:file , 226.Nm restore 227reads from the named file on the remote host using 228.Xr rmt 8 . 229If the name of the file is 230.Ql Fl , 231.Nm restore 232reads from standard input. 233Thus, 234.Xr dump 8 235and 236.Nm restore 237can be used in a pipeline to dump and restore a file system 238with the command 239.Bd -literal -offset indent 240dump 0f - /usr | (cd /mnt; restore xf -) 241.Ed 242.Pp 243.It Cm h 244.Nm Restore 245extracts the actual directory, 246rather than the files that it references. 247This prevents hierarchical restoration of complete subtrees 248from the dump. 249.It Cm m 250.Nm Restore 251will extract by inode numbers rather than by file name. 252This is useful if only a few files are being extracted, 253and one wants to avoid regenerating the complete pathname 254to the file. 255.It Cm s 256The next argument to 257.Nm restore 258is a number which 259selects the file on a multi-file dump tape. File numbering 260starts at 1. 261.It Cm v 262Normally 263.Nm restore 264does its work silently. 265The 266.Cm v 267(verbose) 268key causes it to type the name of each file it treats 269preceded by its file type. 270.It Cm y 271.Nm Restore 272will not ask whether it should abort the restore if gets an error. 273It will always try to skip over the bad block(s) and continue as 274best it can. 275.El 276.Sh DIAGNOSTICS 277Complaints about bad key characters. 278.Pp 279Complaints if it gets a read error. 280If 281.Cm y 282has been specified, or the user responds 283.Ql y , 284.Nm restore 285will attempt to continue the restore. 286.Pp 287If a backup was made using more than one tape volume, 288.Nm restore 289will notify the user when it is time to mount the next volume. 290If the 291.Cm x 292or 293.Cm i 294key has been specified, 295.Nm restore 296will also ask which volume the user wishes to mount. 297The fastest way to extract a few files is to 298start with the last volume, and work towards the first volume. 299.Pp 300There are numerous consistency checks that can be listed by 301.Nm restore . 302Most checks are self-explanatory or can ``never happen''. 303Common errors are given below. 304.Pp 305.Bl -tag -width Ds -compact 306.It Converting to new file system format. 307A dump tape created from the old file system has been loaded. 308It is automatically converted to the new file system format. 309.Pp 310.It <filename>: not found on tape 311The specified file name was listed in the tape directory, 312but was not found on the tape. 313This is caused by tape read errors while looking for the file, 314and from using a dump tape created on an active file system. 315.Pp 316.It expected next file <inumber>, got <inumber> 317A file that was not listed in the directory showed up. 318This can occur when using a dump created on an active file system. 319.Pp 320.It Incremental dump too low 321When doing incremental restore, 322a dump that was written before the previous incremental dump, 323or that has too low an incremental level has been loaded. 324.Pp 325.It Incremental dump too high 326When doing incremental restore, 327a dump that does not begin its coverage where the previous incremental 328dump left off, 329or that has too high an incremental level has been loaded. 330.Pp 331.It Tape read error while restoring <filename> 332.It Tape read error while skipping over inode <inumber> 333.It Tape read error while trying to resynchronize 334A tape (or other media) read error has occurred. 335If a file name is specified, 336then its contents are probably partially wrong. 337If an inode is being skipped or the tape is trying to resynchronize, 338then no extracted files have been corrupted, 339though files may not be found on the tape. 340.Pp 341.It resync restore, skipped <num> blocks 342After a dump read error, 343.Nm restore 344may have to resynchronize itself. 345This message lists the number of blocks that were skipped over. 346.El 347.Sh FILES 348.Bl -tag -width "./restoresymtable" -compact 349.It Pa /dev/rmt? 350the default tape drive 351.It Pa /tmp/rstdir* 352file containing directories on the tape. 353.It Pa /tmp/rstmode* 354owner, mode, and time stamps for directories. 355.It Pa \&./restoresymtable 356information passed between incremental restores. 357.El 358.Sh SEE ALSO 359.Xr dump 8 , 360.Xr newfs 8 , 361.Xr mount 8 , 362.Xr mkfs 8 , 363.Xr rmt 8 364.Sh BUGS 365.Nm Restore 366can get confused when doing incremental restores from 367dump that were made on active file systems. 368.Pp 369A level zero dump must be done after a full restore. 370Because restore runs in user code, 371it has no control over inode allocation; 372thus a full restore must be done to get a new set of directories 373reflecting the new inode numbering, 374even though the contents of the files is unchanged. 375.Sh HISTORY 376The 377.Nm restore 378command appeared in 379.Bx 4.2 . 380