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*] [-v] [-q] \<paths...\>;
  12
  13 # DESCRIPTION
  14
  15 `bup restore` extracts files from a backup set (created
  16 with `bup-save`(1)) to the local filesystem.
  17
  18 The specified *paths* are of the form
  19 /_branch_/_revision_/_some/where_.  The components of the
  20 path are as follows:
  21
  22 branch
  23 :   the name of the backup set to restore from; this
  24     corresponds to the `--name` (`-n`) option to `bup save`.
  25
  26 revision
  27 :   the revision of the backup set to restore.  The
  28     revision *latest* is always the most recent
  29     backup on the given branch.  You can discover other
  30     revisions using `bup ls /branch`.
  31
  32 some/where
  33 :   the previously saved path (after any stripping/grafting) that you
  34     want to restore.  For example, `etc/passwd`.
  35
  36 If _some/where_ names a directory, `bup restore` will restore that
  37 directory and then recursively restore its contents.
  38
  39 If _some/where_ names a directory and ends with a slash (ie.
  40 path/to/dir/), `bup restore` will restore the children of that
  41 directory directly to the current directory (or the `--outdir`).  If
  42 _some/where_ does not end in a slash, the children will be restored to
  43 a subdirectory of the current directory.
  44
  45 If _some/where_ names a directory and ends in '/.' (ie.
  46 path/to/dir/.), `bup restore` will do exactly what it would have done
  47 for path/to/dir, and then restore _dir_'s metadata to the current
  48 directory (or the `--outdir`).  See the EXAMPLES section.
  49
  50 Whenever path metadata is available, `bup restore` will attempt to
  51 restore it.  When restoring ownership, bup implements tar/rsync-like
  52 semantics.  It will not try to restore the user unless running as
  53 root, and it will fall back to the numeric uid or gid whenever the
  54 metadata contains a user or group name that doesn't exist on the
  55 current system.  The use of user and group names can be disabled via
  56 `--numeric-ids` (which can be important when restoring a chroot, for
  57 example), and as a special case, a uid or gid of 0 will never be
  58 remapped by name.
  59
  60 Hardlinks will also be restored when possible, but at least currently,
  61 no links will be made to targets outside the restore tree, and if the
  62 restore tree spans a different arrangement of filesystems from the
  63 save tree, some hardlink sets may not be completely restored.
  64
  65 Also note that changing hardlink sets on disk between index and save
  66 may produce unexpected results.  With the current implementation, bup
  67 will attempt to recreate any given hardlink set as it existed at index
  68 time, even if all of the files in the set weren't still hardlinked
  69 (but were otherwise identical) at save time.
  70
  71 Note that during the restoration process, access to data within the
  72 restore tree may be more permissive than it was in the original
  73 source.  Unless security is irrelevant, you must restore to a private
  74 subdirectory, and then move the resulting tree to its final position.
  75 See the EXAMPLES section for a demonstration.
  76
  77 # OPTIONS
  78
  79 -C, \--outdir=*outdir*
  80 :   create and change to directory *outdir* before
  81     extracting the files.
  82
  83 \--numeric-ids
  84 :   restore numeric IDs (user, group, etc.) rather than names.
  85
  86 -v, \--verbose
  87 :   increase log output.  Given once, prints every
  88     directory as it is restored; given twice, prints every
  89     file and directory.
  90
  91 -q, \--quiet
  92 :   don't show the progress meter.  Normally, is stderr is
  93     a tty, a progress display is printed that shows the
  94     total number of files restored.
  95
  96 # EXAMPLE
  97
  98 Create a simple test backup set:
  99
 100     $ bup index -u /etc
 101     $ bup save -n mybackup /etc/passwd /etc/profile
 102
 103 Restore just one file:
 104
 105     $ bup restore /mybackup/latest/etc/passwd
 106     Restoring: 1, done.
 107
 108     $ ls -l passwd
 109     -rw-r--r-- 1 apenwarr apenwarr 1478 2010-09-08 03:06 passwd
 110
 111 Restore etc to test (no trailing slash):
 112
 113     $ bup restore -C test /mybackup/latest/etc
 114     Restoring: 3, done.
 115
 116     $ find test
 117     test
 118     test/etc
 119     test/etc/passwd
 120     test/etc/profile
 121
 122 Restore the contents of etc to test (trailing slash):
 123
 124     $ bup restore -C test /mybackup/latest/etc/
 125     Restoring: 2, done.
 126
 127     $ find test
 128     test
 129     test/passwd
 130     test/profile
 131
 132 Restore the contents of etc and etc's metadata to test (trailing
 133 "/."):
 134
 135     $ bup restore -C test /mybackup/latest/etc/.
 136     Restoring: 2, done.
 137
 138     # At this point test and etc's metadata will match.
 139     $ find test
 140     test
 141     test/passwd
 142     test/profile
 143
 144 Restore a tree without risk of unauthorized access:
 145
 146     # mkdir --mode 0700 restore-tmp
 147
 148     # bup restore -C restore-tmp /somebackup/latest/foo
 149     Restoring: 42, done.
 150
 151     # mv restore-tmp/foo somewhere
 152
 153     # rmdir restore-tmp
 154
 155
 156 # SEE ALSO
 157
 158 `bup-save`(1), `bup-ftp`(1), `bup-fuse`(1), `bup-web`(1)
 159
 160 # BUP
 161
 162 Part of the `bup`(1) suite.