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 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 -r, \--remote=*host*:*path*
  92 :   restore the backup set from the given remote server.  If
  93     *path* is omitted, uses the default path on the remote
  94     server (you still need to include the ':').  The connection to the
  95     remote server is made with SSH.  If you'd like to specify which port, user
  96     or private key to use for the SSH connection, we recommend you use the
  97     `~/.ssh/config` file.
  98
  99 -C, \--outdir=*outdir*
 100 :   create and change to directory *outdir* before
 101     extracting the files.
 102
 103 \--numeric-ids
 104 :   restore numeric IDs (user, group, etc.) rather than names.
 105
 106 \--exclude-rx=*pattern*
 107 :   exclude any path matching *pattern*, which must be a Python
 108     regular expression (http://docs.python.org/library/re.html).  The
 109     pattern will be compared against the full path rooted at the top
 110     of the restore tree, without anchoring, so "x/y" will match
 111     "ox/yard" or "box/yards".  To exclude the contents of /tmp, but
 112     not the directory itself, use "^/tmp/.". (can be specified more
 113     than once)
 114
 115     Note that the root of the restore tree (which matches '^/') is the
 116     top of the archive tree being restored, and has nothing to do with
 117     the filesystem destination.  Given "restore ... /foo/latest/etc/",
 118     the pattern '^/passwd$' would match if a file named passwd had
 119     been saved as '/foo/latest/etc/passwd'.
 120
 121     Examples:
 122
 123       * '/foo$' - exclude any file named foo
 124       * '/foo/$' - exclude any directory named foo
 125       * '/foo/.' - exclude the content of any directory named foo
 126       * '^/tmp/.' - exclude root-level /tmp's content, but not /tmp itself
 127
 128 \--exclude-rx-from=*filename*
 129 :   read --exclude-rx patterns from *filename*, one pattern per-line
 130     (may be repeated).  Ignore completely empty lines.
 131
 132 \--sparse
 133 :   write output data sparsely when reasonable.  Currently, reasonable
 134     just means "at least whenever there are 512 or more consecutive
 135     zeroes".
 136
 137 \--map-user *old*=*new*
 138 :   for every path, restore the *old* (saved) user name as *new*.
 139     Specifying "" for *new* will clear the user.  For example
 140     "--map-user foo=" will allow the uid to take effect for any path
 141     that originally had a user of "foo", unless countermanded by a
 142     subsequent "--map-user foo=..." specification.  See DESCRIPTION
 143     above for further information.
 144
 145 \--map-group *old*=*new*
 146 :   for every path, restore the *old* (saved) group name as *new*.
 147     Specifying "" for *new* will clear the group.  For example
 148     "--map-group foo=" will allow the gid to take effect for any path
 149     that originally had a group of "foo", unless countermanded by a
 150     subsequent "--map-group foo=..." specification.  See DESCRIPTION
 151     above for further information.
 152
 153 \--map-uid *old*=*new*
 154 :   for every path, restore the *old* (saved) uid as *new*, unless
 155     countermanded by a subsequent "--map-uid *old*=..." option.  Note
 156     that the uid will only be relevant for paths with no user.  See
 157     DESCRIPTION above for further information.
 158
 159 \--map-gid *old*=*new*
 160 :   for every path, restore the *old* (saved) gid as *new*, unless
 161     countermanded by a subsequent "--map-gid *old*=..." option.  Note
 162     that the gid will only be relevant for paths with no user.  See
 163     DESCRIPTION above for further information.
 164
 165 -v, \--verbose
 166 :   increase log output.  Given once, prints every
 167     directory as it is restored; given twice, prints every
 168     file and directory.
 169
 170 -q, \--quiet
 171 :   suppress output, including the progress meter.  Normally, if
 172     stderr is a tty, a progress meter displays the total number of
 173     files restored.
 174
 175 # EXAMPLES
 176
 177 Create a simple test backup set:
 178
 179     $ bup index -u /etc
 180     $ bup save -n mybackup /etc/passwd /etc/profile
 181
 182 Restore just one file:
 183
 184     $ bup restore /mybackup/latest/etc/passwd
 185     Restoring: 1, done.
 186
 187     $ ls -l passwd
 188     -rw-r--r-- 1 apenwarr apenwarr 1478 2010-09-08 03:06 passwd
 189
 190 Restore etc to test (no trailing slash):
 191
 192     $ bup restore -C test /mybackup/latest/etc
 193     Restoring: 3, done.
 194
 195     $ find test
 196     test
 197     test/etc
 198     test/etc/passwd
 199     test/etc/profile
 200
 201 Restore the contents of etc to test (trailing slash):
 202
 203     $ bup restore -C test /mybackup/latest/etc/
 204     Restoring: 2, done.
 205
 206     $ find test
 207     test
 208     test/passwd
 209     test/profile
 210
 211 Restore the contents of etc and etc's metadata to test (trailing
 212 "/."):
 213
 214     $ bup restore -C test /mybackup/latest/etc/.
 215     Restoring: 2, done.
 216
 217     # At this point test and etc's metadata will match.
 218     $ find test
 219     test
 220     test/passwd
 221     test/profile
 222
 223 Restore a tree without risk of unauthorized access:
 224
 225     # mkdir --mode 0700 restore-tmp
 226
 227     # bup restore -C restore-tmp /somebackup/latest/foo
 228     Restoring: 42, done.
 229
 230     # mv restore-tmp/foo somewhere
 231
 232     # rmdir restore-tmp
 233
 234 Restore a tree, remapping an old user and group to a new user and group:
 235
 236     # ls -l /original/y
 237     -rw-r----- 1 foo baz  3610 Nov  4 11:31 y
 238     # bup restore -C dest --map-user foo=bar --map-group baz=bax /x/latest/y
 239     Restoring: 42, done.
 240     # ls -l dest/y
 241     -rw-r----- 1 bar bax  3610 Nov  4 11:31 y
 242
 243 Restore a tree, remapping an old uid to a new uid.  Note that the old
 244 user must be erased so that bup won't prefer it over the uid:
 245
 246     # ls -l /original/y
 247     -rw-r----- 1 foo baz  3610 Nov  4 11:31 y
 248     # ls -ln /original/y
 249     -rw-r----- 1 1000 1007  3610 Nov  4 11:31 y
 250     # bup restore -C dest --map-user foo= --map-uid 1000=1042 /x/latest/y
 251     Restoring: 97, done.
 252     # ls -ln dest/y
 253     -rw-r----- 1 1042 1007  3610 Nov  4 11:31 y
 254
 255 An alternate way to do the same by quashing users/groups universally
 256 with `--numeric-ids`:
 257
 258     # bup restore -C dest --numeric-ids --map-uid 1000=1042 /x/latest/y
 259     Restoring: 97, done.
 260
 261 # SEE ALSO
 262
 263 `bup-save`(1), `bup-ftp`(1), `bup-fuse`(1), `bup-web`(1)
 264
 265 # BUP
 266
 267 Part of the `bup`(1) suite.