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