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