Update base_version to 0.34~ for 0.34 development

[bup.git] / Documentation / bup-restore.md

diff --git a/Documentation/bup-restore.md b/Documentation/bup-restore.md
index ab98c00b9e402d054f3096efa9c895cad7a796f2..a7c246eacb08491a1a0b0a35df28363d345c125a 100644 (file)
--- a/Documentation/bup-restore.md
+++ b/Documentation/bup-restore.md
@@ -8,8 +8,8 @@ bup-restore - extract files from a backup set
 
 # SYNOPSIS
 
 
 # SYNOPSIS
 

-bup restore [\--outdir=*outdir*] [\--exclude-rx *pattern*] [-v] [-q]
-\<paths...\>
+bup restore [-r *host*:[*path*]] [\--outdir=*outdir*] [\--exclude-rx *pattern*]
+[\--exclude-rx-from *filename*] [-v] [-q] \<paths...\>

 
 # DESCRIPTION
 
 
 # DESCRIPTION
 


@@ -48,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.
 
 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
 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
 
 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


@@ -77,6 +93,14 @@ See the EXAMPLES section for a demonstration.
 
 # OPTIONS
 
 
 # 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.
 -C, \--outdir=*outdir*
 :   create and change to directory *outdir* before
     extracting the files.


@@ -106,18 +130,55 @@ See the EXAMPLES section for a demonstration.
       * '/foo/.' - exclude the content of any directory named foo
       * '^/tmp/.' - exclude root-level /tmp's content, but not /tmp itself
 
       * '/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
 -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
 Create a simple test backup set:
     
     $ bup index -u /etc


@@ -175,6 +236,32 @@ Restore a tree without risk of unauthorized access:
 
     # rmdir restore-tmp
     
 
     # 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
 
 
 # SEE ALSO