1bup-restore(1) bup-restore(1)
2
6 bup-restore - extract files from a backup set
7
9 bup restore [--outdir=outdir] [--exclude-rx pattern] [--exclude-rx-from
10 filename] [-v] [-q] <paths...>
11
13 bup restore extracts files from a backup set (created with bup-save(1))
14 to the local filesystem.
15 The specified paths are of the form /branch/revision/some/where. The
17 components of the path are as follows:
18 branch the name of the backup set to restore from; this corresponds to
20 the --name (-n) option to bup save.
21 revision
23 the revision of the backup set to restore. The revision latest
24 is always the most recent backup on the given branch. You can
25 discover other revisions using bup ls /branch.
26 some/where
28 the previously saved path (after any stripping/grafting) that
29 you want to restore. For example, etc/passwd.
30 If some/where names a directory, bup restore will restore that directo‐
32 ry and then recursively restore its contents.
33 If some/where names a directory and ends with a slash (ie.
35 path/to/dir/), bup restore will restore the children of that directory
36 directly to the current directory (or the --outdir). If some/where
37 does not end in a slash, the children will be restored to a subdirecto‐
38 ry of the current directory.
39 If some/where names a directory and ends in `/.' (ie. path/to/dir/.),
41 bup restore will do exactly what it would have done for path/to/dir,
42 and then restore dir's metadata to the current directory (or the --out‐
43 dir). See the EXAMPLES section.
44 Whenever path metadata is available, bup restore will attempt to re‐
46 store it. When restoring ownership, bup implements tar/rsync-like se‐
47 mantics. It will normally prefer user and group names to uids and gids
48 when they're available, but it will not try to restore the user unless
49 running as root, and it will fall back to the numeric uid or gid when‐
50 ever the metadata contains a user or group name that doesn't exist on
51 the current system. The use of user and group names can be disabled
52 via --numeric-ids (which can be important when restoring a chroot, for
53 example), and as a special case, a uid or gid of 0 will never be
54 remapped by name. Additionally, some systems don't allow setting a
55 uid/gid that doesn't correspond with a known user/group. On those sys‐
56 tems, bup will log an error for each relevant path.
57 The --map-user, --map-group, --map-uid, --map-gid options may be used
59 to adjust the available ownership information before any of the rules
60 above are applied, but note that due to those rules, --map-uid and
61 --map-gid will have no effect whenever a path has a valid user or
62 group. In those cases, either --numeric-ids must be specified, or the
63 user or group must be cleared by a suitable --map-user foo= or
64 --map-group foo=.
65 Hardlinks will also be restored when possible, but at least currently,
67 no links will be made to targets outside the restore tree, and if the
68 restore tree spans a different arrangement of filesystems from the save
69 tree, some hardlink sets may not be completely restored.
70 Also note that changing hardlink sets on disk between index and save
72 may produce unexpected results. With the current implementation, bup
73 will attempt to recreate any given hardlink set as it existed at index
74 time, even if all of the files in the set weren't still hardlinked (but
75 were otherwise identical) at save time.
76 Note that during the restoration process, access to data within the re‐
78 store tree may be more permissive than it was in the original source.
79 Unless security is irrelevant, you must restore to a private subdirec‐
80 tory, and then move the resulting tree to its final position. See the
81 EXAMPLES section for a demonstration.
82
84 -C, --outdir=outdir
85 create and change to directory outdir before extracting the
86 files.
87 --numeric-ids
89 restore numeric IDs (user, group, etc.) rather than names.
90 --exclude-rx=pattern
92 exclude any path matching pattern, which must be a Python regu‐
93 lar expression (http://docs.python.org/library/re.html). The
94 pattern will be compared against the full path rooted at the top
95 of the restore tree, without anchoring, so “x/y” will match
96 “ox/yard” or “box/yards”. To exclude the contents of /tmp, but
97 not the directory itself, use “^/tmp/.”. (can be specified more
98 than once)
99 Note that the root of the restore tree (which matches `^/') is
101 the top of the archive tree being restored, and has nothing to
102 do with the filesystem destination. Given “restore ...
103 /foo/latest/etc/”, the pattern `^/passwd$' would match if a file
104 named passwd had been saved as `/foo/latest/etc/passwd'.
105 Examples:
107 · `/foo$' - exclude any file named foo
109 · `/foo/$' - exclude any directory named foo
111 · `/foo/.' - exclude the content of any directory named foo
113 · `^/tmp/.' - exclude root-level /tmp's content, but not /tmp
115 itself
116 --exclude-rx-from=filename
118 read –exclude-rx patterns from filename, one pattern per-line
119 (may be repeated). Ignore completely empty lines.
120 --sparse
122 write output data sparsely when reasonable. Currently, reason‐
123 able just means “at least whenever there are 512 or more consec‐
124 utive zeroes”.
125 --map-user old=new
127 for every path, restore the old (saved) user name as new. Spec‐
128 ifying “” for new will clear the user. For example “–map-user
129 foo=” will allow the uid to take effect for any path that origi‐
130 nally had a user of “foo”, unless countermanded by a subsequent
131 “–map-user foo=...” specification. See DESCRIPTION above for
132 further information.
133 --map-group old=new
135 for every path, restore the old (saved) group name as new.
136 Specifying “” for new will clear the group. For example
137 “–map-group foo=” will allow the gid to take effect for any path
138 that originally had a group of “foo”, unless countermanded by a
139 subsequent “–map-group foo=...” specification. See DESCRIPTION
140 above for further information.
141 --map-uid old=new
143 for every path, restore the old (saved) uid as new, unless coun‐
144 termanded by a subsequent “–map-uid old=...” option. Note that
145 the uid will only be relevant for paths with no user. See DE‐
146 SCRIPTION above for further information.
147 --map-gid old=new
149 for every path, restore the old (saved) gid as new, unless coun‐
150 termanded by a subsequent “–map-gid old=...” option. Note that
151 the gid will only be relevant for paths with no user. See DE‐
152 SCRIPTION above for further information.
153 -v, --verbose
155 increase log output. Given once, prints every directory as it
156 is restored; given twice, prints every file and directory.
157 -q, --quiet
159 don't show the progress meter. Normally, is stderr is a tty, a
160 progress display is printed that shows the total number of files
161 restored.
162
164 Create a simple test backup set:
165 $ bup index -u /etc
167 $ bup save -n mybackup /etc/passwd /etc/profile
168 Restore just one file:
170 $ bup restore /mybackup/latest/etc/passwd
172 Restoring: 1, done.
173 $ ls -l passwd
175 -rw-r--r-- 1 apenwarr apenwarr 1478 2010-09-08 03:06 passwd
176 Restore etc to test (no trailing slash):
178 $ bup restore -C test /mybackup/latest/etc
180 Restoring: 3, done.
181 $ find test
183 test
184 test/etc
185 test/etc/passwd
186 test/etc/profile
187 Restore the contents of etc to test (trailing slash):
189 $ bup restore -C test /mybackup/latest/etc/
191 Restoring: 2, done.
192 $ find test
194 test
195 test/passwd
196 test/profile
197 Restore the contents of etc and etc's metadata to test (trailing “/.”):
199 $ bup restore -C test /mybackup/latest/etc/.
201 Restoring: 2, done.
202 # At this point test and etc's metadata will match.
204 $ find test
205 test
206 test/passwd
207 test/profile
208 Restore a tree without risk of unauthorized access:
210 # mkdir --mode 0700 restore-tmp
212 # bup restore -C restore-tmp /somebackup/latest/foo
214 Restoring: 42, done.
215 # mv restore-tmp/foo somewhere
217 # rmdir restore-tmp
219 Restore a tree, remapping an old user and group to a new user and
221 group:
222 # ls -l /original/y
224 -rw-r----- 1 foo baz 3610 Nov 4 11:31 y
225 # bup restore -C dest --map-user foo=bar --map-group baz=bax /x/latest/y
226 Restoring: 42, done.
227 # ls -l dest/y
228 -rw-r----- 1 bar bax 3610 Nov 4 11:31 y
229 Restore a tree, remapping an old uid to a new uid. Note that the old
231 user must be erased so that bup won't prefer it over the uid:
232 # ls -l /original/y
234 -rw-r----- 1 foo baz 3610 Nov 4 11:31 y
235 # ls -ln /original/y
236 -rw-r----- 1 1000 1007 3610 Nov 4 11:31 y
237 # bup restore -C dest --map-user foo= --map-uid 1000=1042 /x/latest/y
238 Restoring: 97, done.
239 # ls -ln dest/y
240 -rw-r----- 1 1042 1007 3610 Nov 4 11:31 y
241 An alternate way to do the same by quashing users/groups universally
243 with --numeric-ids:
244 # bup restore -C dest --numeric-ids --map-uid 1000=1042 /x/latest/y
246 Restoring: 97, done.
247
249 bup-save(1), bup-ftp(1), bup-fuse(1), bup-web(1)
250
252 Part of the bup(1) suite.
253
255 Avery Pennarun <apenwarr@gmail.com>.
256Bup 0.29.2 2018-10-20 bup-restore(1)