Store metadata in the index, in bupindex.meta; only store unique values.

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

diff --git a/Documentation/bup-restore.md b/Documentation/bup-restore.md
index f5a2ad4050c9b9001c78962824057f540772f6f9..e362cdac433f91b8c7203060747a66c4a2adae23 100644 (file)
--- a/Documentation/bup-restore.md
+++ b/Documentation/bup-restore.md
@@ -45,6 +45,32 @@ 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.
+
+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.
+
+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't still hardlinked
+(but were otherwise identical) at save time.
+
+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 +78,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 +126,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