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