Documentation/bup-restore.md

   1 % bup-restore(1) Bup %BUP_VERSION%
   2 % Avery Pennarun <apenwarr@gmail.com>
   3 % %BUP_DATE%
   4
   5 # NAME
   6
   7 bup-restore - extract files from a backup set
   8
   9 # SYNOPSIS
  10
  11 bup restore [\--outdir=*outdir*] [\--exclude-rx *pattern*] [-v] [-q]
  12 \<paths...\>
  13
  14 # DESCRIPTION
  15
  16 `bup restore` extracts files from a backup set (created
  17 with `bup-save`(1)) to the local filesystem.
  18
  19 The specified *paths* are of the form
  20 /_branch_/_revision_/_some/where_.  The components of the
  21 path are as follows:
  22
  23 branch
  24 :   the name of the backup set to restore from; this
  25     corresponds to the `--name` (`-n`) option to `bup save`.
  26
  27 revision
  28 :   the revision of the backup set to restore.  The
  29     revision *latest* is always the most recent
  30     backup on the given branch.  You can discover other
  31     revisions using `bup ls /branch`.
  32
  33 some/where
  34 :   the previously saved path (after any stripping/grafting) that you
  35     want to restore.  For example, `etc/passwd`.
  36
  37 If _some/where_ names a directory, `bup restore` will restore that
  38 directory and then recursively restore its contents.
  39
  40 If _some/where_ names a directory and ends with a slash (ie.
  41 path/to/dir/), `bup restore` will restore the children of that
  42 directory directly to the current directory (or the `--outdir`).  If
  43 _some/where_ does not end in a slash, the children will be restored to
  44 a subdirectory of the current directory.
  45
  46 If _some/where_ names a directory and ends in '/.' (ie.
  47 path/to/dir/.), `bup restore` will do exactly what it would have done
  48 for path/to/dir, and then restore _dir_'s metadata to the current
  49 directory (or the `--outdir`).  See the EXAMPLES section.
  50
  51 Whenever path metadata is available, `bup restore` will attempt to
  52 restore it.  When restoring ownership, bup implements tar/rsync-like
  53 semantics.  It will normally prefer user and group names to uids and
  54 gids when they're available, but it will not try to restore the user
  55 unless running as root, and it will fall back to the numeric uid or
  56 gid whenever the metadata contains a user or group name that doesn't
  57 exist on the current system.  The use of user and group names can be
  58 disabled via `--numeric-ids` (which can be important when restoring a
  59 chroot, for example), and as a special case, a uid or gid of 0 will
  60 never be remapped by name.  Additionally, some systems don't allow
  61 setting a uid/gid that doesn't correspond with a known user/group.  On
  62 those systems, bup will log an error for each relevant path.
  63
  64 The `--map-user`, `--map-group`, `--map-uid`, `--map-gid` options may
  65 be used to adjust the available ownership information before any of
  66 the rules above are applied, but note that due to those rules,
  67 `--map-uid` and `--map-gid` will have no effect whenever a path has a
  68 valid user or group.  In those cases, either `--numeric-ids` must be
  69 specified, or the user or group must be cleared by a suitable
  70 `--map-user foo=` or `--map-group foo=`.
  71
  72 Hardlinks will also be restored when possible, but at least currently,
  73 no links will be made to targets outside the restore tree, and if the
  74 restore tree spans a different arrangement of filesystems from the
  75 save tree, some hardlink sets may not be completely restored.
  76
  77 Also note that changing hardlink sets on disk between index and save
  78 may produce unexpected results.  With the current implementation, bup
  79 will attempt to recreate any given hardlink set as it existed at index
  80 time, even if all of the files in the set weren't still hardlinked
  81 (but were otherwise identical) at save time.
  82
  83 Note that during the restoration process, access to data within the
  84 restore tree may be more permissive than it was in the original
  85 source.  Unless security is irrelevant, you must restore to a private
  86 subdirectory, and then move the resulting tree to its final position.
  87 See the EXAMPLES section for a demonstration.
  88
  89 # OPTIONS
  90
  91 -C, \--outdir=*outdir*
  92 :   create and change to directory *outdir* before
  93     extracting the files.
  94
  95 \--numeric-ids
  96 :   restore numeric IDs (user, group, etc.) rather than names.
  97
  98 \--exclude-rx=*pattern*
  99 :   exclude any path matching *pattern*, which must be a Python
 100     regular expression (http://docs.python.org/library/re.html).  The
 101     pattern will be compared against the full path rooted at the top
 102     of the restore tree, without anchoring, so "x/y" will match
 103     "ox/yard" or "box/yards".  To exclude the contents of /tmp, but
 104     not the directory itself, use "^/tmp/.". (can be specified more
 105     than once)
 106
 107     Note that the root of the restore tree (which matches '^/') is the
 108     top of the archive tree being restored, and has nothing to do with
 109     the filesystem destination.  Given "restore ... /foo/latest/etc/",
 110     the pattern '^/passwd$' would match if a file named passwd had
 111     been saved as '/foo/latest/etc/passwd'.
 112
 113     Examples:
 114
 115       * '/foo$' - exclude any file named foo
 116       * '/foo/$' - exclude any directory named foo
 117       * '/foo/.' - exclude the content of any directory named foo
 118       * '^/tmp/.' - exclude root-level /tmp's content, but not /tmp itself
 119
 120 \--map-user *old*=*new*
 121 :   restore *old* user as *new* user.  Specifying "" for *new* will
 122     clear the user, i.e. `--map-user foo=`.
 123
 124 \--map-group *old*=*new*
 125 :   restore *old* group as *new* group.  Specifying "" for *new* will
 126     clear the group, i.e. `--map-user foo=`.
 127
 128 \--map-uid *old*=*new*
 129 :   restore *old* uid as *new* uid.
 130
 131 \--map-gid *old*=*new*
 132 :   restore *old* gid as *new* gid.
 133
 134 -v, \--verbose
 135 :   increase log output.  Given once, prints every
 136     directory as it is restored; given twice, prints every
 137     file and directory.
 138
 139 -q, \--quiet
 140 :   don't show the progress meter.  Normally, is stderr is
 141     a tty, a progress display is printed that shows the
 142     total number of files restored.
 143
 144 # EXAMPLE
 145
 146 Create a simple test backup set:
 147
 148     $ bup index -u /etc
 149     $ bup save -n mybackup /etc/passwd /etc/profile
 150
 151 Restore just one file:
 152
 153     $ bup restore /mybackup/latest/etc/passwd
 154     Restoring: 1, done.
 155
 156     $ ls -l passwd
 157     -rw-r--r-- 1 apenwarr apenwarr 1478 2010-09-08 03:06 passwd
 158
 159 Restore etc to test (no trailing slash):
 160
 161     $ bup restore -C test /mybackup/latest/etc
 162     Restoring: 3, done.
 163
 164     $ find test
 165     test
 166     test/etc
 167     test/etc/passwd
 168     test/etc/profile
 169
 170 Restore the contents of etc to test (trailing slash):
 171
 172     $ bup restore -C test /mybackup/latest/etc/
 173     Restoring: 2, done.
 174
 175     $ find test
 176     test
 177     test/passwd
 178     test/profile
 179
 180 Restore the contents of etc and etc's metadata to test (trailing
 181 "/."):
 182
 183     $ bup restore -C test /mybackup/latest/etc/.
 184     Restoring: 2, done.
 185
 186     # At this point test and etc's metadata will match.
 187     $ find test
 188     test
 189     test/passwd
 190     test/profile
 191
 192 Restore a tree without risk of unauthorized access:
 193
 194     # mkdir --mode 0700 restore-tmp
 195
 196     # bup restore -C restore-tmp /somebackup/latest/foo
 197     Restoring: 42, done.
 198
 199     # mv restore-tmp/foo somewhere
 200
 201     # rmdir restore-tmp
 202
 203 Restore a tree, remapping an old user and group to a new user and group:
 204
 205     # bup restore -C dest --map-user foo=bar --map-group baz=bax /x/latest/y
 206     Restoring: 42, done.
 207
 208 Restore a tree, remapping an old uid to a new uid.  Note that the old
 209 user must be erased so that bup won't prefer it over the uid:
 210
 211     # bup restore -C dest --map-user foo= --map-uid 1000=1042 /x/latest/y
 212     Restoring: 97, done.
 213
 214 An alternate way to do the same by quashing users/groups universally
 215 with `--numeric-ids`:
 216
 217     # bup restore -C dest --numeric-ids --map-uid 1000=1042 /x/latest/y
 218     Restoring: 97, done.
 219
 220 # SEE ALSO
 221
 222 `bup-save`(1), `bup-ftp`(1), `bup-fuse`(1), `bup-web`(1)
 223
 224 # BUP
 225
 226 Part of the `bup`(1) suite.