1.\" $NetBSD: restore.8,v 1.35 2002/02/08 01:30:46 ross 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. All advertising materials mentioning features or use of this software 15.\" must display the following acknowledgement: 16.\" This product includes software developed by the University of 17.\" California, Berkeley and its contributors. 18.\" 4. Neither the name of the University nor the names of its contributors 19.\" may be used to endorse or promote products derived from this software 20.\" without specific prior written permission. 21.\" 22.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 25.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 32.\" SUCH DAMAGE. 33.\" 34.\" @(#)restore.8 8.4 (Berkeley) 5/1/95 35.\" 36.Dd July 1, 1997 37.Dt RESTORE 8 38.Os 39.Sh NAME 40.Nm restore , 41.Nm rrestore 42.Nd "restore files or file systems from backups made with dump" 43.Sh SYNOPSIS 44.Nm 45.Fl i 46.Op Fl cdhmuvyN 47.Op Fl b Ar blocksize 48.Op Fl f Ar file 49.Op Fl s Ar fileno 50.Nm "" 51.Fl R 52.Op Fl cduvyN 53.Op Fl b Ar blocksize 54.Op Fl f Ar file 55.Op Fl s Ar fileno 56.Nm "" 57.Fl r 58.Op Fl cduvyN 59.Op Fl b Ar blocksize 60.Op Fl f Ar file 61.Op Fl s Ar fileno 62.Nm "" 63.Fl t 64.Op Fl cdhuvy 65.Op Fl b Ar blocksize 66.Op Fl f Ar file 67.Op Fl s Ar fileno 68.Op Ar 69.Nm "" 70.Fl x 71.Op Fl cdhmuvyN 72.Op Fl b Ar blocksize 73.Op Fl f Ar file 74.Op Fl s Ar fileno 75.Op Ar 76.Pp 77.in -\n(iSu 78(The 79.Bx 4.3 80option syntax is implemented for backward compatibility, but 81is not documented here.) 82.Sh DESCRIPTION 83The 84.Nm 85command performs the inverse function of 86.Xr dump 8 . 87A full backup of a file system may be restored and 88subsequent incremental backups layered on top of it. 89Single files and 90directory subtrees may be restored from full or partial 91backups. 92.Nm 93works across a network; 94to do this see the 95.Fl f 96flag described below. 97Other arguments to the command are file or directory 98names specifying the files that are to be restored. 99Unless the 100.Fl h 101flag is specified (see below), 102the appearance of a directory name refers to 103the files and (recursively) subdirectories of that directory. 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. 144.Nm 145will ask which volume the user wishes to mount. 146The fastest way to extract a few files is to 147start with the last volume, and work towards the first volume. 148.It Ic help , ? 149List a summary of the available commands. 150.It Ic \&ls Op Ar arg 151List the current or specified directory. 152Entries that are directories are appended with a ``/''. 153Entries that have been marked for extraction are prepended with a ``*''. 154If the verbose 155flag is set the inode number of each entry is also listed. 156.It Ic pwd 157Print the full pathname of the current working directory. 158.It Ic quit , Ic xit 159Restore immediately exits, 160even if the extraction list is not empty. 161.It Ic setmodes 162All the directories that have been added to the extraction list 163have their owner, modes, and times set; 164nothing is extracted from the dump. 165This is useful for cleaning up after a restore has been prematurely aborted. 166.It Ic verbose 167The sense of the 168.Fl v 169flag is toggled. 170When set, the verbose flag causes the 171.Ic ls 172command to list the inode numbers of all entries. 173It also causes 174.Nm 175to print out information about each file as it is extracted. 176.It Ic what 177List dump header information. 178.It Ic Debug 179Enable debugging. 180.El 181.It Fl R 182.Nm 183requests 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 level 0 restores successfully, the 198.Fl r 199flag may be used to restore 200any necessary incremental backups on top of the level 0. 201The 202.Fl r 203flag precludes an interactive file extraction and can be 204detrimental to one's health if not used carefully (not to mention 205the disk). 206An example: 207.Bd -literal -offset indent 208newfs /dev/rrp0g eagle 209mount /dev/rp0g /mnt 210cd /mnt 211 212restore rf /dev/rst8 213.Ed 214.Pp 215Note that 216.Nm 217leaves a file 218.Pa restoresymtable 219in the root directory to pass information between incremental 220restore passes. 221This file should be removed when the last incremental has been 222restored. 223.Pp 224.Nm "" , 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.Ic dumpdir 245program. 246.ne 1i 247.It Fl x 248The named files are read from the given media. 249If a named file matches a directory whose contents 250are on the backup 251and the 252.Fl h 253flag is not specified, 254the directory is recursively extracted. 255The owner, modification time, 256and mode are restored (if possible). 257If no file argument is given, 258then the root directory is extracted, 259which results in the entire content of the 260backup being extracted, 261unless the 262.Fl h 263flag has been specified. 264.El 265.Pp 266The following additional options may be specified: 267.Bl -tag -width Ds 268.It Fl b Ar blocksize 269The number of kilobytes per dump record. 270If the 271.Fl b 272option is not specified, 273.Nm 274tries to determine the block size dynamically. 275.It Fl c 276Normally, 277.Nm 278will try to determine dynamically whether the dump was made from an 279old (pre-4.4) or new format file sytem. 280The 281.Fl c 282flag disables this check, and only allows reading a dump in the old 283format. 284.It Fl d 285Enable debugging. 286.It Fl f Ar file 287Read the backup from 288.Ar file ; 289.Ar file 290may be a special device file 291like 292.Pa /dev/rst0 293(a tape drive), 294.Pa /dev/rsd1c 295(a disk drive), 296an ordinary file, 297or 298.Ql Fl 299(the standard input). 300If the name of the file is of the form 301.Dq host:file , 302or 303.Dq user@host:file , 304.Nm 305reads from the named file on the remote host using 306.Xr rmt 8 . 307If the name of the file is 308.Ql Fl , 309.Nm 310reads from standard input. 311Thus, 312.Xr dump 8 313and 314.Nm 315can be used in a pipeline to dump and restore a file system 316with the command 317.Bd -literal -offset indent 318dump 0f - /usr | (cd /mnt; restore xf -) 319.Ed 320.Pp 321.It Fl h 322Extract the actual directory, 323rather than the files that it references. 324This prevents hierarchical restoration of complete subtrees 325from the dump. 326.It Fl m 327Extract by inode numbers rather than by file name. 328This is useful if only a few files are being extracted, 329and one wants to avoid regenerating the complete pathname 330to the file. 331.It Fl s Ar fileno 332Read from the specified 333.Ar fileno 334on a multi-file tape. 335File numbering starts at 1. 336.It Fl u 337The 338.Fl u 339(unlink) 340flag removes files before extracting them. 341This is useful when an executable file is in use. 342Ignored if 343.Fl t 344or 345.Fl N 346flag is given. 347.It Fl v 348Normally 349.Nm 350does its work silently. 351The 352.Fl v 353(verbose) 354flag causes it to type the name of each file it treats 355preceded by its file type. 356.It Fl y 357Do not ask the user whether to abort the restore in the event of an error. 358Always try to skip over the bad block(s) and continue. 359.It Fl N 360Do not perform actual writing to disk. 361.El 362.Sh ENVIRONMENT 363If the following environment variable exists it will be utilized by 364.Nm "" : 365.Bl -tag -width "TMPDIR" -compact 366.It TMPDIR 367The directory given in TMPDIR will be used 368instead of 369.Pa /tmp 370to store temporary files. 371Refer to 372.Xr environ 7 373for more information. 374.El 375.Sh FILES 376.Bl -tag -width "./restoresymtable" -compact 377.It Pa /dev/nrst0 378default tape unit to use. 379Taken from 380.Dv _PATH_DEFTAPE 381in 382.Pa /usr/include/paths.h . 383.It Pa /dev/rst* 384raw SCSI tape interface 385.It Pa /tmp/rstdir* 386file containing directories on the tape. 387.It Pa /tmp/rstmode* 388owner, mode, and time stamps for directories. 389.It Pa \&./restoresymtable 390information passed between incremental restores. 391.El 392.Sh DIAGNOSTICS 393Complains if it gets a read error. 394If 395.Fl y 396has been specified, or the user responds 397.Ql y , 398.Nm 399will attempt to continue the restore. 400.Pp 401If a backup was made using more than one tape volume, 402.Nm 403will notify the user when it is time to mount the next volume. 404If the 405.Fl x 406or 407.Fl i 408flag has been specified, 409.Nm 410will also ask which volume the user wishes to mount. 411The fastest way to extract a few files is to 412start with the last volume, and work towards the first volume. 413.Pp 414There are numerous consistency checks that can be listed by 415.Nm "" . 416Most checks are self-explanatory or can ``never happen''. 417Common errors are given below. 418.Pp 419.Bl -tag -width Ds -compact 420.It Converting to new file system format. 421A dump tape created from the old file system has been loaded. 422It is automatically converted to the new file system format. 423.Pp 424.It \*[Lt]filename\*[Gt]: not found on tape 425The specified file name was listed in the tape directory, 426but was not found on the tape. 427This is caused by tape read errors while looking for the file, 428and from using a dump tape created on an active file system. 429.Pp 430.It expected next file \*[Lt]inumber\*[Gt], got \*[Lt]inumber\*[Gt] 431A file that was not listed in the directory showed up. 432This can occur when using a dump created on an active file system. 433.Pp 434.It Incremental dump too low 435When doing incremental restore, 436a dump that was written before the previous incremental dump, 437or that has too low an incremental level has been loaded. 438.Pp 439.It Incremental dump too high 440When doing incremental restore, 441a dump that does not begin its coverage where the previous incremental 442dump left off, 443or that has too high an incremental level has been loaded. 444.Pp 445.It Tape read error while restoring \*[Lt]filename\*[Gt] 446.It Tape read error while skipping over inode \*[Lt]inumber\*[Gt] 447.It Tape read error while trying to resynchronize 448A tape (or other media) read error has occurred. 449If a file name is specified, 450then its contents are probably partially wrong. 451If an inode is being skipped or the tape is trying to resynchronize, 452then no extracted files have been corrupted, 453though files may not be found on the tape. 454.Pp 455.It resync restore, skipped \*[Lt]num\*[Gt] blocks 456After a dump read error, 457.Nm 458may have to resynchronize itself. 459This message lists the number of blocks that were skipped over. 460.El 461.Sh SEE ALSO 462.Xr environ 7 , 463.Xr dump 8 , 464.Xr mount 8 , 465.Xr newfs 8 , 466.Xr rmt 8 467.Sh HISTORY 468The 469.Nm 470command appeared in 471.Bx 4.2 . 472.Sh BUGS 473.Nm 474can get confused when doing incremental restores from 475dumps that were made on active file systems. 476.Pp 477A level zero dump must be done after a full restore. 478Because 479.Nm 480runs in user code, 481it has no control over inode allocation; 482thus a full dump must be done to get a new set of directories 483reflecting the new inode numbering, 484even though the content of the files is unchanged. 485.Pp 486The temporary files 487.Pa /tmp/rstdir* 488and 489.Pa /tmp/rstmode* 490are generated with a unique name based on the date of the dump 491and the process ID (see 492.Xr mktemp 3 ) , 493except for when 494.Fl r 495or 496.Fl R 497is used. 498Because 499.Fl R 500allows you to restart a 501.Fl r 502operation that may have been interrupted, the temporary files should 503be the same across different processes. 504In all other cases, the files are unique because it is possible to 505have two different dumps started at the same time, and separate 506operations shouldn't conflict with each other. 507