| 1 |
% bup-restore(1) Bup %BUP_VERSION% |
| 2 |
% Avery Pennarun <[email protected]> |
| 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 |
As a special case, if _some/where_ names the "latest" symlink, |
| 52 |
e.g. `bup restore /foo/latest`, then bup will act exactly as if the |
| 53 |
save that "latest" points to had been specified, and restore that, |
| 54 |
rather than the "latest" symlink itself. |
| 55 |
|
| 56 |
Whenever path metadata is available, `bup restore` will attempt to |
| 57 |
restore it. When restoring ownership, bup implements tar/rsync-like |
| 58 |
semantics. It will normally prefer user and group names to uids and |
| 59 |
gids when they're available, but it will not try to restore the user |
| 60 |
unless running as root, and it will fall back to the numeric uid or |
| 61 |
gid whenever the metadata contains a user or group name that doesn't |
| 62 |
exist on the current system. The use of user and group names can be |
| 63 |
disabled via `--numeric-ids` (which can be important when restoring a |
| 64 |
chroot, for example), and as a special case, a uid or gid of 0 will |
| 65 |
never be remapped by name. Additionally, some systems don't allow |
| 66 |
setting a uid/gid that doesn't correspond with a known user/group. On |
| 67 |
those systems, bup will log an error for each relevant path. |
| 68 |
|
| 69 |
The `--map-user`, `--map-group`, `--map-uid`, `--map-gid` options may |
| 70 |
be used to adjust the available ownership information before any of |
| 71 |
the rules above are applied, but note that due to those rules, |
| 72 |
`--map-uid` and `--map-gid` will have no effect whenever a path has a |
| 73 |
valid user or group. In those cases, either `--numeric-ids` must be |
| 74 |
specified, or the user or group must be cleared by a suitable |
| 75 |
`--map-user foo=` or `--map-group foo=`. |
| 76 |
|
| 77 |
Hardlinks will also be restored when possible, but at least currently, |
| 78 |
no links will be made to targets outside the restore tree, and if the |
| 79 |
restore tree spans a different arrangement of filesystems from the |
| 80 |
save tree, some hardlink sets may not be completely restored. |
| 81 |
|
| 82 |
Also note that changing hardlink sets on disk between index and save |
| 83 |
may produce unexpected results. With the current implementation, bup |
| 84 |
will attempt to recreate any given hardlink set as it existed at index |
| 85 |
time, even if all of the files in the set weren't still hardlinked |
| 86 |
(but were otherwise identical) at save time. |
| 87 |
|
| 88 |
Note that during the restoration process, access to data within the |
| 89 |
restore tree may be more permissive than it was in the original |
| 90 |
source. Unless security is irrelevant, you must restore to a private |
| 91 |
subdirectory, and then move the resulting tree to its final position. |
| 92 |
See the EXAMPLES section for a demonstration. |
| 93 |
|
| 94 |
# OPTIONS |
| 95 |
|
| 96 |
-r, \--remote=*host*:*path* |
| 97 |
: restore the backup set from the given remote server. If |
| 98 |
*path* is omitted, uses the default path on the remote |
| 99 |
server (you still need to include the ':'). The connection to the |
| 100 |
remote server is made with SSH. If you'd like to specify which port, user |
| 101 |
or private key to use for the SSH connection, we recommend you use the |
| 102 |
`~/.ssh/config` file. |
| 103 |
|
| 104 |
-C, \--outdir=*outdir* |
| 105 |
: create and change to directory *outdir* before |
| 106 |
extracting the files. |
| 107 |
|
| 108 |
\--numeric-ids |
| 109 |
: restore numeric IDs (user, group, etc.) rather than names. |
| 110 |
|
| 111 |
\--exclude-rx=*pattern* |
| 112 |
: exclude any path matching *pattern*, which must be a Python |
| 113 |
regular expression (http://docs.python.org/library/re.html). The |
| 114 |
pattern will be compared against the full path rooted at the top |
| 115 |
of the restore tree, without anchoring, so "x/y" will match |
| 116 |
"ox/yard" or "box/yards". To exclude the contents of /tmp, but |
| 117 |
not the directory itself, use "^/tmp/.". (can be specified more |
| 118 |
than once) |
| 119 |
|
| 120 |
Note that the root of the restore tree (which matches '^/') is the |
| 121 |
top of the archive tree being restored, and has nothing to do with |
| 122 |
the filesystem destination. Given "restore ... /foo/latest/etc/", |
| 123 |
the pattern '^/passwd$' would match if a file named passwd had |
| 124 |
been saved as '/foo/latest/etc/passwd'. |
| 125 |
|
| 126 |
Examples: |
| 127 |
|
| 128 |
* '/foo$' - exclude any file named foo |
| 129 |
* '/foo/$' - exclude any directory named foo |
| 130 |
* '/foo/.' - exclude the content of any directory named foo |
| 131 |
* '^/tmp/.' - exclude root-level /tmp's content, but not /tmp itself |
| 132 |
|
| 133 |
\--exclude-rx-from=*filename* |
| 134 |
: read --exclude-rx patterns from *filename*, one pattern per-line |
| 135 |
(may be repeated). Ignore completely empty lines. |
| 136 |
|
| 137 |
\--sparse |
| 138 |
: write output data sparsely when reasonable. Currently, reasonable |
| 139 |
just means "at least whenever there are 512 or more consecutive |
| 140 |
zeroes". |
| 141 |
|
| 142 |
\--map-user *old*=*new* |
| 143 |
: for every path, restore the *old* (saved) user name as *new*. |
| 144 |
Specifying "" for *new* will clear the user. For example |
| 145 |
"--map-user foo=" will allow the uid to take effect for any path |
| 146 |
that originally had a user of "foo", unless countermanded by a |
| 147 |
subsequent "--map-user foo=..." specification. See DESCRIPTION |
| 148 |
above for further information. |
| 149 |
|
| 150 |
\--map-group *old*=*new* |
| 151 |
: for every path, restore the *old* (saved) group name as *new*. |
| 152 |
Specifying "" for *new* will clear the group. For example |
| 153 |
"--map-group foo=" will allow the gid to take effect for any path |
| 154 |
that originally had a group of "foo", unless countermanded by a |
| 155 |
subsequent "--map-group foo=..." specification. See DESCRIPTION |
| 156 |
above for further information. |
| 157 |
|
| 158 |
\--map-uid *old*=*new* |
| 159 |
: for every path, restore the *old* (saved) uid as *new*, unless |
| 160 |
countermanded by a subsequent "--map-uid *old*=..." option. Note |
| 161 |
that the uid will only be relevant for paths with no user. See |
| 162 |
DESCRIPTION above for further information. |
| 163 |
|
| 164 |
\--map-gid *old*=*new* |
| 165 |
: for every path, restore the *old* (saved) gid as *new*, unless |
| 166 |
countermanded by a subsequent "--map-gid *old*=..." option. Note |
| 167 |
that the gid will only be relevant for paths with no user. See |
| 168 |
DESCRIPTION above for further information. |
| 169 |
|
| 170 |
-v, \--verbose |
| 171 |
: increase log output. Given once, prints every |
| 172 |
directory as it is restored; given twice, prints every |
| 173 |
file and directory. |
| 174 |
|
| 175 |
-q, \--quiet |
| 176 |
: suppress output, including the progress meter. Normally, if |
| 177 |
stderr is a tty, a progress meter displays the total number of |
| 178 |
files restored. |
| 179 |
|
| 180 |
# EXAMPLES |
| 181 |
|
| 182 |
Create a simple test backup set: |
| 183 |
|
| 184 |
$ bup index -u /etc |
| 185 |
$ bup save -n mybackup /etc/passwd /etc/profile |
| 186 |
|
| 187 |
Restore just one file: |
| 188 |
|
| 189 |
$ bup restore /mybackup/latest/etc/passwd |
| 190 |
Restoring: 1, done. |
| 191 |
|
| 192 |
$ ls -l passwd |
| 193 |
-rw-r--r-- 1 apenwarr apenwarr 1478 2010-09-08 03:06 passwd |
| 194 |
|
| 195 |
Restore etc to test (no trailing slash): |
| 196 |
|
| 197 |
$ bup restore -C test /mybackup/latest/etc |
| 198 |
Restoring: 3, done. |
| 199 |
|
| 200 |
$ find test |
| 201 |
test |
| 202 |
test/etc |
| 203 |
test/etc/passwd |
| 204 |
test/etc/profile |
| 205 |
|
| 206 |
Restore the contents of etc to test (trailing slash): |
| 207 |
|
| 208 |
$ bup restore -C test /mybackup/latest/etc/ |
| 209 |
Restoring: 2, done. |
| 210 |
|
| 211 |
$ find test |
| 212 |
test |
| 213 |
test/passwd |
| 214 |
test/profile |
| 215 |
|
| 216 |
Restore the contents of etc and etc's metadata to test (trailing |
| 217 |
"/."): |
| 218 |
|
| 219 |
$ bup restore -C test /mybackup/latest/etc/. |
| 220 |
Restoring: 2, done. |
| 221 |
|
| 222 |
# At this point test and etc's metadata will match. |
| 223 |
$ find test |
| 224 |
test |
| 225 |
test/passwd |
| 226 |
test/profile |
| 227 |
|
| 228 |
Restore a tree without risk of unauthorized access: |
| 229 |
|
| 230 |
# mkdir --mode 0700 restore-tmp |
| 231 |
|
| 232 |
# bup restore -C restore-tmp /somebackup/latest/foo |
| 233 |
Restoring: 42, done. |
| 234 |
|
| 235 |
# mv restore-tmp/foo somewhere |
| 236 |
|
| 237 |
# rmdir restore-tmp |
| 238 |
|
| 239 |
Restore a tree, remapping an old user and group to a new user and group: |
| 240 |
|
| 241 |
# ls -l /original/y |
| 242 |
-rw-r----- 1 foo baz 3610 Nov 4 11:31 y |
| 243 |
# bup restore -C dest --map-user foo=bar --map-group baz=bax /x/latest/y |
| 244 |
Restoring: 42, done. |
| 245 |
# ls -l dest/y |
| 246 |
-rw-r----- 1 bar bax 3610 Nov 4 11:31 y |
| 247 |
|
| 248 |
Restore a tree, remapping an old uid to a new uid. Note that the old |
| 249 |
user must be erased so that bup won't prefer it over the uid: |
| 250 |
|
| 251 |
# ls -l /original/y |
| 252 |
-rw-r----- 1 foo baz 3610 Nov 4 11:31 y |
| 253 |
# ls -ln /original/y |
| 254 |
-rw-r----- 1 1000 1007 3610 Nov 4 11:31 y |
| 255 |
# bup restore -C dest --map-user foo= --map-uid 1000=1042 /x/latest/y |
| 256 |
Restoring: 97, done. |
| 257 |
# ls -ln dest/y |
| 258 |
-rw-r----- 1 1042 1007 3610 Nov 4 11:31 y |
| 259 |
|
| 260 |
An alternate way to do the same by quashing users/groups universally |
| 261 |
with `--numeric-ids`: |
| 262 |
|
| 263 |
# bup restore -C dest --numeric-ids --map-uid 1000=1042 /x/latest/y |
| 264 |
Restoring: 97, done. |
| 265 |
|
| 266 |
# SEE ALSO |
| 267 |
|
| 268 |
`bup-save`(1), `bup-ftp`(1), `bup-fuse`(1), `bup-web`(1) |
| 269 |
|
| 270 |
# BUP |
| 271 |
|
| 272 |
Part of the `bup`(1) suite. |