1RESTORE(8) System management commands RESTORE(8)
2
6 restore - restore files or file systems from backups made with dump
7
9 restore -C [-cdHklMvVy] [-b blocksize] [-D filesystem] [-f file] [-F
10 script] [-L limit] [-s fileno] [-T directory]
11 restore -i [-acdhHklmMNouvVy] [-A file] [-b blocksize] [-f file] [-F
13 script] [-Q file] [-s fileno] [-T directory]
14 restore -P file [-acdhHklmMNuvVy] [-b blocksize] [-f file] [-F script]
16 [-s fileno] [-T directory] [-X filelist] [ file ... ]
17 restore -R [-cdHklMNuvVy] [-b blocksize] [-f file] [-F script] [-s
19 fileno] [-T directory]
20 restore -r [-cdHklMNuvVy] [-b blocksize] [-f file] [-F script] [-s
22 fileno] [-T directory]
23 restore -t [-cdhHklMNuvVy] [-A file] [-b blocksize] [-f file] [-F
25 script] [-Q file] [-s fileno] [-T directory] [-X filelist] [ file ... ]
26 restore -x [-adchHklmMNouvVy] [-A file] [-b blocksize] [-f file] [-F
28 script] [-Q file] [-s fileno] [-T directory] [-X filelist] [ file ... ]
29
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 Exactly one of the following flags is required:
42 -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 -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 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 cd arg Change the current working directory to the specified
66 argument.
67 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 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 help List a summary of the available commands.
86 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 pwd Print the full pathname of the current working directory.
95 quit Restore immediately exits, even if the extraction list is
97 not empty.
98 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 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 -P file
112 Restore creates a new Quick File Access file file from an exist‐
113 ing dump file without restoring its contents.
114 -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 -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 mke2fs /dev/sda1
129 mount /dev/sda1 /mnt
131 cd /mnt
133 restore rf /dev/st0
135 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 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 -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 -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
161 The following additional options may be specified:
162 -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 -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 -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 -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 -d The -d (debug) flag causes restore to print debug information.
189 -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 -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 -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 -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 -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 especially 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 -k Use Kerberos authentication when contacting the remote tape
224 server. (Only available if this options was enabled when restore
225 was compiled.)
226 -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 -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 -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 -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 -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 -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 -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 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 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 This option can be used when restoring from local or remote
274 tapes (see above) or from local or remote files.
275 -s fileno
277 Read from the specified fileno on a multi-file tape. File num‐
278 bering starts at 1.
279 -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 -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 -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 -V Enables reading multi-volume non-tape mediums like CDROMs.
297 -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 -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 (The 4.3BSD option syntax is implemented for backward compatibility but
310 is not documented here.)
311
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 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 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 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 <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 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 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 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 Tape read error while restoring <filename>
351 Tape read error while skipping over inode <inumber>
353 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 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
367 Restore exits with zero status on success. Tape errors are indicated
368 with an exit code of 1.
369 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
374 If the following environment variable exists it will be utilized by
375 restore:
376 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 TMPDIR The directory given in TMPDIR will be used instead of /tmp to
382 store temporary files.
383 RMT The environment variable RMT will be used to determine the path‐
385 name of the remote rmt(8) program.
386 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
393 /dev/st0
394 the default tape drive
395 /tmp/rstdir*
397 file containing directories on the tape
398 /tmp/rstmode*
400 owner, mode, and time stamps for directories
401 ./restoresymtable
403 information passed between incremental restores
404
406 dump(8), mount(8), mke2fs(8), rmt(8)
407
409 Restore can get confused when doing incremental restores from dumps
410 that were made on active file systems.
411 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 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 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 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 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
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 Starting with 0.4b5, the new maintainer is Stelian Pop
453 <stelian@popies.net>.
454
456 The dump/restore backup suite is available from <http://dump.source‐
457 forge.net>
458
460 The restore command appeared in 4.2BSD.
461BSD version 0.4b42 of June 18, 2009 RESTORE(8)