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