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