restore/restore.8.in

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