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] [-b blocksize] [-f file] [-F script]
16       [-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 descendants 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  descendants  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 few files is to start
82                     with the last volume and work towards the first volume.
83
84              help   List a summary of the available commands.
85
86              ls [arg]
87                     List the current or specified directory. Entries that are
88                     directories  are  appended  with a “/”. Entries that have
89                     been marked for extraction are prepended with a  “*”.  If
90                     the  verbose  flag is set, the inode number of each entry
91                     is also listed.
92
93              pwd    Print the full pathname of the current working directory.
94
95              quit   Restore immediately exits, even if the extraction list is
96                     not empty.
97
98              setmodes
99                     All  directories  that  have been added to the extraction
100                     list have their owner, modes, and times set;  nothing  is
101                     extracted  from  the dump. This is useful for cleaning up
102                     after a restore has been prematurely aborted.
103
104              verbose
105                     The sense of the -v flag is toggled. When set,  the  ver‐
106                     bose flag causes the ls command to list the inode numbers
107                     of all entries. It  also  causes  restore  to  print  out
108                     information about each file as it is extracted.
109
110       -P file
111              Restore creates a new Quick File Access file file from an exist‐
112              ing dump file without restoring its contents.
113
114       -R     Restore requests a particular tape  of  a  multi-volume  set  on
115              which to restart a full restore (see the -r flag below). This is
116              useful if the restore has been interrupted.
117
118       -r     Restore (rebuild) a file system. The target file  system  should
119              be made pristine with mke2fs(8), mounted, and the user cd'd into
120              the pristine file system before starting the restoration of  the
121              initial  level  0  backup. If the level 0 restores successfully,
122              the -r flag may be used to  restore  any  necessary  incremental
123              backups on top of the level 0. The -r flag precludes an interac‐
124              tive file extraction and can be detrimental to one's health (not
125              to mention the disk) if not used carefully. An example:
126
127                     mke2fs /dev/sda1
128
129                     mount /dev/sda1 /mnt
130
131                     cd /mnt
132
133                     restore rf /dev/st0
134
135              Note  that  restore  leaves  a  file restoresymtable in the root
136              directory  to  pass  information  between  incremental   restore
137              passes.   This  file should be removed when the last incremental
138              has been restored.
139
140              Restore, in conjunction with mke2fs(8) and dump(8), may be  used
141              to modify file system parameters such as size or block size.
142
143       -t     The names of the specified files are listed if they occur on the
144              backup. If no file argument is  given,  the  root  directory  is
145              listed,  which results in the entire content of the backup being
146              listed, unless the -h flag has been specified.  Note that the -t
147              flag  replaces  the function of the old dumpdir(8) program.  See
148              also the -X option below.
149
150       -x     The named files are read from the given media. If a  named  file
151              matches  a directory whose contents are on the backup and the -h
152              flag is not specified, the directory is  recursively  extracted.
153              The  owner,  modification time, and mode are restored (if possi‐
154              ble). If no file  argument  is  given,  the  root  directory  is
155              extracted,  which  results  in  the entire content of the backup
156              being extracted, unless the -h flag  has  been  specified.   See
157              also the -X option below.
158

OPTIONS

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

DIAGNOSTICS

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

EXIT STATUS

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

ENVIRONMENT

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

FILES

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

SEE ALSO

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

BUGS

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

AUTHOR

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

AVAILABILITY

455       The dump/restore backup suite is available  from  <https://dump.source
456       forge.io>
457

HISTORY

459       The restore command appeared in 4.2BSD.
460
461
462
463BSD                      version 0.4b47 of 1 Jan 2021               RESTORE(8)
Impressum