RESTORE(8)

📦
version 0.4b55 · 9 versions
, in ubuntu stonking

💖 RESTORE(8) 💖

system management commands, but make it a group chat 🫶

okay bestie, sit DOWN, because this one is the absolute crown jewel of disaster recovery and i need you to be so fr fr locked in for it. it's restore, from section 8 of the manual (that's the sysadmin zone, the grown-up zone 💅), and it's basically dump(8)'s other half. the comeback arc. the "girl, we can fix this" energy. ✨

✨ NAME ✨

restore — restore files or filesystems from backups made with dump

like. the whole point. the entire vibe. no cap. 🎀

🌸 SYNOPSIS 🌸

restore -C [-cdHklMqvVy] [-b blocksize] [-D filesystem] [-f file] [-F
script] [-L limit] [-s fileno] [-T directory]

restore -i [-acdhHklmMNoquvVy] [-A file] [-b blocksize] [-f file] [-F
script] [-Q file] [-s fileno] [-T directory]

restore -P file [-acdhHklmMNquvVy] [-b blocksize] [-f file] [-F script]
[-s fileno] [-T directory] [-X filelist] [ file ... ]

restore -R [-cdHklMNquvVy] [-b blocksize] [-f file] [-F script] [-s
fileno] [-T directory]

restore -r [-cdHklMNquvVy] [-b blocksize] [-f file] [-F script] [-s
fileno] [-T directory]

restore -t [-cdhHklMNquvVy] [-A file] [-b blocksize] [-f file] [-F
script] [-Q file] [-s fileno] [-T directory] [-X filelist] [ file ... ]

restore -x [-adchHklmMNoquvVy] [-A file] [-b blocksize] [-f file] [-F
script] [-Q file] [-s fileno] [-T directory] [-X filelist] [ file ... ]

look at all those flags. it's giving ✨options✨. every single one of them matters and we're gonna get to every single one, don't you worry 💜

👑 DESCRIPTION 👑

restore does the inverse function of dump(8). read that again. it's the undo button. the uno reverse card. 🦋

so here's the tea:

  • a full backup of a filesystem can be restored, and then subsequent incremental backups get layered on top of it. lasagna style. 🍓
  • you can also just grab single files and directory subtrees out of full or partial backups. you don't have to take the whole thing, she's flexible.
  • restore works across a network — for that, peep the -f flag down below, it's the one that makes it happen.
  • any other arguments to the command are file or directory names specifying the files that are to be restored.
  • and unless the -h flag is specified (again, see below, bestie), when you name a directory, it means the files and (recursively) subdirectories of that directory. so like. the whole tree. the full bloodline. 😭

🌈 exactly one. ONE. of the following flags is required 🌈

not two. not zero. exactly one. this is the vibe check and you WILL pass it or restore will be so disappointed in you 💀

-C

this mode lets you compare files from a dump. restore reads the backup and compares its contents with the files that are actually present on the disk. it first changes its working directory to the root of the filesystem that was dumped, and then it compares the tape with the files in its new current directory. also go look at the -L flag described below, it's her partner in crime. 👯

-i

the interactive one. the main character mode. 😌 after reading in the directory information from the dump, restore gives you a little shell-like interface so you can move around the directory tree and hand-pick which files get extracted. it's like shopping but for your own data, iconic.

the available commands are below — and for those commands that need an argument, the default is the current directory. 🛍️

✨ the interactive commands ✨

add [arg]

the current directory, or the argument you specified, gets added to the list of files to be extracted. if you name a directory, then it and all its descendants get added to the extraction list (unless the -h flag was specified on the command line, obviously). files that are on the extraction list get a “*” prepended to them when they're listed by ls. little star. little celebrity. ⭐

cd arg

change the current working directory to the specified argument. classic. we love her. 🚶‍♀️

delete [arg]

the current directory, or the argument you specified, gets deleted from the list of files to be extracted. and yeah, if it's a directory, then it and all its descendants come off the extraction list (unless, once again, the -h flag was specified on the command line).

okay and here's the pro tip from the ancestors: the most expedient way to extract most of the files from a directory is to add the directory to the extraction list and then delete those files that are not needed. add everything, remove the crumbs. so efficient. 💅

extract

all files on the extraction list are extracted from the dump. restore will ask you which volume you wish to mount. and the fastest way to extract a few files is to start with the last volume and work toward the first volume. backwards and unbothered. 🌀

help

list a summary of the available commands. your little cheat sheet. your safety net. 🫶

ls [arg]

list the current or specified directory. entries that are directories get a “/” appended. entries that have been marked for extraction get a “*” prepended. and if the verbose flag is set, the inode number of each entry also gets listed. receipts. 🧾

pwd

print the full pathname of the current working directory. where am i. who am i. what is a filesystem. 🌌

quit

restore immediately exits, even if the extraction list is not empty. she does not do lingering goodbyes. she's gone. 💨

setmodes

every directory that's been added to the extraction list gets its owner, modes, and times set; nothing is extracted from the dump. this is for cleaning up after a restore has been prematurely aborted. the "okay we're not doing this today" command. 🙈

verbose

toggles the sense of the -v flag. when it's set, the verbose flag causes the ls command to list the inode numbers of all entries. it also causes restore to print out information about each file as it is extracted. she narrates. she's a talker. 🗣️

-P file

restore creates a new Quick File Access file file from an existing dump file, without restoring its contents. just the index, no main event. 👑

-R

restore requests a particular tape of a multi-volume set on which to restart a full restore (see the -r flag below). this is useful if the restore has been interrupted. we've all been interrupted. it's fine. resume. 🌈

-r

restore (rebuild) a filesystem.

okay so listen carefully because this one has RULES. the target filesystem should be made pristine with mke2fs(8), mounted, and the user should cd into the pristine filesystem before starting the restoration of the initial level 0 backup. if the level 0 restores successfully, the -r flag may be used to restore any necessary incremental backups on top of the level 0.

and now, the warning, said dramatically because it is dramatic:

the -r flag precludes an interactive file extraction and can be detrimental to one's health (not to mention the disk) if not used carefully. 🚨💀

an example, so you don't have to guess:

mke2fs /dev/sda1

mount /dev/sda1 /mnt

cd /mnt

restore -r -f /dev/st0

note that restore leaves a file restoresymtable in the root directory to pass information between incremental restore passes. this file should be removed when the last incremental has been restored. don't leave her hanging around, she's done her job. 🎀

restore, in conjunction with mke2fs(8) and dump(8), may be used to modify filesystem parameters such as size or block size. glow-up your filesystem. ✨

-t

the names of the specified files are listed if they occur on the backup. if no file argument is given, the root directory is listed, which results in the entire content of the backup being listed, unless the -h flag has been specified.

also note that the -t flag replaces the function of the old dumpdir(8) program. she's the new girl and she's doing it better. 💅

see also the -X option below. and ooo, if the -0 flag is used, the output separator is the null character (instead of the newline character). null. the quiet one. 🌚

-x

the named files are read from the given media. if a named file matches a directory whose contents are on the backup and the -h flag is not specified, the directory is recursively extracted. the owner, modification time, and mode are restored (if possible — no promises, bestie 🫶).

if no file argument is given, the root directory is extracted, which results in the entire content of the backup being extracted, unless the -h flag has been specified.

see also the -X option below. yes, again. she's that important. 👀

✨ OPTIONS ✨

okay so here's the extra stuff you can tack on, bestie 💅

  • -a, --no-ask-volume — so when you're in -i or -x mode, restore literally pops the question and asks you which volume number the files you want are on (the whole point being it only reads the interesting volumes, so it's faster). This flag says "no thank u, no questions" and just reads every volume starting from 1. Which is the move when you genuinely have no idea which volume has your files, or when you'd rather sit through a longer run that doesn't need you, instead of a shorter run that keeps bugging you. unattended mode >> interactive mode, lowkey. 🙂‍↕️
  • -A, --archive-file archive_file — read the table of contents out of archive_file instead of off the media itself. Team it up with -t, -i, or -x and you can check whether files are even on the media without mounting the media. no mounting, no drama. 🎀
  • -b, --block-size blocksize — how many kilobytes go in each dump record. Skip this flag and restore will try to figure out the media block size dynamically, like the icon it is. ✨
  • -c, --old-format — normally restore vibes it out on its own and detects whether the dump came from an old (pre-4.4) or new format filesystem. This flag turns that check off and only lets you read a dump in the old format. that's the whole personality. 👑
  • -d, --debug — makes restore spill debug information. talkative king. 🗣️
  • -D, --filesystem-name filesystem — lets you name the filesystem when you're running restore with the -C option to check the backup.
  • -f, --input-file file — read the backup from file. and file can be honestly whatever: a special device file like /dev/st0 (tape drive) or /dev/sda1 (disk drive), a plain ordinary file, or - which means standard input. If the name looks like host:file or user@host:file, restore reads that named file off the remote host using rmt(8). remote bestie behavior fr fr 🌈
  • -F, --sot-script script — run script at the beginning of every single tape. the device name and the current volume number get passed in on the command line. the script has to return 0 if restore should keep going without asking you to swap the tape, or 1 if restore should keep going but do ask you to swap the tape. literally any other exit code and restore aborts, no discussion. and for security reasons, restore reverts back to the real user ID and the real group ID before it runs the script. safety first, always. 🔒
  • -h, --no-hierarchical-restore — extract the actual directory itself, not the files it references. this blocks hierarchical restoration of complete subtrees from the dump. one layer, that's it.
  • -H, --hash-size hash_size — use a hashtable with the number of entries you pick for storing the directory entries, instead of a linked list. this hashtable speeds up inode lookups a lot (you really notice it in interactive mode when you're adding/removing files from the restore list) — but the price is much more memory usage. the default value is 1, which means no hashtable at all. trade-offs, bestie. 💀
  • -k, --kerberos — use Kerberos authentication when you contact the remote tape server. (only available if this option was enabled when restore was compiled — so it might just not exist for you, rip.)
  • -L, --max-miscompares limit — lets you set a maximal number of miscompares when you're using restore with the -C option to check the backup. hit that limit and restore aborts with an error message. a value of 0 (the default) disables the check entirely. 🛑
  • -m, --extract-by-inode — extract by inode numbers instead of by filename. this one's for when you're only pulling out a few files and you want to dodge regenerating the complete pathname for the file. efficiency, periodt. ⚡
  • -M, --multivolume — turns on the multi-volume feature (for reading dumps that were made using the -M option of dump). the name you gave with -f gets treated as a prefix, and restore tries to read in sequence from <prefix>001, <prefix>002 and so on. so many volumes, so little time 📼
  • -N, --no-write — restore does a full execution exactly as requested by one of the -i, -R, -r, -t or -x commands, but without actually writing any file on disk. purely a rehearsal, no consequences. 🙈
  • -o, --set-curr-dir-perms — automatically restores the current directory permissions, no asking the operator whether to do it in one of -i or -x modes. it just does it. ✨
  • --no-set-curr-dir-perms — leaves the current directory permissions unchanged, and also doesn't ask the operator whether to do it in one of -i or -x modes. and btw, if you give both this and --set-curr-dir-perms, this flag takes priority. it wins. 👑
  • -q, --abort-on-intervention — aborts immediately the instant operator attention is needed. no prompting for read errors, no prompting for tape changes, none of it. if it needs you, it's out. 💅
  • -Q, --QFAfile file — use the file file to read the tape position as stored using the dump Quick File Access mode, in one of -i, -x or -t mode.
okay genuine heads-up bestie, this one has lore. it's recommended that you set up the st driver to return logical tape positions rather than physical ones before you call dump/restore with the -Q parameter. because not all tape devices support physical tape positions, and those devices will return an error during dump/restore when the st driver is sitting on its default physical setting. check the st(4) man page, the option MTSETDRVBUFFER, or the mt(1) man page for how to set the driver to return logical tape positions. and before you call restore with -Q, always make sure the st driver is set to return the same type of tape position that was used during the call to dump. otherwise restore may get confused. 😭

this option works when you're restoring from local or remote tapes (see above) or from local or remote files.

  • -s, --read-from-tape-fileno fileno — read from the fileno you specify on a multi-file tape. file numbering starts at 1. not zero, bestie, one. 🍓
  • -T, --tmp-dir directory — lets you pick a directory to use for storing temporary files. default value is /tmp. this flag is most useful when you're restoring files after having booted from a floppy — because there might be little or no space on the floppy filesystem, but another source of space might exist somewhere else. 🌸
  • -u, --unlink-existing — when it's creating certain types of files, restore may throw a warning diagnostic if those files already exist in the target directory. to stop that, the -u (unlink) flag makes restore remove the old entries before it tries to create the new ones. out with the old, in with the new 🔥
  • -v, --verbose — normally restore does its work silently, like a mystery. the -v (verbose) flag makes it print the name of each file it treats, preceded by its file type. narration on 🎙️
  • -0, --zero-terminator — the (zero terminated) flag makes the output lines zero terminated instead of line feed terminated. this flag is only recognized for -t (listing). just the one job. 🎯
  • -V, --multi-volume-non-tape-medium — enables reading multi-volume non-tape media, like CDROMs. 📀
  • -X, --extractlist-file filelist — read a list of files to be listed or extracted out of the text file filelist, on top of whatever you already put on the command line. you can use this together with the -t or -x commands. filelist should contain filenames separated by newlines. and filelist can be an ordinary file or - (the standard input). 🫶
  • -y, --no-abort-on-error — don't ask the user whether to abort the restore when an error happens. just always try to skip over the bad block(s) and keep going. we persist. 😤
  • --ignore-compression-flag-for-0.4b45-dumps — v0.4b45 of dump had a bug, and what that bug meant is that while the tape recorded that compression had been selected, the tape was actually written uncompressed. this option tells dump to ignore the compression flag and assume the dump is uncompressed.
⚠️ this option is only useful for reading these old corrupted dumps, and it will cause errors reading any other compressed dump. so like, don't just leave it on, bestie. 💀

(The 4.3BSD option syntax is implemented for backward compatibility but is not documented here.)

🌈 DIAGNOSTICS 🌈

so restore will complain if it gets a read error. if the -y flag has been specified, or if the user responds y, restore will attempt to continue the restore. 😌

if a backup was made using more than one tape volume, restore notifies the user when it's time to mount the next volume. and if the -x or -i flag has been specified, restore will also ask which volume the user wishes to mount. pro tip from the source material: the fastest way to extract a few files is to start with the last volume and work toward the first volume. backwards is bestie behavior. 🔄

there are numerous consistency checks that can be listed by restore. most of them are self-explanatory or "can never happen" (famous last words 💀). the common errors are given below:

  • Converting to new filesystem format — a dump tape created from the old filesystem has been loaded. it's automatically converted to the new filesystem format. glow up complete ✨
  • <filename>: not found on tape — the specified filename was listed in the tape directory, but it wasn't found on the tape. this happens because of tape read errors while looking for the file, and from using a dump tape created on an active filesystem. 😭
  • expected next file <inumber>, got <inumber> — a file that was not listed in the directory showed up. this can occur when you're using a dump created on an active filesystem.
  • Incremental dump too low — when you're doing an incremental restore, this means a dump that was written before the previous incremental dump, or that has too low an incremental level, has been loaded. 📉
  • Incremental dump too high — when you're doing an incremental restore, this means a dump that does not begin its coverage where the previous incremental dump left off, or that has too high an incremental level, has been loaded. 📈
  • Tape read error while restoring <filename>
  • Tape read error while skipping over inode <inumber>
  • Tape read error while trying to resynchronize

— a tape (or other media) read error has occurred. if a filename is specified, its contents are probably partially wrong. if an inode is being skipped or the tape is trying to resynchronize, no extracted files have been corrupted, though files may not be found on the tape. 🙏

  • resync restore, skipped <num> blocks — after a dump read error, restore may have to resynchronize itself. this message lists the number of blocks that were skipped over. counting the casualties fr fr 🧮

💥 EXIT STATUS 💥

okay bestie, here's the vibe check on how restore says goodbye:

  • exit code 0 — we ate, no crumbs, success 💅
  • exit code 1 — tape errors 😭 the tape said no
  • exit code 2 — only in compare mode (-C): this means some files were modified or deleted since the dump was made, i.e. your live filesystem said "not the same queen" 🙈

🌸 ENVIRONMENT 🌸

if these environment variables exist, restore will absolutely utilize them, no cap:

  • TAPE — if you didn't pass -f, restore uses the device you set here as the dump device. TAPE can be shaped like tapename, host:tapename, or user@host:tapename ✨
  • TMPDIR — the directory you put here gets used instead of /tmp for storing temp files 🎀
  • RMT — this one tells restore the pathname of the remote rmt(8) program 🫶
  • RSH — restore reads this to figure out which remote shell command to use for a network restore (rsh, ssh etc.). if it's not set, rcmd(3) gets used instead — but then only root can do a network restore 👑

📁 FILES 📁

  • /dev/st0 — the default tape drive, the classic 💾
  • /tmp/rstdir* — file containing directories on the tape 🗂️
  • /tmp/rstmode* — owner, mode, and timestamps for directories 🔐
  • ./restoresymtable — info passed between incremental restores, the little messenger 🦋

👀 SEE ALSO 👀

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

go read those too, they're all part of the same cinematic universe fr fr 🌈

🐛 BUGS 🐛

okay so this is the part where we keep it real, and some of it is genuinely spooky, so listen up:

  • restore can get confused when doing incremental restores from dumps that were made on active filesystems. it's giving chaos 💀
  • a level 0 dump must be done after a full restore. why? because restore runs in user code, so it has no control over inode allocation. that means you have to do a full dump to get a fresh set of directories reflecting the new inode numbering — even though the content of the files is unchanged. yes really, the content is the same, but the inodes moved, and that's the whole point 😤
  • the temp files /tmp/rstdir* and /tmp/rstmode* get generated with a unique name based on the date of the dump and the process ID (see mktemp(3)) — except when -r or -R is used. because -R lets you restart a -r operation that may have been interrupted, the temp files should be the same across different processes. in all other cases the files are unique, because it's possible to have two different dumps started at the same time, and separate operations shouldn't conflict with each other 🤝
  • to do a network restore, you have to run restore as root or use a remote shell replacement (see the RSH variable). this is due to the previous security history of dump and restore. and listen: restore is written to be setuid root, but we are not certain all bugs are gone from the code — run setuid at your own risk 🚨
  • at the end of restores in -i or -x modes (unless the -o option is in use), restore will ask the operator whether to set the permissions on the current directory. if the operator confirms this action, the permissions on the directory from where restore was launched get replaced by the permissions on the dumped root inode. although this behaviour isn't really a bug, it has proven itself to be confusing for many users, so it's recommended to answer 'no' — unless you're performing a full restore and you do actually want to restore the permissions on '/' 😅
  • and one more thing: because restore runs in user space, it sees only the files that the kernel exposes when invoked with the -C option, whereas dump sees all files on the underlying filesystem. this can lead to confusion when comparing a dumped filesystem with a live one in which part of the original tree is obscured by another filesystem mounted on top of it 🫠
bestie, that last one is the "two filesystems, one mount point" jump scare. if your compare is acting weird, check what's mounted where 👀

✍️ AUTHOR ✍️

the dump/restore backup suite was ported to Linux's Second Extended File System by Remy Card <card@Linux.EU.Org>. he maintained the initial versions of dump (up to and including 0.4b4, released in January 1997) 🫡

starting with 0.4b5, the new maintainer is Stelian Pop <stelian@popies.net> 💖

since release 0.4b49 the new maintainer is Tim Woodall <debianbugs@woodall.me.uk> 👑

📦 AVAILABILITY 📦

the dump/restore backup suite is available from https://dump.sourceforge.io — go get it, it's right there 🌟

📜 HISTORY 📜

the restore command appeared in 4.2BSD. ancient. iconic. still here. periodt 👑

and that's the whole page, bestie!! 🎀 this one came from the BSD family of man pages — it's version 0.4b55 of 10 Jun 2026 for RESTORE(8) 💖 ngl, a manual page that ships exit codes, a whole set of env vars, and a bug list with setuid warnings in it? that's main character energy fr 🦋 now go make that backup, your filesystem is counting on you 🫶✨

📦 where this page comes from