1RESTORE(8)                System management commands                RESTORE(8)
2
3
4

NAME

6       restore - restore files or file systems from backups made with dump
7

SYNOPSIS

9       restore  -C  [-cdHklMvVy]  [-b blocksize] [-D filesystem] [-f file] [-F
10       script] [-L limit] [-s fileno] [-T directory]
11
12       restore -i [-acdhHklmMNouvVy] [-A file] [-b blocksize]  [-f  file]  [-F
13       script] [-Q file] [-s fileno] [-T directory]
14
15       restore  -P  file  [-acdhHklmMNuvVy] [-A file] [-b blocksize] [-f file]
16       [-F script] [-s fileno] [-T directory] [-X filelist] [ file ... ]
17
18       restore -R [-cdHklMNuvVy] [-b blocksize]  [-f  file]  [-F  script]  [-s
19       fileno] [-T directory]
20
21       restore  -r  [-cdHklMNuvVy]  [-b  blocksize]  [-f file] [-F script] [-s
22       fileno] [-T directory]
23
24       restore -t [-cdhHklMNuvVy] [-A  file]  [-b  blocksize]  [-f  file]  [-F
25       script] [-Q file] [-s fileno] [-T directory] [-X filelist] [ file ... ]
26
27       restore  -x  [-adchHklmMNouvVy]  [-A file] [-b blocksize] [-f file] [-F
28       script] [-Q file] [-s fileno] [-T directory] [-X filelist] [ file ... ]
29

DESCRIPTION

31       The restore command performs the inverse function of dump(8).   A  full
32       backup  of  a  file  system  may be restored and subsequent incremental
33       backups layered on top of it. Single files and directory  subtrees  may
34       be  restored from full or partial backups.  Restore works across a net‐
35       work; to do this see the -f flag described below.  Other  arguments  to
36       the  command  are file or directory names specifying the files that are
37       to be restored. Unless the  -h  flag  is  specified  (see  below),  the
38       appearance  of  a  directory name refers to the files and (recursively)
39       subdirectories of that directory.
40
41       Exactly one of the following flags is required:
42
43       -C     This mode allows comparison of files from a dump.  Restore reads
44              the  backup  and compares its contents with files present on the
45              disk. It first changes its working directory to the root of  the
46              filesystem  that was dumped and compares the tape with the files
47              in its new current directory. See also  the  -L  flag  described
48              below.
49
50       -i     This  mode  allows interactive restoration of files from a dump.
51              After reading  in  the  directory  information  from  the  dump,
52              restore  provides a shell like interface that allows the user to
53              move around the directory tree selecting files to be  extracted.
54              The  available commands are given below; for those commands that
55              require an argument, the default is the current directory.
56
57              add [arg]
58                     The current directory or specified argument is  added  to
59                     the  list  of  files  to be extracted.  If a directory is
60                     specified, then it and all its descendents are  added  to
61                     the  extraction  list (unless the -h flag is specified on
62                     the command line). Files that are on the extraction  list
63                     are prepended with a “*” when they are listed by ls.
64
65              cd arg Change  the  current  working  directory to the specified
66                     argument.
67
68              delete [arg]
69                     The current directory or specified  argument  is  deleted
70                     from the list of files to be extracted. If a directory is
71                     specified, then it and all its  descendents  are  deleted
72                     from the extraction list (unless the -h flag is specified
73                     on the command line). The most expedient way  to  extract
74                     most  of  the files from a directory is to add the direc‐
75                     tory to the extraction list and then delete  those  files
76                     that are not needed.
77
78              extract
79                     All  files  on the extraction list are extracted from the
80                     dump.  Restore will ask which volume the user  wishes  to
81                     mount.  The  fastest  way  to  extract a f ew files is to
82                     start with the last volume and  work  towards  the  first
83                     volume.
84
85              help   List a summary of the available commands.
86
87              ls [arg]
88                     List the current or specified directory. Entries that are
89                     directories are appended with a “/”.  Entries  that  have
90                     been  marked  for extraction are prepended with a “*”. If
91                     the verbose flag is set, the inode number of  each  entry
92                     is also listed.
93
94              pwd    Print the full pathname of the current working directory.
95
96              quit   Restore immediately exits, even if the extraction list is
97                     not empty.
98
99              setmodes
100                     All directories that have been added  to  the  extraction
101                     list  have  their owner, modes, and times set; nothing is
102                     extracted from the dump. This is useful for  cleaning  up
103                     after a restore has been prematurely aborted.
104
105              verbose
106                     The  sense  of the -v flag is toggled. When set, the ver‐
107                     bose flag causes the ls command to list the inode numbers
108                     of  all  entries.  It  also  causes  restore to print out
109                     information about each file as it is extracted.
110
111       -P file
112              Restore creates a new Quick File Access file file from an exist‐
113              ing dump file without restoring its contents.
114
115       -R     Restore  requests  a  particular  tape  of a multi-volume set on
116              which to restart a full restore (see the -r flag below). This is
117              useful if the restore has been interrupted.
118
119       -r     Restore  (rebuild)  a file system. The target file system should
120              be made pristine with mke2fs(8), mounted, and the user cd'd into
121              the  pristine file system before starting the restoration of the
122              initial level 0 backup. If the level  0  restores  successfully,
123              the  -r  flag  may  be used to restore any necessary incremental
124              backups on top of the level 0. The -r flag precludes an interac‐
125              tive file extraction and can be detrimental to one's health (not
126              to mention the disk) if not used carefully. An example:
127
128                     mke2fs /dev/sda1
129
130                     mount /dev/sda1 /mnt
131
132                     cd /mnt
133
134                     restore rf /dev/st0
135
136              Note that restore leaves a  file  restoresymtable  in  the  root
137              directory   to  pass  information  between  incremental  restore
138              passes.  This file should be removed when the  last  incremental
139              has been restored.
140
141              Restore,  in conjunction with mke2fs(8) and dump(8), may be used
142              to modify file system parameters such as size or block size.
143
144       -t     The names of the specified files are listed if they occur on the
145              backup.  If  no  file  argument  is given, the root directory is
146              listed, which results in the entire content of the backup  being
147              listed, unless the -h flag has been specified.  Note that the -t
148              flag replaces the function of the old dumpdir(8)  program.   See
149              also the -X option below.
150
151       -x     The  named  files are read from the given media. If a named file
152              matches a directory whose contents are on the backup and the  -h
153              flag  is  not specified, the directory is recursively extracted.
154              The owner, modification time, and mode are restored  (if  possi‐
155              ble).  If  no  file  argument  is  given,  the root directory is
156              extracted, which results in the entire  content  of  the  backup
157              being  extracted,  unless  the  -h flag has been specified.  See
158              also the -X option below.
159

OPTIONS

161       The following additional options may be specified:
162
163       -a     In -i or -x mode, restore does ask the user for the volume  num‐
164              ber  on  which  the files to be extracted are supposed to be (in
165              order to minimise the time by reading only the interesting  vol‐
166              umes).  The  -a option disables this behaviour and reads all the
167              volumes starting with 1. This option is useful when the operator
168              does  not  know  on  which  volume the files to be extracted are
169              and/or when he prefers the longer unattended  mode  rather  than
170              the shorter interactive mode.
171
172       -A archive_file
173              Read  the  table  of  contents  from archive_file instead of the
174              media. This option can be used in combination with the  -t,  -i,
175              or  -x options, making it possible to check whether files are on
176              the media without having to mount the media.
177
178       -b blocksize
179              The number of kilobytes per dump record. If the -b option is not
180              specified,  restore  tries  to  determine  the  media block size
181              dynamically.
182
183       -c     Normally, restore will try to determine dynamically whether  the
184              dump  was  made from an old (pre-4.4) or new format file system.
185              The -c flag disables this check, and only allows reading a  dump
186              in the old format.
187
188       -d     The -d (debug) flag causes restore to print debug information.
189
190       -D filesystem
191              The  -D flag allows the user to specify the filesystem name when
192              using restore with the -C option to check the backup.
193
194       -f file
195              Read the backup from file; file may be  a  special  device  file
196              like /dev/st0 (a tape drive), /dev/sda1 (a disk drive), an ordi‐
197              nary file, or - (the standard input). If the name of the file is
198              of  the form host:file or user@host:file, restore reads from the
199              named file on the remote host using rmt(8).
200
201       -F script
202              Run script at the beginning of each tape. The  device  name  and
203              the  current  volume  number are passed on the command line. The
204              script must return 0 if restore should continue  without  asking
205              the  user  to  change the tape, 1 if restore should continue but
206              ask the user to change the tape. Any other exit code will  cause
207              restore  to abort. For security reasons, restore reverts back to
208              the real user ID and  the  real  group  ID  before  running  the
209              script.
210
211       -h     Extract the actual directory, rather than the files that it ref‐
212              erences. This prevents hierarchical restoration of complete sub‐
213              trees from the dump.
214
215       -H hash_size
216              Use a hashtable having the specified number of entries for stor‐
217              ing the directories entries  instead  of  a  linked  list.  This
218              hashtable  will  considerably  speed  up  inode lookups (visible
219              especialy in interactive mode when  adding/removing  files  from
220              the  restore  list), but at the price of much more memory usage.
221              The default value is 1, meaning no hashtable is used.
222
223       -k     Use Kerberos authentication  when  contacting  the  remote  tape
224              server. (Only available if this options was enabled when restore
225              was compiled.)
226
227       -l     When doing remote restores, assume the remote file is a  regular
228              file  (instead  of  a tape device). If you're restoring a remote
229              compressed file, you will need to specify this option or restore
230              will fail to access it correctly.
231
232       -L limit
233              The  -L flag allows the user to specify a maximal number of mis‐
234              compares when using restore with the  -C  option  to  check  the
235              backup.  If  this  limit  is reached, restore will abort with an
236              error message. A value of 0 (the  default  value)  disables  the
237              check.
238
239       -m     Extract  by inode numbers rather than by file name. This is use‐
240              ful if only a few files are being extracted, and  one  wants  to
241              avoid regenerating the complete pathname to the file.
242
243       -M     Enables  the  multi-volume feature (for reading dumps made using
244              the -M option of dump). The name specified with -f is treated as
245              a prefix and restore tries to read in sequence from <prefix>001,
246              <prefix>002 etc.
247
248       -N     The -N flag causes  restore  to  perform  a  full  execution  as
249              requested  by one of -i, -R, -r, t or x command without actually
250              writing any file on disk.
251
252       -o     The -o flag causes restore to automatically restore the  current
253              directory  permissions without asking the operator whether to do
254              so in one of -i or -x modes.
255
256       -Q file
257              Use the file file in order to read tape position as stored using
258              the dump Quick File Access mode, in one of -i, -x or -t mode.
259
260              It is recommended to set up the st driver to return logical tape
261              positions rather than physical before calling dump/restore  with
262              parameter  -Q.  Since not all tape devices support physical tape
263              positions those tape devices return an error during dump/restore
264              when  the  st  driver  is  set  to the default physical setting.
265              Please see the st(4) man page, option MTSETDRVBUFFER  ,  or  the
266              mt(1)  man page, on how to set the driver to return logical tape
267              positions.
268
269              Before calling restore with parameter -Q, always make  sure  the
270              st  driver  is set to return the same type of tape position used
271              during the call to dump.  Otherwise restore may be confused.
272
273              This option can be used when  restoring  from  local  or  remote
274              tapes (see above) or from local or remote files.
275
276       -s fileno
277              Read  from  the specified fileno on a multi-file tape. File num‐
278              bering starts at 1.
279
280       -T directory
281              The -T flag allows the user to specify a directory  to  use  for
282              the storage of temporary files. The default value is /tmp.  This
283              flag is most useful when restoring  files  after  having  booted
284              from  a  floppy. There might be little or no space on the floppy
285              filesystem, but another source of space might exist.
286
287       -u     When creating certain types of files,  restore  may  generate  a
288              warning  diagnostic  if  they already exist in the target direc‐
289              tory. To prevent this, the -u (unlink) flag  causes  restore  to
290              remove old entries before attempting to create new ones.
291
292       -v     Normally  restore  does its work silently. The -v (verbose) flag
293              causes it to type the name of each file it  treats  preceded  by
294              its file type.
295
296       -V     Enables reading multi-volume non-tape mediums like CDROMs.
297
298       -X filelist
299              Read  list of files to be listed or extracted from the text file
300              filelist in addition to those specified  on  the  command  line.
301              This  can be used in conjunction with the -t or -x commands. The
302              file filelist should contain file names separated  by  newlines.
303              filelist may be an ordinary file or - (the standard input).
304
305       -y     Do not ask the user whether to abort the restore in the event of
306              an error.  Always try to skip over the  bad  block(s)  and  con‐
307              tinue.
308
309       (The 4.3BSD option syntax is implemented for backward compatibility but
310       is not documented here.)
311

DIAGNOSTICS

313       Complains if it gets a read error. If y has been specified, or the user
314       responds y, restore will attempt to continue the restore.
315
316       If  a  backup  was  made  using more than one tape volume, restore will
317       notify the user when it is time to mount the next volume. If the -x  or
318       -i flag has been specified, restore will also ask which volume the user
319       wishes to mount. The fastest way to extract a few  files  is  to  start
320       with the last volume, and work towards the first volume.
321
322       There  are  numerous  consistency checks that can be listed by restore.
323       Most checks are self-explanatory or can “never happen”.  Common  errors
324       are given below:
325
326       Converting to new file system format
327              A dump tape created from the old file system has been loaded. It
328              is automatically converted to the new file system format.
329
330       <filename>: not found on tape
331              The specified file name was listed in the  tape  directory,  but
332              was  not  found  on the tape. This is caused by tape read errors
333              while looking for the file, and from using a dump  tape  created
334              on an active file system.
335
336       expected next file <inumber>, got <inumber>
337              A  file that was not listed in the directory showed up. This can
338              occur when using a dump created on an active file system.
339
340       Incremental dump too low
341              When doing an incremental  restore,  a  dump  that  was  written
342              before  the  previous  incremental  dump, or that has too low an
343              incremental level has been loaded.
344
345       Incremental dump too high
346              When doing an incremental restore, a dump that  does  not  begin
347              its  coverage  where  the previous incremental dump left off, or
348              that has too high an incremental level has been loaded.
349
350       Tape read error while restoring <filename>
351
352       Tape read error while skipping over inode <inumber>
353
354       Tape read error while trying to resynchronize
355              A tape (or other media) read error has occurred. If a file  name
356              is  specified,  its contents are probably partially wrong. If an
357              inode is being skipped or the tape is trying  to  resynchronize,
358              no  extracted files have been corrupted, though files may not be
359              found on the tape.
360
361       resync restore, skipped <num> blocks
362              After a dump read  error,  restore  may  have  to  resynchronize
363              itself.  This  message  lists  the  number  of  blocks that were
364              skipped over.
365

EXIT STATUS

367       Restore exits with zero status on success. Tape  errors  are  indicated
368       with an exit code of 1.
369
370       When  doing  a comparison of files from a dump, an exit code of 2 indi‐
371       cates that some files were modified or deleted since the dump was made.
372

ENVIRONMENT

374       If the following environment variable exists it  will  be  utilized  by
375       restore:
376
377       TAPE   If no -f option was specified, restore will use the device spec‐
378              ified via TAPE as the dump device.  TAPE  may  be  of  the  form
379              tapename, host:tapename or user@host:tapename.
380
381       TMPDIR The  directory  given  in TMPDIR will be used instead of /tmp to
382              store temporary files.
383
384       RMT    The environment variable RMT will be used to determine the path‐
385              name of the remote rmt(8) program.
386
387       RSH    Restore uses the contents of this variable to determine the name
388              of the remote shell command to use when doing a network  restore
389              (rsh,  ssh  etc.).  If this variable is not set, rcmd(3) will be
390              used, but only root will be able to do a network restore.
391

FILES

393       /dev/st0
394              the default tape drive
395
396       /tmp/rstdir*
397              file containing directories on the tape
398
399       /tmp/rstmode*
400              owner, mode, and time stamps for directories
401
402       ./restoresymtable
403              information passed between incremental restores
404

SEE ALSO

406       dump(8), mount(8), mke2fs(8), rmt(8)
407

BUGS

409       Restore can get confused when doing  incremental  restores  from  dumps
410       that were made on active file systems.
411
412       A  level 0 dump must be done after a full restore. Because restore runs
413       in user code, it has no control over inode allocation; thus a full dump
414       must  be  done to get a new set of directories reflecting the new inode
415       numbering, even though the content of the files is unchanged.
416
417       The temporary files /tmp/rstdir* and /tmp/rstmode* are generated with a
418       unique  name  based  on  the  date  of the dump and the process ID (see
419       mktemp(3)), except when -r or -R is used.  Because  -R  allows  you  to
420       restart  a  -r  operation that may have been interrupted, the temporary
421       files should be the same  across  different  processes.  In  all  other
422       cases,  the files are unique because it is possible to have two differ‐
423       ent dumps started at the same time, and separate  operations  shouldn't
424       conflict with each other.
425
426       To  do  a  network  restore,  you  have to run restore as root or use a
427       remote shell replacement (see RSH variable).  This is due to the previ‐
428       ous  security  history of dump and restore.  ( restore is written to be
429       setuid root, but we are not certain all bugs are gone from the  code  -
430       run setuid at your own risk.)
431
432       At  the end of restores in -i or -x modes (unless -o option is in use),
433       restore will ask the operator whether to set  the  permissions  on  the
434       current  directory.  If  the operator confirms this action, the permis‐
435       sions on the directory from where restore was launched will be replaced
436       by the permissions on the dumped root inode. Although this behaviour is
437       not really a bug, it has proven itself to be confusing for many  users,
438       so  it  is  recommended to answer 'no', unless you're performing a full
439       restore and you do want to restore the permissions on '/'.
440
441       It should be underlined that because it runs in user  code,  restore  ,
442       when  run  with  the  -C  option, sees the files as the kernel presents
443       them, whereas dump sees all the files on a given filesystem. In partic‐
444       ular,  this can cause some confusion when comparing a dumped filesystem
445       a part of which is hidden by a filesystem mounted on top of it.
446

AUTHOR

448       The dump/restore backup suite was ported  to  Linux's  Second  Extended
449       File System by Remy Card <card@Linux.EU.Org>. He maintained the initial
450       versions of dump (up and including 0.4b4, released in january 1997).
451
452       Starting   with   0.4b5,   the   new   maintainer   is   Stelian    Pop
453       <stelian@popies.net>.
454

AVAILABILITY

456       The  dump/restore  backup  suite is available from <http://dump.source
457       forge.net>
458

HISTORY

460       The restore command appeared in 4.2BSD.
461
462
463
464BSD                    version 0.4b41 of January 2, 2006            RESTORE(8)
Impressum