Restore any metadata during "bup restore"; add "bup meta --edit".

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

diff --git a/Documentation/bup-restore.md b/Documentation/bup-restore.md
index f5a2ad4050c9b9001c78962824057f540772f6f9..5085a67713ce894d2ff30ac21201a989bbe57a24 100644 (file)
--- a/Documentation/bup-restore.md
+++ b/Documentation/bup-restore.md
@@ -45,6 +45,21 @@ the children will be restored to a subdirectory of the
 current directory.  See the EXAMPLES section to see how
 this works.
 
+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.
+
+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.
 
 # OPTIONS
 
@@ -52,6 +67,9 @@ this works.
 :   create and change to directory *outdir* before
     extracting the files.
 
+\--numeric-ids
+:   restore numeric IDs (user, group, etc.) rather than names.
+
 -v, \--verbose
 :   increase log output.  Given once, prints every
     directory as it is restored; given twice, prints every
@@ -97,6 +115,17 @@ Restore the whole directory (trailing slash):
     test2
     test2/passwd
     test2/profile
+
+Restore a tree without risk of unauthorized access:
+
+    # mkdir --mode 0700 restore-tmp
+
+    # bup restore -C restore-tmp /somebackup/latest/foo
+    Restoring: 42, done.
+
+    # mv restore-tmp/foo somewhere
+
+    # rmdir restore-tmp
     
 
 # SEE ALSO