X-Git-Url: https://arthur.barton.de/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=Documentation%2Fbup-restore.md;h=700f3d467dd0bb365b911bc460da51401531ab71;hb=5b04ce607e9a54f7a75ba15ad997681c2cfc8f12;hp=e362cdac433f91b8c7203060747a66c4a2adae23;hpb=7ccf0a9f15b5fc4bc0e257cda7658b72bd04b8a1;p=bup.git diff --git a/Documentation/bup-restore.md b/Documentation/bup-restore.md index e362cda..700f3d4 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] \; +bup restore [\--outdir=*outdir*] [\--exclude-rx *pattern*] +[\--exclude-rx-from *filename*] [-v] [-q] \ # DESCRIPTION @@ -16,7 +17,7 @@ bup restore [\--outdir=*outdir*] [-v] [-q] \; 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 @@ -29,31 +30,44 @@ revision 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. 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 @@ -81,18 +95,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 @@ -105,27 +178,39 @@ Restore just one file: $ 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: @@ -138,6 +223,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