.\" Automatically generated by Pandoc 2.9.2.1
.\"
.TH "bup-restore" "1" "2021-02-06" "Bup 0.32" ""
.hy
.SH NAME
.PP
bup-restore - extract files from a backup set
.SH SYNOPSIS
.PP
bup restore [-r \f[I]host\f[R]:[\f[I]path\f[R]]]
[--outdir=\f[I]outdir\f[R]] [--exclude-rx \f[I]pattern\f[R]]
[--exclude-rx-from \f[I]filename\f[R]] [-v] [-q] <paths\&...>
.SH DESCRIPTION
.PP
\f[C]bup restore\f[R] extracts files from a backup set (created with
\f[C]bup-save\f[R](1)) to the local filesystem.
.PP
The specified \f[I]paths\f[R] are of the form
/\f[I]branch\f[R]/\f[I]revision\f[R]/\f[I]some/where\f[R].
The components of the path are as follows:
.TP
branch
the name of the backup set to restore from; this corresponds to the
\f[C]--name\f[R] (\f[C]-n\f[R]) option to \f[C]bup save\f[R].
.TP
revision
the revision of the backup set to restore.
The revision \f[I]latest\f[R] is always the most recent backup on the
given branch.
You can discover other revisions using \f[C]bup ls /branch\f[R].
.TP
some/where
the previously saved path (after any stripping/grafting) that you want
to restore.
For example, \f[C]etc/passwd\f[R].
.PP
If \f[I]some/where\f[R] names a directory, \f[C]bup restore\f[R] will
restore that directory and then recursively restore its contents.
.PP
If \f[I]some/where\f[R] names a directory and ends with a slash (ie.
path/to/dir/), \f[C]bup restore\f[R] will restore the children of that
directory directly to the current directory (or the \f[C]--outdir\f[R]).
If \f[I]some/where\f[R] does not end in a slash, the children will be
restored to a subdirectory of the current directory.
.PP
If \f[I]some/where\f[R] names a directory and ends in `/.' (ie.
path/to/dir/.), \f[C]bup restore\f[R] will do exactly what it would have
done for path/to/dir, and then restore \f[I]dir\f[R]\[cq]s metadata to
the current directory (or the \f[C]--outdir\f[R]).
See the EXAMPLES section.
.PP
As a special case, if \f[I]some/where\f[R] names the \[lq]latest\[rq]
symlink, e.g.\ \f[C]bup restore /foo/latest\f[R], then bup will act
exactly as if the save that \[lq]latest\[rq] points to had been
specified, and restore that, rather than the \[lq]latest\[rq] symlink
itself.
.PP
Whenever path metadata is available, \f[C]bup restore\f[R] will attempt
to restore it.
When restoring ownership, bup implements tar/rsync-like semantics.
It will normally prefer user and group names to uids and gids when
they\[cq]re available, but it will not try to restore the user unless
running as root, and it will fall back to the numeric uid or gid
whenever the metadata contains a user or group name that doesn\[cq]t
exist on the current system.
The use of user and group names can be disabled via
\f[C]--numeric-ids\f[R] (which can be important when restoring a chroot,
for example), and as a special case, a uid or gid of 0 will never be
remapped by name.
Additionally, some systems don\[cq]t allow setting a uid/gid that
doesn\[cq]t correspond with a known user/group.
On those systems, bup will log an error for each relevant path.
.PP
The \f[C]--map-user\f[R], \f[C]--map-group\f[R], \f[C]--map-uid\f[R],
\f[C]--map-gid\f[R] options may be used to adjust the available
ownership information before any of the rules above are applied, but
note that due to those rules, \f[C]--map-uid\f[R] and
\f[C]--map-gid\f[R] will have no effect whenever a path has a valid user
or group.
In those cases, either \f[C]--numeric-ids\f[R] must be specified, or the
user or group must be cleared by a suitable \f[C]--map-user foo=\f[R] or
\f[C]--map-group foo=\f[R].
.PP
Hardlinks will also be restored when possible, but at least currently,
no links will be made to targets outside the restore tree, and if the
restore tree spans a different arrangement of filesystems from the save
tree, some hardlink sets may not be completely restored.
.PP
Also note that changing hardlink sets on disk between index and save may
produce unexpected results.
With the current implementation, bup will attempt to recreate any given
hardlink set as it existed at index time, even if all of the files in
the set weren\[cq]t still hardlinked (but were otherwise identical) at
save time.
.PP
Note that during the restoration process, access to data within the
restore tree may be more permissive than it was in the original source.
Unless security is irrelevant, you must restore to a private
subdirectory, and then move the resulting tree to its final position.
See the EXAMPLES section for a demonstration.
.SH OPTIONS
.TP
-r, --remote=\f[I]host\f[R]:\f[I]path\f[R]
restore the backup set from the given remote server.
If \f[I]path\f[R] is omitted, uses the default path on the remote server
(you still need to include the `:').
The connection to the remote server is made with SSH.
If you\[cq]d like to specify which port, user or private key to use for
the SSH connection, we recommend you use the \f[C]\[ti]/.ssh/config\f[R]
file.
.TP
-C, --outdir=\f[I]outdir\f[R]
create and change to directory \f[I]outdir\f[R] before extracting the
files.
.TP
--numeric-ids
restore numeric IDs (user, group, etc.) rather than names.
.TP
--exclude-rx=\f[I]pattern\f[R]
exclude any path matching \f[I]pattern\f[R], which must be a Python
regular expression (http://docs.python.org/library/re.html).
The pattern will be compared against the full path rooted at the top of
the restore tree, without anchoring, so \[lq]x/y\[rq] will match
\[lq]ox/yard\[rq] or \[lq]box/yards\[rq].
To exclude the contents of /tmp, but not the directory itself, use
\[lq]\[ha]/tmp/.\[rq].
(can be specified more than once)
.RS
.PP
Note that the root of the restore tree (which matches `\[ha]/') is the
top of the archive tree being restored, and has nothing to do with the
filesystem destination.
Given \[lq]restore \&... /foo/latest/etc/\[rq], the pattern
`\[ha]/passwd$' would match if a file named passwd had been saved as
`/foo/latest/etc/passwd'.
.PP
Examples:
.IP \[bu] 2
`/foo$' - exclude any file named foo
.IP \[bu] 2
`/foo/$' - exclude any directory named foo
.IP \[bu] 2
`/foo/.' - exclude the content of any directory named foo
.IP \[bu] 2
`\[ha]/tmp/.' - exclude root-level /tmp\[cq]s content, but not /tmp
itself
.RE
.TP
--exclude-rx-from=\f[I]filename\f[R]
read \[en]exclude-rx patterns from \f[I]filename\f[R], one pattern
per-line (may be repeated).
Ignore completely empty lines.
.TP
--sparse
write output data sparsely when reasonable.
Currently, reasonable just means \[lq]at least whenever there are 512 or
more consecutive zeroes\[rq].
.TP
--map-user \f[I]old\f[R]=\f[I]new\f[R]
for every path, restore the \f[I]old\f[R] (saved) user name as
\f[I]new\f[R].
Specifying \[dq]\[dq] for \f[I]new\f[R] will clear the user.
For example \[lq]\[en]map-user foo=\[rq] will allow the uid to take
effect for any path that originally had a user of \[lq]foo\[rq], unless
countermanded by a subsequent \[lq]\[en]map-user foo=\&...\[rq]
specification.
See DESCRIPTION above for further information.
.TP
--map-group \f[I]old\f[R]=\f[I]new\f[R]
for every path, restore the \f[I]old\f[R] (saved) group name as
\f[I]new\f[R].
Specifying \[dq]\[dq] for \f[I]new\f[R] will clear the group.
For example \[lq]\[en]map-group foo=\[rq] will allow the gid to take
effect for any path that originally had a group of \[lq]foo\[rq], unless
countermanded by a subsequent \[lq]\[en]map-group foo=\&...\[rq]
specification.
See DESCRIPTION above for further information.
.TP
--map-uid \f[I]old\f[R]=\f[I]new\f[R]
for every path, restore the \f[I]old\f[R] (saved) uid as \f[I]new\f[R],
unless countermanded by a subsequent \[lq]\[en]map-uid
\f[I]old\f[R]=\&...\[rq] option.
Note that the uid will only be relevant for paths with no user.
See DESCRIPTION above for further information.
.TP
--map-gid \f[I]old\f[R]=\f[I]new\f[R]
for every path, restore the \f[I]old\f[R] (saved) gid as \f[I]new\f[R],
unless countermanded by a subsequent \[lq]\[en]map-gid
\f[I]old\f[R]=\&...\[rq] option.
Note that the gid will only be relevant for paths with no user.
See DESCRIPTION above for further information.
.TP
-v, --verbose
increase log output.
Given once, prints every directory as it is restored; given twice,
prints every file and directory.
.TP
-q, --quiet
suppress output, including the progress meter.
Normally, if stderr is a tty, a progress meter displays the total number
of files restored.
.SH EXAMPLES
.PP
Create a simple test backup set:
.IP
.nf
\f[C]
$ bup index -u /etc
$ bup save -n mybackup /etc/passwd /etc/profile
\f[R]
.fi
.PP
Restore just one file:
.IP
.nf
\f[C]
$ bup restore /mybackup/latest/etc/passwd
Restoring: 1, done.

$ ls -l passwd
-rw-r--r-- 1 apenwarr apenwarr 1478 2010-09-08 03:06 passwd
\f[R]
.fi
.PP
Restore etc to test (no trailing slash):
.IP
.nf
\f[C]
$ bup restore -C test /mybackup/latest/etc
Restoring: 3, done.

$ find test
test
test/etc
test/etc/passwd
test/etc/profile
\f[R]
.fi
.PP
Restore the contents of etc to test (trailing slash):
.IP
.nf
\f[C]
$ bup restore -C test /mybackup/latest/etc/
Restoring: 2, done.

$ find test
test
test/passwd
test/profile
\f[R]
.fi
.PP
Restore the contents of etc and etc\[cq]s metadata to test (trailing
\[lq]/.\[rq]):
.IP
.nf
\f[C]
$ bup restore -C test /mybackup/latest/etc/.
Restoring: 2, done.

# At this point test and etc\[aq]s metadata will match.
$ find test
test
test/passwd
test/profile
\f[R]
.fi
.PP
Restore a tree without risk of unauthorized access:
.IP
.nf
\f[C]
# mkdir --mode 0700 restore-tmp

# bup restore -C restore-tmp /somebackup/latest/foo
Restoring: 42, done.

# mv restore-tmp/foo somewhere

# rmdir restore-tmp
\f[R]
.fi
.PP
Restore a tree, remapping an old user and group to a new user and group:
.IP
.nf
\f[C]
# ls -l /original/y
-rw-r----- 1 foo baz  3610 Nov  4 11:31 y
# bup restore -C dest --map-user foo=bar --map-group baz=bax /x/latest/y
Restoring: 42, done.
# ls -l dest/y
-rw-r----- 1 bar bax  3610 Nov  4 11:31 y
\f[R]
.fi
.PP
Restore a tree, remapping an old uid to a new uid.
Note that the old user must be erased so that bup won\[cq]t prefer it
over the uid:
.IP
.nf
\f[C]
# ls -l /original/y
-rw-r----- 1 foo baz  3610 Nov  4 11:31 y
# ls -ln /original/y
-rw-r----- 1 1000 1007  3610 Nov  4 11:31 y
# bup restore -C dest --map-user foo= --map-uid 1000=1042 /x/latest/y
Restoring: 97, done.
# ls -ln dest/y
-rw-r----- 1 1042 1007  3610 Nov  4 11:31 y
\f[R]
.fi
.PP
An alternate way to do the same by quashing users/groups universally
with \f[C]--numeric-ids\f[R]:
.IP
.nf
\f[C]
# bup restore -C dest --numeric-ids --map-uid 1000=1042 /x/latest/y
Restoring: 97, done.
\f[R]
.fi
.SH SEE ALSO
.PP
\f[C]bup-save\f[R](1), \f[C]bup-ftp\f[R](1), \f[C]bup-fuse\f[R](1),
\f[C]bup-web\f[R](1)
.SH BUP
.PP
Part of the \f[C]bup\f[R](1) suite.
.SH AUTHORS
Avery Pennarun <apenwarr@gmail.com>.