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