X-Git-Url: https://arthur.barton.de/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=Documentation%2Fbup-restore.md;h=a7c246eacb08491a1a0b0a35df28363d345c125a;hb=HEAD;hp=986240744fd4771c429ecffdc19eb066e1d92008;hpb=7e9005e3166906090decc973d4950bf790128f4b;p=bup.git

diff --git a/Documentation/bup-restore.md b/Documentation/bup-restore.md
index 9862407..a7c246e 100644
--- a/Documentation/bup-restore.md
+++ b/Documentation/bup-restore.md
@@ -8,7 +8,8 @@ bup-restore - extract files from a backup set
 
 # 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
 
@@ -47,15 +48,31 @@ 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
@@ -76,6 +93,14 @@ See the EXAMPLES section for a demonstration.
 
 # 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.
@@ -83,18 +108,77 @@ See the EXAMPLES section for a demonstration.
 \--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
@@ -152,6 +236,32 @@ 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