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 [-r *host*:[*path*]] [\--outdir=*outdir*] [\--exclude-rx *pattern*]
  12 [\--exclude-rx-from *filename*] [-v] [-q] \<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 As a special case, if _some/where_ names the "latest" symlink,
  52 e.g. `bup restore /foo/latest`, then bup will act exactly as if the
  53 save that "latest" points to had been specified, and restore that,
  54 rather than the "latest" symlink itself.
  55
  56 Whenever path metadata is available, `bup restore` will attempt to
  57 restore it.  When restoring ownership, bup implements tar/rsync-like
  58 semantics.  It will normally prefer user and group names to uids and
  59 gids when they're available, but it will not try to restore the user
  60 unless running as root, and it will fall back to the numeric uid or
  61 gid whenever the metadata contains a user or group name that doesn't
  62 exist on the current system.  The use of user and group names can be
  63 disabled via `--numeric-ids` (which can be important when restoring a
  64 chroot, for example), and as a special case, a uid or gid of 0 will
  65 never be remapped by name.  Additionally, some systems don't allow
  66 setting a uid/gid that doesn't correspond with a known user/group.  On
  67 those systems, bup will log an error for each relevant path.
  68
  69 The `--map-user`, `--map-group`, `--map-uid`, `--map-gid` options may
  70 be used to adjust the available ownership information before any of
  71 the rules above are applied, but note that due to those rules,
  72 `--map-uid` and `--map-gid` will have no effect whenever a path has a
  73 valid user or group.  In those cases, either `--numeric-ids` must be
  74 specified, or the user or group must be cleared by a suitable
  75 `--map-user foo=` or `--map-group foo=`.
  76
  77 Hardlinks will also be restored when possible, but at least currently,
  78 no links will be made to targets outside the restore tree, and if the
  79 restore tree spans a different arrangement of filesystems from the
  80 save tree, some hardlink sets may not be completely restored.
  81
  82 Also note that changing hardlink sets on disk between index and save
  83 may produce unexpected results.  With the current implementation, bup
  84 will attempt to recreate any given hardlink set as it existed at index
  85 time, even if all of the files in the set weren't still hardlinked
  86 (but were otherwise identical) at save time.
  87
  88 Note that during the restoration process, access to data within the
  89 restore tree may be more permissive than it was in the original
  90 source.  Unless security is irrelevant, you must restore to a private
  91 subdirectory, and then move the resulting tree to its final position.
  92 See the EXAMPLES section for a demonstration.
  93
  94 # OPTIONS
  95
  96 -r, \--remote=*host*:*path*
  97 :   restore the backup set from the given remote server.  If
  98     *path* is omitted, uses the default path on the remote
  99     server (you still need to include the ':').  The connection to the
 100     remote server is made with SSH.  If you'd like to specify which port, user
 101     or private key to use for the SSH connection, we recommend you use the
 102     `~/.ssh/config` file.
 103
 104 -C, \--outdir=*outdir*
 105 :   create and change to directory *outdir* before
 106     extracting the files.
 107
 108 \--numeric-ids
 109 :   restore numeric IDs (user, group, etc.) rather than names.
 110
 111 \--exclude-rx=*pattern*
 112 :   exclude any path matching *pattern*, which must be a Python
 113     regular expression (http://docs.python.org/library/re.html).  The
 114     pattern will be compared against the full path rooted at the top
 115     of the restore tree, without anchoring, so "x/y" will match
 116     "ox/yard" or "box/yards".  To exclude the contents of /tmp, but
 117     not the directory itself, use "^/tmp/.". (can be specified more
 118     than once)
 119
 120     Note that the root of the restore tree (which matches '^/') is the
 121     top of the archive tree being restored, and has nothing to do with
 122     the filesystem destination.  Given "restore ... /foo/latest/etc/",
 123     the pattern '^/passwd$' would match if a file named passwd had
 124     been saved as '/foo/latest/etc/passwd'.
 125
 126     Examples:
 127
 128       * '/foo$' - exclude any file named foo
 129       * '/foo/$' - exclude any directory named foo
 130       * '/foo/.' - exclude the content of any directory named foo
 131       * '^/tmp/.' - exclude root-level /tmp's content, but not /tmp itself
 132
 133 \--exclude-rx-from=*filename*
 134 :   read --exclude-rx patterns from *filename*, one pattern per-line
 135     (may be repeated).  Ignore completely empty lines.
 136
 137 \--sparse
 138 :   write output data sparsely when reasonable.  Currently, reasonable
 139     just means "at least whenever there are 512 or more consecutive
 140     zeroes".
 141
 142 \--map-user *old*=*new*
 143 :   for every path, restore the *old* (saved) user name as *new*.
 144     Specifying "" for *new* will clear the user.  For example
 145     "--map-user foo=" will allow the uid to take effect for any path
 146     that originally had a user of "foo", unless countermanded by a
 147     subsequent "--map-user foo=..." specification.  See DESCRIPTION
 148     above for further information.
 149
 150 \--map-group *old*=*new*
 151 :   for every path, restore the *old* (saved) group name as *new*.
 152     Specifying "" for *new* will clear the group.  For example
 153     "--map-group foo=" will allow the gid to take effect for any path
 154     that originally had a group of "foo", unless countermanded by a
 155     subsequent "--map-group foo=..." specification.  See DESCRIPTION
 156     above for further information.
 157
 158 \--map-uid *old*=*new*
 159 :   for every path, restore the *old* (saved) uid as *new*, unless
 160     countermanded by a subsequent "--map-uid *old*=..." option.  Note
 161     that the uid will only be relevant for paths with no user.  See
 162     DESCRIPTION above for further information.
 163
 164 \--map-gid *old*=*new*
 165 :   for every path, restore the *old* (saved) gid as *new*, unless
 166     countermanded by a subsequent "--map-gid *old*=..." option.  Note
 167     that the gid will only be relevant for paths with no user.  See
 168     DESCRIPTION above for further information.
 169
 170 -v, \--verbose
 171 :   increase log output.  Given once, prints every
 172     directory as it is restored; given twice, prints every
 173     file and directory.
 174
 175 -q, \--quiet
 176 :   suppress output, including the progress meter.  Normally, if
 177     stderr is a tty, a progress meter displays the total number of
 178     files restored.
 179
 180 # EXAMPLES
 181
 182 Create a simple test backup set:
 183
 184     $ bup index -u /etc
 185     $ bup save -n mybackup /etc/passwd /etc/profile
 186
 187 Restore just one file:
 188
 189     $ bup restore /mybackup/latest/etc/passwd
 190     Restoring: 1, done.
 191
 192     $ ls -l passwd
 193     -rw-r--r-- 1 apenwarr apenwarr 1478 2010-09-08 03:06 passwd
 194
 195 Restore etc to test (no trailing slash):
 196
 197     $ bup restore -C test /mybackup/latest/etc
 198     Restoring: 3, done.
 199
 200     $ find test
 201     test
 202     test/etc
 203     test/etc/passwd
 204     test/etc/profile
 205
 206 Restore the contents of etc to test (trailing slash):
 207
 208     $ bup restore -C test /mybackup/latest/etc/
 209     Restoring: 2, done.
 210
 211     $ find test
 212     test
 213     test/passwd
 214     test/profile
 215
 216 Restore the contents of etc and etc's metadata to test (trailing
 217 "/."):
 218
 219     $ bup restore -C test /mybackup/latest/etc/.
 220     Restoring: 2, done.
 221
 222     # At this point test and etc's metadata will match.
 223     $ find test
 224     test
 225     test/passwd
 226     test/profile
 227
 228 Restore a tree without risk of unauthorized access:
 229
 230     # mkdir --mode 0700 restore-tmp
 231
 232     # bup restore -C restore-tmp /somebackup/latest/foo
 233     Restoring: 42, done.
 234
 235     # mv restore-tmp/foo somewhere
 236
 237     # rmdir restore-tmp
 238
 239 Restore a tree, remapping an old user and group to a new user and group:
 240
 241     # ls -l /original/y
 242     -rw-r----- 1 foo baz  3610 Nov  4 11:31 y
 243     # bup restore -C dest --map-user foo=bar --map-group baz=bax /x/latest/y
 244     Restoring: 42, done.
 245     # ls -l dest/y
 246     -rw-r----- 1 bar bax  3610 Nov  4 11:31 y
 247
 248 Restore a tree, remapping an old uid to a new uid.  Note that the old
 249 user must be erased so that bup won't prefer it over the uid:
 250
 251     # ls -l /original/y
 252     -rw-r----- 1 foo baz  3610 Nov  4 11:31 y
 253     # ls -ln /original/y
 254     -rw-r----- 1 1000 1007  3610 Nov  4 11:31 y
 255     # bup restore -C dest --map-user foo= --map-uid 1000=1042 /x/latest/y
 256     Restoring: 97, done.
 257     # ls -ln dest/y
 258     -rw-r----- 1 1042 1007  3610 Nov  4 11:31 y
 259
 260 An alternate way to do the same by quashing users/groups universally
 261 with `--numeric-ids`:
 262
 263     # bup restore -C dest --numeric-ids --map-uid 1000=1042 /x/latest/y
 264     Restoring: 97, done.
 265
 266 # SEE ALSO
 267
 268 `bup-save`(1), `bup-ftp`(1), `bup-fuse`(1), `bup-web`(1)
 269
 270 # BUP
 271
 272 Part of the `bup`(1) suite.