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