restore/restore.8

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