Debian Codegraph @

Documentation/man8/man5/man2/man3/man2/man7/bup-restore.1.md

raw
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.