1.\" $NetBSD: restore.8,v 1.56 2018/07/18 17:57:00 wiz 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 July 15, 2018 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.It Fl h 358Extract the actual directory, 359rather than the files that it references. 360This prevents hierarchical restoration of complete subtrees 361from the dump. 362.It Fl M Ar mfile 363Do not set the file flags on restore. 364Instead, append an 365.Xr mtree 8 366specification to 367.Ar mfile , 368which can be used to restore file flags with a command such as 369.Bd -literal -offset indent 370sort mfile | mtree -e -i -u 371.Ed 372.It Fl m 373Extract by inode numbers rather than by file name. 374This is useful if only a few files are being extracted, 375and one wants to avoid regenerating the complete pathname 376to the file. 377.It Fl N 378Do not perform actual writing to disk. 379.It Fl s Ar fileno 380Read from the specified 381.Ar fileno 382on a multi-file tape. 383File numbering starts at 1. 384.It Fl u 385The 386.Fl u 387(unlink) 388flag removes files before extracting them. 389This is useful when an executable file is in use. 390Ignored if 391.Fl t 392or 393.Fl N 394flag is given. 395.It Fl v 396Normally 397.Nm 398does its work silently. 399The 400.Fl v 401(verbose) 402flag causes it to type the name of each file it treats 403preceded by its file type. 404.It Fl y 405Do not ask the user whether to abort the restore in the event of an error. 406Always try to skip over the bad block(s) and continue. 407.El 408.Pp 409The historic alternate name 410.Nm rrestore 411was once required when restoring from a remote host. 412This functionality is now built into 413.Nm 414itself. 415.Sh ENVIRONMENT 416If the following environment variable exists it will be used by 417.Nm : 418.Bl -tag -width "TMPDIR" -compact 419.It TMPDIR 420The directory given in TMPDIR will be used 421instead of 422.Pa /tmp 423to store temporary files. 424Refer to 425.Xr environ 7 426for more information. 427.El 428.Sh FILES 429.Bl -tag -width "./restoresymtable" -compact 430.It Pa /dev/nrst0 431default tape unit to use. 432Taken from 433.Dv _PATH_DEFTAPE 434in 435.Pa /usr/include/paths.h . 436.It Pa /dev/rst* 437raw SCSI tape interface 438.It Pa /tmp/rstdir* 439file containing directories on the tape. 440.It Pa /tmp/rstmode* 441owner, mode, and time stamps for directories. 442.It Pa \&./restoresymtable 443information passed between incremental restores. 444.El 445.Sh DIAGNOSTICS 446Complains if it gets a read error. 447If 448.Fl y 449has been specified, or the user responds 450.Ql y , 451.Nm 452will attempt to continue the restore. 453.Pp 454If a backup was made using more than one tape volume, 455.Nm 456will notify the user when it is time to mount the next volume. 457If the 458.Fl x 459or 460.Fl i 461flag has been specified, 462.Nm 463will also ask which volume the user wishes to mount. 464The fastest way to extract a few files is to 465start with the last volume, and work towards the first volume. 466.Pp 467There are numerous consistency checks that can be listed by 468.Nm . 469Most checks are self-explanatory or can 470.Dq never happen . 471Common errors are given below. 472.Pp 473.Bl -tag -width Ds -compact 474.It Converting to new file system format. 475A dump tape created from the old file system has been loaded. 476It is automatically converted to the new file system format. 477.Pp 478.It <filename>: not found on tape 479The specified file name was listed in the tape directory, 480but was not found on the tape. 481This is caused by tape read errors while looking for the file, 482and from using a dump tape created on an active file system. 483.Pp 484.It expected next file <inumber>, got <inumber> 485A file that was not listed in the directory showed up. 486This can occur when using a dump created on an active file system. 487.Pp 488.It Incremental dump too low 489When doing incremental restore, 490a dump that was written before the previous incremental dump, 491or that has too low an incremental level has been loaded. 492.Pp 493.It Incremental dump too high 494When doing incremental restore, 495a dump that does not begin its coverage where the previous incremental 496dump left off, 497or that has too high an incremental level has been loaded. 498.Pp 499.It Tape read error while restoring <filename> 500.It Tape read error while skipping over inode <inumber> 501.It Tape read error while trying to resynchronize 502A tape (or other media) read error has occurred. 503If a file name is specified, 504then its contents are probably partially wrong. 505If an inode is being skipped or the tape is trying to resynchronize, 506then no extracted files have been corrupted, 507though files may not be found on the tape. 508.Pp 509.It resync restore, skipped <num> blocks 510After a dump read error, 511.Nm 512may have to resynchronize itself. 513This message lists the number of blocks that were skipped over. 514.El 515.Sh SEE ALSO 516.Xr rcmd 1 , 517.Xr rcmd 3 , 518.Xr environ 7 , 519.Xr dump 8 , 520.Xr mount 8 , 521.Xr newfs 8 , 522.Xr rmt 8 523.Sh HISTORY 524The 525.Nm 526command appeared in 527.Bx 4.2 . 528.Sh BUGS 529.Nm 530can get confused when doing incremental restores from 531dumps that were made on active file systems. 532.Pp 533A level zero dump must be done after a full restore. 534Because 535.Nm 536runs in user mode, 537it has no control over inode allocation; 538thus a full dump must be done to get a new set of directories 539reflecting the new inode numbering, 540even though the content of the files is unchanged. 541.Pp 542The temporary files 543.Pa /tmp/rstdir* 544and 545.Pa /tmp/rstmode* 546are generated with a unique name based on the date of the dump 547and the process ID (see 548.Xr mktemp 3 ) , 549except for when 550.Fl r 551or 552.Fl R 553is used. 554Because 555.Fl R 556allows you to restart a 557.Fl r 558operation that may have been interrupted, the temporary files should 559be the same across different processes. 560In all other cases, the files are unique because it is possible to 561have two different dumps started at the same time, and separate 562operations shouldn't conflict with each other. 563