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 not try to restore the user unless running as
  54 root, and it will fall back to the numeric uid or gid whenever the
  55 metadata contains a user or group name that doesn't exist on the
  56 current system.  The use of user and group names can be disabled via
  57 `--numeric-ids` (which can be important when restoring a chroot, for
  58 example), and as a special case, a uid or gid of 0 will never be
  59 remapped by name.  Additionally, some systems don't allow setting a
  60 uid/gid that doesn't correspond with a known user/group.  On those
  61 systems, bup will log an error for each relevant path.
  62
  63 Hardlinks will also be restored when possible, but at least currently,
  64 no links will be made to targets outside the restore tree, and if the
  65 restore tree spans a different arrangement of filesystems from the
  66 save tree, some hardlink sets may not be completely restored.
  67
  68 Also note that changing hardlink sets on disk between index and save
  69 may produce unexpected results.  With the current implementation, bup
  70 will attempt to recreate any given hardlink set as it existed at index
  71 time, even if all of the files in the set weren't still hardlinked
  72 (but were otherwise identical) at save time.
  73
  74 Note that during the restoration process, access to data within the
  75 restore tree may be more permissive than it was in the original
  76 source.  Unless security is irrelevant, you must restore to a private
  77 subdirectory, and then move the resulting tree to its final position.
  78 See the EXAMPLES section for a demonstration.
  79
  80 # OPTIONS
  81
  82 -C, \--outdir=*outdir*
  83 :   create and change to directory *outdir* before
  84     extracting the files.
  85
  86 \--numeric-ids
  87 :   restore numeric IDs (user, group, etc.) rather than names.
  88
  89 \--exclude-rx=*pattern*
  90 :   exclude any path matching *pattern*, which must be a Python
  91     regular expression (http://docs.python.org/library/re.html).  The
  92     pattern will be compared against the full path rooted at the top
  93     of the restore tree, without anchoring, so "x/y" will match
  94     "ox/yard" or "box/yards".  To exclude the contents of /tmp, but
  95     not the directory itself, use "^/tmp/.". (can be specified more
  96     than once)
  97
  98     Note that the root of the restore tree (which matches '^/') is the
  99     top of the archive tree being restored, and has nothing to do with
 100     the filesystem destination.  Given "restore ... /foo/latest/etc/",
 101     the pattern '^/passwd$' would match if a file named passwd had
 102     been saved as '/foo/latest/etc/passwd'.
 103
 104     Examples:
 105
 106       * '/foo$' - exclude any file named foo
 107       * '/foo/$' - exclude any directory named foo
 108       * '/foo/.' - exclude the content of any directory named foo
 109       * '^/tmp/.' - exclude root-level /tmp's content, but not /tmp itself
 110
 111 -v, \--verbose
 112 :   increase log output.  Given once, prints every
 113     directory as it is restored; given twice, prints every
 114     file and directory.
 115
 116 -q, \--quiet
 117 :   don't show the progress meter.  Normally, is stderr is
 118     a tty, a progress display is printed that shows the
 119     total number of files restored.
 120
 121 # EXAMPLE
 122
 123 Create a simple test backup set:
 124
 125     $ bup index -u /etc
 126     $ bup save -n mybackup /etc/passwd /etc/profile
 127
 128 Restore just one file:
 129
 130     $ bup restore /mybackup/latest/etc/passwd
 131     Restoring: 1, done.
 132
 133     $ ls -l passwd
 134     -rw-r--r-- 1 apenwarr apenwarr 1478 2010-09-08 03:06 passwd
 135
 136 Restore etc to test (no trailing slash):
 137
 138     $ bup restore -C test /mybackup/latest/etc
 139     Restoring: 3, done.
 140
 141     $ find test
 142     test
 143     test/etc
 144     test/etc/passwd
 145     test/etc/profile
 146
 147 Restore the contents of etc to test (trailing slash):
 148
 149     $ bup restore -C test /mybackup/latest/etc/
 150     Restoring: 2, done.
 151
 152     $ find test
 153     test
 154     test/passwd
 155     test/profile
 156
 157 Restore the contents of etc and etc's metadata to test (trailing
 158 "/."):
 159
 160     $ bup restore -C test /mybackup/latest/etc/.
 161     Restoring: 2, done.
 162
 163     # At this point test and etc's metadata will match.
 164     $ find test
 165     test
 166     test/passwd
 167     test/profile
 168
 169 Restore a tree without risk of unauthorized access:
 170
 171     # mkdir --mode 0700 restore-tmp
 172
 173     # bup restore -C restore-tmp /somebackup/latest/foo
 174     Restoring: 42, done.
 175
 176     # mv restore-tmp/foo somewhere
 177
 178     # rmdir restore-tmp
 179
 180
 181 # SEE ALSO
 182
 183 `bup-save`(1), `bup-ftp`(1), `bup-fuse`(1), `bup-web`(1)
 184
 185 # BUP
 186
 187 Part of the `bup`(1) suite.