1bup-restore(1)                                                  bup-restore(1)
2
3
4

NAME

6       bup-restore - extract files from a backup set
7

SYNOPSIS

9       bup restore [--outdir=outdir] [--exclude-rx pattern] [--exclude-rx-from
10       filename] [-v] [-q] <paths...>
11

DESCRIPTION

13       bup restore extracts files from a backup set (created with bup-save(1))
14       to the local filesystem.
15
16       The  specified  paths are of the form /branch/revision/some/where.  The
17       components of the path are as follows:
18
19       branch the name of the backup set to restore from; this corresponds  to
20              the --name (-n) option to bup save.
21
22       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
27       some/where
28              the  previously  saved  path (after any stripping/grafting) that
29              you want to restore.  For example, etc/passwd.
30
31       If some/where names a directory, bup restore will restore that directo‐
32       ry and then recursively restore its contents.
33
34       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
40       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
45       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
58       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
66       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
71       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
77       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

OPTIONS

84       -C, --outdir=outdir
85              create and change to  directory  outdir  before  extracting  the
86              files.
87
88       --numeric-ids
89              restore numeric IDs (user, group, etc.) rather than names.
90
91       --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
100              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
106              Examples:
107
108              · `/foo$' - exclude any file named foo
109
110              · `/foo/$' - exclude any directory named foo
111
112              · `/foo/.' - exclude the content of any directory named foo
113
114              · `^/tmp/.'  -  exclude  root-level /tmp's content, but not /tmp
115                itself
116
117       --exclude-rx-from=filename
118              read –exclude-rx patterns from filename,  one  pattern  per-line
119              (may be repeated).  Ignore completely empty lines.
120
121       --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
126       --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
134       --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
142       --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
148       --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
154       -v, --verbose
155              increase  log  output.  Given once, prints every directory as it
156              is restored; given twice, prints every file and directory.
157
158       -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

EXAMPLES

164       Create a simple test backup set:
165
166              $ bup index -u /etc
167              $ bup save -n mybackup /etc/passwd /etc/profile
168
169       Restore just one file:
170
171              $ bup restore /mybackup/latest/etc/passwd
172              Restoring: 1, done.
173
174              $ ls -l passwd
175              -rw-r--r-- 1 apenwarr apenwarr 1478 2010-09-08 03:06 passwd
176
177       Restore etc to test (no trailing slash):
178
179              $ bup restore -C test /mybackup/latest/etc
180              Restoring: 3, done.
181
182              $ find test
183              test
184              test/etc
185              test/etc/passwd
186              test/etc/profile
187
188       Restore the contents of etc to test (trailing slash):
189
190              $ bup restore -C test /mybackup/latest/etc/
191              Restoring: 2, done.
192
193              $ find test
194              test
195              test/passwd
196              test/profile
197
198       Restore the contents of etc and etc's metadata to test (trailing “/.”):
199
200              $ bup restore -C test /mybackup/latest/etc/.
201              Restoring: 2, done.
202
203              # At this point test and etc's metadata will match.
204              $ find test
205              test
206              test/passwd
207              test/profile
208
209       Restore a tree without risk of unauthorized access:
210
211              # mkdir --mode 0700 restore-tmp
212
213              # bup restore -C restore-tmp /somebackup/latest/foo
214              Restoring: 42, done.
215
216              # mv restore-tmp/foo somewhere
217
218              # rmdir restore-tmp
219
220       Restore a tree, remapping an old user and  group  to  a  new  user  and
221       group:
222
223              # 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
230       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
233              # 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
242       An alternate way to do the same by  quashing  users/groups  universally
243       with --numeric-ids:
244
245              # bup restore -C dest --numeric-ids --map-uid 1000=1042 /x/latest/y
246              Restoring: 97, done.
247

SEE ALSO

249       bup-save(1), bup-ftp(1), bup-fuse(1), bup-web(1)
250

BUP

252       Part of the bup(1) suite.
253

AUTHORS

255       Avery Pennarun <apenwarr@gmail.com>.
256
257
258
259Bup 0.29.1                        2017-03-26                    bup-restore(1)
Impressum