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