# SYNOPSIS
-bup restore [\--outdir=*outdir*] [-v] [-q] \<paths...\>;
+bup restore [-r *host*:[*path*]] [\--outdir=*outdir*] [\--exclude-rx *pattern*]
+[\--exclude-rx-from *filename*] [-v] [-q] \<paths...\>
# DESCRIPTION
with `bup-save`(1)) to the local filesystem.
The specified *paths* are of the form
-/_branch_/_revision_/_path/to/file_. The components of the
+/_branch_/_revision_/_some/where_. The components of the
path are as follows:
branch
backup on the given branch. You can discover other
revisions using `bup ls /branch`.
-/path/to/file
-: the original absolute filesystem path to the file you
- want to restore. For example, `/etc/passwd`.
+some/where
+: the previously saved path (after any stripping/grafting) that you
+ want to restore. For example, `etc/passwd`.
-Note: if the /path/to/file is a directory, `bup restore`
-will restore that directory as well as recursively
-restoring all its contents.
-
-If /path/to/file is a directory ending in a slash (ie.
-/path/to/dir/), `bup restore` will restore the children of
-that directory directly to the current directory (or the
-`--outdir`). If the directory does *not* end in a slash,
-the children will be restored to a subdirectory of the
-current directory. See the EXAMPLES section to see how
-this works.
+If _some/where_ names a directory, `bup restore` will restore that
+directory and then recursively restore its contents.
+
+If _some/where_ names a directory and ends with a slash (ie.
+path/to/dir/), `bup restore` will restore the children of that
+directory directly to the current directory (or the `--outdir`). If
+_some/where_ does not end in a slash, the children will be restored to
+a subdirectory of the current directory.
+
+If _some/where_ names a directory and ends in '/.' (ie.
+path/to/dir/.), `bup restore` will do exactly what it would have done
+for path/to/dir, and then restore _dir_'s metadata to the current
+directory (or the `--outdir`). See the EXAMPLES section.
+
+As a special case, if _some/where_ names the "latest" symlink,
+e.g. `bup restore /foo/latest`, then bup will act exactly as if the
+save that "latest" points to had been specified, and restore that,
+rather than the "latest" symlink itself.
Whenever path metadata is available, `bup restore` will attempt to
restore it. When restoring ownership, bup implements tar/rsync-like
-semantics. 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't exist on the
-current system. The use of user and group names can be disabled via
-`--numeric-ids` (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.
+semantics. It will normally prefer user and group names to uids and
+gids when they'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't
+exist on the current system. The use of user and group names can be
+disabled via `--numeric-ids` (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't allow
+setting a uid/gid that doesn't correspond with a known user/group. On
+those systems, bup will log an error for each relevant path.
+
+The `--map-user`, `--map-group`, `--map-uid`, `--map-gid` 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,
+`--map-uid` and `--map-gid` will have no effect whenever a path has a
+valid user or group. In those cases, either `--numeric-ids` must be
+specified, or the user or group must be cleared by a suitable
+`--map-user foo=` or `--map-group foo=`.
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
# OPTIONS
+-r, \--remote=*host*:*path*
+: restore the backup set from the given remote server. If
+ *path* 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'd like to specify which port, user
+ or private key to use for the SSH connection, we recommend you use the
+ `~/.ssh/config` file.
+
-C, \--outdir=*outdir*
: create and change to directory *outdir* before
extracting the files.
\--numeric-ids
: restore numeric IDs (user, group, etc.) rather than names.
+\--exclude-rx=*pattern*
+: exclude any path matching *pattern*, 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 "x/y" will match
+ "ox/yard" or "box/yards". To exclude the contents of /tmp, but
+ not the directory itself, use "^/tmp/.". (can be specified more
+ than once)
+
+ Note that the root of the restore tree (which matches '^/') is the
+ top of the archive tree being restored, and has nothing to do with
+ the filesystem destination. Given "restore ... /foo/latest/etc/",
+ the pattern '^/passwd$' would match if a file named passwd had
+ been saved as '/foo/latest/etc/passwd'.
+
+ Examples:
+
+ * '/foo$' - exclude any file named foo
+ * '/foo/$' - exclude any directory named foo
+ * '/foo/.' - exclude the content of any directory named foo
+ * '^/tmp/.' - exclude root-level /tmp's content, but not /tmp itself
+
+\--exclude-rx-from=*filename*
+: read --exclude-rx patterns from *filename*, one pattern per-line
+ (may be repeated). Ignore completely empty lines.
+
+\--sparse
+: write output data sparsely when reasonable. Currently, reasonable
+ just means "at least whenever there are 512 or more consecutive
+ zeroes".
+
+\--map-user *old*=*new*
+: for every path, restore the *old* (saved) user name as *new*.
+ Specifying "" for *new* will clear the user. For example
+ "--map-user foo=" will allow the uid to take effect for any path
+ that originally had a user of "foo", unless countermanded by a
+ subsequent "--map-user foo=..." specification. See DESCRIPTION
+ above for further information.
+
+\--map-group *old*=*new*
+: for every path, restore the *old* (saved) group name as *new*.
+ Specifying "" for *new* will clear the group. For example
+ "--map-group foo=" will allow the gid to take effect for any path
+ that originally had a group of "foo", unless countermanded by a
+ subsequent "--map-group foo=..." specification. See DESCRIPTION
+ above for further information.
+
+\--map-uid *old*=*new*
+: for every path, restore the *old* (saved) uid as *new*, unless
+ countermanded by a subsequent "--map-uid *old*=..." option. Note
+ that the uid will only be relevant for paths with no user. See
+ DESCRIPTION above for further information.
+
+\--map-gid *old*=*new*
+: for every path, restore the *old* (saved) gid as *new*, unless
+ countermanded by a subsequent "--map-gid *old*=..." option. Note
+ that the gid will only be relevant for paths with no user. See
+ DESCRIPTION above for further information.
+
-v, \--verbose
: increase log output. Given once, prints every
directory as it is restored; given twice, prints every
file and directory.
-q, \--quiet
-: don't show the progress meter. Normally, is stderr is
- a tty, a progress display is printed that shows the
- total number of files restored.
+: suppress output, including the progress meter. Normally, if
+ stderr is a tty, a progress meter displays the total number of
+ files restored.
+
+# EXAMPLES
-# EXAMPLE
-
Create a simple test backup set:
$ bup index -u /etc
$ ls -l passwd
-rw-r--r-- 1 apenwarr apenwarr 1478 2010-09-08 03:06 passwd
+
+Restore etc to test (no trailing slash):
-Restore the whole directory (no trailing slash):
-
- $ bup restore -C test1 /mybackup/latest/etc
+ $ bup restore -C test /mybackup/latest/etc
Restoring: 3, done.
- $ find test1
- test1
- test1/etc
- test1/etc/passwd
- test1/etc/profile
+ $ find test
+ test
+ test/etc
+ test/etc/passwd
+ test/etc/profile
-Restore the whole directory (trailing slash):
+Restore the contents of etc to test (trailing slash):
+
+ $ bup restore -C test /mybackup/latest/etc/
+ Restoring: 2, done.
- $ bup restore -C test2 /mybackup/latest/etc/
+ $ find test
+ test
+ test/passwd
+ test/profile
+
+Restore the contents of etc and etc's metadata to test (trailing
+"/."):
+
+ $ bup restore -C test /mybackup/latest/etc/.
Restoring: 2, done.
- $ find test2
- test2
- test2/passwd
- test2/profile
+ # At this point test and etc's metadata will match.
+ $ find test
+ test
+ test/passwd
+ test/profile
Restore a tree without risk of unauthorized access:
# rmdir restore-tmp
+Restore a tree, remapping an old user and group to a new user and group:
+
+ # 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
+
+Restore a tree, remapping an old uid to a new uid. Note that the old
+user must be erased so that bup won't prefer it over the uid:
+
+ # 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
+
+An alternate way to do the same by quashing users/groups universally
+with `--numeric-ids`:
+
+ # bup restore -C dest --numeric-ids --map-uid 1000=1042 /x/latest/y
+ Restoring: 97, done.
# SEE ALSO
projects / bup.git / blobdiff