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 Note that during the restoration process, access to data within the
  59 restore tree may be more permissive than it was in the original
  60 source.  Unless security is irrelevant, you must restore to a private
  61 subdirectory, and then move the resulting tree to its final position.
  62 See the EXAMPLES section for a demonstration.
  63
  64 # OPTIONS
  65
  66 -C, \--outdir=*outdir*
  67 :   create and change to directory *outdir* before
  68     extracting the files.
  69
  70 \--numeric-ids
  71 :   restore numeric IDs (user, group, etc.) rather than names.
  72
  73 -v, \--verbose
  74 :   increase log output.  Given once, prints every
  75     directory as it is restored; given twice, prints every
  76     file and directory.
  77
  78 -q, \--quiet
  79 :   don't show the progress meter.  Normally, is stderr is
  80     a tty, a progress display is printed that shows the
  81     total number of files restored.
  82
  83 # EXAMPLE
  84
  85 Create a simple test backup set:
  86
  87     $ bup index -u /etc
  88     $ bup save -n mybackup /etc/passwd /etc/profile
  89
  90 Restore just one file:
  91
  92     $ bup restore /mybackup/latest/etc/passwd
  93     Restoring: 1, done.
  94
  95     $ ls -l passwd
  96     -rw-r--r-- 1 apenwarr apenwarr 1478 2010-09-08 03:06 passwd
  97
  98 Restore the whole directory (no trailing slash):
  99
 100     $ bup restore -C test1 /mybackup/latest/etc
 101     Restoring: 3, done.
 102
 103     $ find test1
 104     test1
 105     test1/etc
 106     test1/etc/passwd
 107     test1/etc/profile
 108
 109 Restore the whole directory (trailing slash):
 110
 111     $ bup restore -C test2 /mybackup/latest/etc/
 112     Restoring: 2, done.
 113
 114     $ find test2
 115     test2
 116     test2/passwd
 117     test2/profile
 118
 119 Restore a tree without risk of unauthorized access:
 120
 121     # mkdir --mode 0700 restore-tmp
 122
 123     # bup restore -C restore-tmp /somebackup/latest/foo
 124     Restoring: 42, done.
 125
 126     # mv restore-tmp/foo somewhere
 127
 128     # rmdir restore-tmp
 129
 130
 131 # SEE ALSO
 132
 133 `bup-save`(1), `bup-ftp`(1), `bup-fuse`(1), `bup-web`(1)
 134
 135 # BUP
 136
 137 Part of the `bup`(1) suite.