1.\" Copyright (c) 1985, 1991, 1993 2.\" The Regents of the University of California. 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. Neither the name of the University nor the names of its contributors 13.\" may be used to endorse or promote products derived from this software 14.\" without specific prior written permission. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.\" @(#)restore.8 8.4 (Berkeley) 5/1/95 29.\" 30.Dd October 12, 2006 31.Dt RESTORE 8 32.Os 33.Sh NAME 34.Nm restore , 35.Nm rrestore 36.Nd "restore files or file systems from backups made with dump" 37.Sh SYNOPSIS 38.Nm 39.Fl i 40.Op Fl dDhmNuvy 41.Op Fl b Ar blocksize 42.Op Fl f Ar file | Fl P Ar pipecommand 43.Op Fl s Ar fileno 44.Nm 45.Fl R 46.Op Fl dDNuvy 47.Op Fl b Ar blocksize 48.Op Fl f Ar file | Fl P Ar pipecommand 49.Op Fl s Ar fileno 50.Nm 51.Fl r 52.Op Fl dDNuvy 53.Op Fl b Ar blocksize 54.Op Fl f Ar file | Fl P Ar pipecommand 55.Op Fl s Ar fileno 56.Nm 57.Fl t 58.Op Fl dDhNuvy 59.Op Fl b Ar blocksize 60.Op Fl f Ar file | Fl P Ar pipecommand 61.Op Fl s Ar fileno 62.Op Ar 63.Nm 64.Fl x 65.Op Fl dDhmNuvy 66.Op Fl b Ar blocksize 67.Op Fl f Ar file | Fl P Ar pipecommand 68.Op Fl s Ar fileno 69.Op Ar 70.Sh DESCRIPTION 71The 72.Nm 73utility performs the inverse function of 74.Xr dump 8 . 75A full backup of a file system may be restored and 76subsequent incremental backups layered on top of it. 77Single files and 78directory subtrees may be restored from full or partial 79backups. 80The 81.Nm 82utility works across a network; 83to do this see the 84.Fl f 85and 86.Fl P 87flags described below. 88Other arguments to the command are file or directory 89names specifying the files that are to be restored. 90Unless the 91.Fl h 92flag is specified (see below), 93the appearance of a directory name refers to 94the files and (recursively) subdirectories of that directory. 95.Pp 96.Nm 97may also be invoked as 98.Nm rrestore . 99The 100.Bx 4.3 101option syntax is implemented for backward compatibility, but 102is not documented here. 103.Pp 104Exactly one of the following flags is required: 105.Bl -tag -width Ds 106.It Fl i 107This mode allows interactive restoration of files from a dump. 108After reading in the directory information from the dump, 109.Nm 110provides a shell like interface that allows the user to move 111around the directory tree selecting files to be extracted. 112The available commands are given below; 113for those commands that require an argument, 114the default is the current directory. 115.Bl -tag -width Fl 116.It Ic add Op Ar arg 117The current directory or specified argument is added to the list of 118files to be extracted. 119If a directory is specified, then it and all its descendents are 120added to the extraction list 121(unless the 122.Fl h 123flag is specified on the command line). 124Files that are on the extraction list are prepended with a ``*'' 125when they are listed by 126.Ic ls . 127.It Ic \&cd Ar arg 128Change the current working directory to the specified argument. 129.It Ic delete Op Ar arg 130The current directory or specified argument is deleted from the list of 131files to be extracted. 132If a directory is specified, then it and all its descendents are 133deleted from the extraction list 134(unless the 135.Fl h 136flag is specified on the command line). 137The most expedient way to extract most of the files from a directory 138is to add the directory to the extraction list and then delete 139those files that are not needed. 140.It Ic extract 141All the files that are on the extraction list are extracted 142from the dump. 143The 144.Nm 145utility will ask which volume the user wishes to mount. 146The fastest way to extract a few files is to 147start with the last volume, and work towards the first volume. 148.It Ic help 149List a summary of the available commands. 150.It Ic \&ls Op Ar arg 151List the current or specified directory. 152Entries that are directories are appended with a ``/''. 153Entries that have been marked for extraction are prepended with a ``*''. 154If the verbose 155flag is set the inode number of each entry is also listed. 156.It Ic pwd 157Print the full pathname of the current working directory. 158.It Ic quit 159Exit immediately, 160even if the extraction list is not empty. 161.It Ic setmodes 162All the directories that have been added to the extraction list 163have their owner, modes, and times set; 164nothing is extracted from the dump. 165This is useful for cleaning up after a restore has been prematurely aborted. 166.It Ic verbose 167The sense of the 168.Fl v 169flag is toggled. 170When set, the verbose flag causes the 171.Ic ls 172command to list the inode numbers of all entries. 173It also causes 174.Nm 175to print out information about each file as it is extracted. 176.It Ic what 177Display dump header information, which includes: date, 178level, label, and the file system and host dump was made 179from. 180.El 181.It Fl R 182Request a particular tape of a multi volume set on which to restart 183a full restore 184(see the 185.Fl r 186flag below). 187This is useful if the restore has been interrupted. 188.It Fl r 189Restore (rebuild a file system). 190The target file system should be made pristine with 191.Xr newfs 8 , 192mounted and the user 193.Xr cd 1 Ns 'd 194into the pristine file system 195before starting the restoration of the initial level 0 backup. 196If the 197level 0 restores successfully, the 198.Fl r 199flag may be used to restore 200any necessary incremental backups on top of the level 0. 201The 202.Fl r 203flag precludes an interactive file extraction and can be 204detrimental to one's health if not used carefully (not to mention 205the disk). 206An example: 207.Bd -literal -offset indent 208newfs /dev/da0s1a 209mount /dev/da0s1a /mnt 210cd /mnt 211 212restore rf /dev/sa0 213.Ed 214.Pp 215Note that 216.Nm 217leaves a file 218.Pa restoresymtable 219in the root directory to pass information between incremental 220restore passes. 221This file should be removed when the last incremental has been 222restored. 223.Pp 224The 225.Nm 226utility , 227in conjunction with 228.Xr newfs 8 229and 230.Xr dump 8 , 231may be used to modify file system parameters 232such as size or block size. 233.It Fl t 234The names of the specified files are listed if they occur 235on the backup. 236If no file argument is given, 237then the root directory is listed, 238which results in the entire content of the 239backup being listed, 240unless the 241.Fl h 242flag has been specified. 243Note that the 244.Fl t 245flag replaces the function of the old 246.Xr dumpdir 8 247program. 248.It Fl x 249The named files are read from the given media. 250If a named file matches a directory whose contents 251are on the backup 252and the 253.Fl h 254flag is not specified, 255the directory is recursively extracted. 256The owner, modification time, 257and mode are restored (if possible). 258If no file argument is given, 259then the root directory is extracted, 260which results in the entire content of the 261backup being extracted, 262unless the 263.Fl h 264flag has been specified. 265.El 266.Pp 267The following additional options may be specified: 268.Bl -tag -width Ds 269.It Fl b Ar blocksize 270The number of kilobytes per dump record. 271If the 272.Fl b 273option is not specified, 274.Nm 275tries to determine the media block size dynamically. 276.It Fl d 277Sends verbose debugging output to the standard error. 278.It Fl D 279This puts 280.Nm 281into degraded mode, 282causing restore to operate less efficiently 283but to try harder to read corrupted backups. 284.It Fl f Ar file 285Read the backup from 286.Ar file ; 287.Ar file 288may be a special device file 289like 290.Pa /dev/sa0 291(a tape drive), 292.Pa /dev/da1c 293(a disk drive), 294an ordinary file, 295or 296.Sq Fl 297(the standard input). 298If the name of the file is of the form 299.Dq host:file , 300or 301.Dq user@host:file , 302.Nm 303reads from the named file on the remote host using 304.Xr rmt 8 . 305.It Fl P Ar pipecommand 306Use 307.Xr popen 3 308to execute the 309.Xr sh 1 310script string defined by 311.Ar pipecommand 312as the input for every volume in the backup. 313This child pipeline's 314.Dv stdout 315.Pq Pa /dev/fd/1 316is redirected to the 317.Nm 318input stream, and the environment variable 319.Ev RESTORE_VOLUME 320is set to the current volume number being read. 321The 322.Ar pipecommand 323script is started each time a volume is loaded, as if it were a tape drive. 324.It Fl h 325Extract the actual directory, 326rather than the files that it references. 327This prevents hierarchical restoration of complete subtrees 328from the dump. 329.It Fl m 330Extract by inode numbers rather than by file name. 331This is useful if only a few files are being extracted, 332and one wants to avoid regenerating the complete pathname 333to the file. 334.It Fl N 335Do the extraction normally, but do not actually write any changes 336to disk. 337This can be used to check the integrity of dump media 338or other test purposes. 339.It Fl s Ar fileno 340Read from the specified 341.Ar fileno 342on a multi-file tape. 343File numbering starts at 1. 344.It Fl u 345When creating certain types of files, restore may generate a warning 346diagnostic if they already exist in the target directory. 347To prevent this, the 348.Fl u 349(unlink) flag causes restore to remove old entries before attempting 350to create new ones. 351This flag is recommended when using extended attributes 352to avoid improperly accumulating attributes on pre-existing files. 353.It Fl v 354Normally 355.Nm 356does its work silently. 357The 358.Fl v 359(verbose) 360flag causes it to type the name of each file it treats 361preceded by its file type. 362.It Fl y 363Do not ask the user whether to abort the restore in the event of an error. 364Always try to skip over the bad block(s) and continue. 365.El 366.Sh ENVIRONMENT 367.Bl -tag -width ".Ev TMPDIR" 368.It Ev TAPE 369Device from which to read backup. 370.It Ev TMPDIR 371Name of directory where temporary files are to be created. 372.El 373.Sh FILES 374.Bl -tag -width "./restoresymtable" -compact 375.It Pa /dev/sa0 376the default tape drive 377.It Pa /tmp/rstdir* 378file containing directories on the tape. 379.It Pa /tmp/rstmode* 380owner, mode, and time stamps for directories. 381.It Pa \&./restoresymtable 382information passed between incremental restores. 383.El 384.Sh DIAGNOSTICS 385The 386.Nm 387utility complains if it gets a read error. 388If 389.Fl y 390has been specified, or the user responds 391.Ql y , 392.Nm 393will attempt to continue the restore. 394.Pp 395If a backup was made using more than one tape volume, 396.Nm 397will notify the user when it is time to mount the next volume. 398If the 399.Fl x 400or 401.Fl i 402flag has been specified, 403.Nm 404will also ask which volume the user wishes to mount. 405The fastest way to extract a few files is to 406start with the last volume, and work towards the first volume. 407.Pp 408There are numerous consistency checks that can be listed by 409.Nm . 410Most checks are self-explanatory or can ``never happen''. 411Common errors are given below. 412.Pp 413.Bl -tag -width Ds -compact 414.It <filename>: not found on tape 415The specified file name was listed in the tape directory, 416but was not found on the tape. 417This is caused by tape read errors while looking for the file, 418and from using a dump tape created on an active file system. 419.Pp 420.It expected next file <inumber>, got <inumber> 421A file that was not listed in the directory showed up. 422This can occur when using a dump created on an active file system. 423.Pp 424.It Incremental dump too low 425When doing incremental restore, 426a dump that was written before the previous incremental dump, 427or that has too low an incremental level has been loaded. 428.Pp 429.It Incremental dump too high 430When doing incremental restore, 431a dump that does not begin its coverage where the previous incremental 432dump left off, 433or that has too high an incremental level has been loaded. 434.Pp 435.It Tape read error while restoring <filename> 436.It Tape read error while skipping over inode <inumber> 437.It Tape read error while trying to resynchronize 438A tape (or other media) read error has occurred. 439If a file name is specified, 440then its contents are probably partially wrong. 441If an inode is being skipped or the tape is trying to resynchronize, 442then no extracted files have been corrupted, 443though files may not be found on the tape. 444.Pp 445.It resync restore, skipped <num> blocks 446After a dump read error, 447.Nm 448may have to resynchronize itself. 449This message lists the number of blocks that were skipped over. 450.El 451.Sh SEE ALSO 452.Xr dump 8 , 453.Xr mount 8 , 454.Xr newfs 8 , 455.Xr rmt 8 456.Sh HISTORY 457The 458.Nm 459utility appeared in 460.Bx 4.2 . 461.Sh BUGS 462The 463.Nm 464utility can get confused when doing incremental restores from 465dumps that were made on active file systems without the 466.Fl L 467option (see 468.Xr dump 8 ) . 469.Pp 470A level zero dump must be done after a full restore. 471Because restore runs in user code, 472it has no control over inode allocation; 473thus a full dump must be done to get a new set of directories 474reflecting the new inode numbering, 475even though the contents of the files is unchanged. 476.Pp 477To do a network restore, you have to run restore as root. 478This is due 479to the previous security history of dump and restore. 480(restore is 481written to be setuid root, but we are not certain all bugs are gone 482from the restore code - run setuid at your own risk.) 483.Pp 484The temporary files 485.Pa /tmp/rstdir* 486and 487.Pa /tmp/rstmode* 488are generated with a unique name based on the date of the dump 489and the process ID (see 490.Xr mktemp 3 ) , 491except for when 492.Fl r 493or 494.Fl R 495is used. 496Because 497.Fl R 498allows you to restart a 499.Fl r 500operation that may have been interrupted, the temporary files should 501be the same across different processes. 502In all other cases, the files are unique because it is possible to 503have two different dumps started at the same time, and separate 504operations should not conflict with each other. 505