Provided by: bup-doc_0.25-1_all bug

NAME

       bup-restore - extract files from a backup set

SYNOPSIS

       bup restore [--outdir=outdir][\--exclude-rx *pattern*] [-v][-q] <paths...>

DESCRIPTION

       bup restore  extracts  files  from  a  backup  set (created with bup-save(1)) to the local
       filesystem.

       The specified paths are of the form /branch/revision/some/where.  The  components  of  the
       path are as follows:

       branch the  name  of  the  backup set to restore from; this corresponds to the --name (-n)
              option to bup save.

       revision
              the revision of the backup set to restore.  The revision latest is always the  most
              recent  backup  on  the  given  branch.   You  can  discover  other revisions using
              bup ls /branch.

       some/where
              the previously saved path (after any stripping/grafting) that you want to  restore.
              For example, etc/passwd.

       If  some/where  names  a  directory,  bup restore  will  restore  that  directory and then
       recursively restore its contents.

       If some/where names a directory and ends with a  slash  (ie.   path/to/dir/),  bup restore
       will  restore  the  children  of  that directory directly to the current directory (or the
       --outdir).  If some/where does not end in a slash, the children  will  be  restored  to  a
       subdirectory of the current directory.

       If some/where names a directory and ends in '/.' (ie.  path/to/dir/.), bup restore will do
       exactly what it would have done for path/to/dir, and then restore dir's  metadata  to  the
       current directory (or the --outdir).  See the EXAMPLES section.

       Whenever  path  metadata  is  available,  bup restore  will  attempt  to restore it.  When
       restoring ownership, bup implements tar/rsync-like semantics.   It  will  normally  prefer
       user  and  group  names  to  uids  and gids when they're available, but it will not try to
       restore the user unless running as root, and it will fall back to the numeric uid  or  gid
       whenever  the  metadata  contains  a  user or group name that doesn't exist on the current
       system.  The use of user and group names can be disabled via --numeric-ids (which  can  be
       important  when restoring a chroot, for example), and as a special case, a uid or gid of 0
       will never be remapped by name.  Additionally, some systems don't allow setting a  uid/gid
       that  doesn't correspond with a known user/group.  On those systems, bup will log an error
       for each relevant path.

       The --map-user, --map-group, --map-uid, --map-gid  options  may  be  used  to  adjust  the
       available  ownership  information before any of the rules above are applied, but note that
       due to those rules, --map-uid and --map-gid will have no effect  whenever  a  path  has  a
       valid  user or group.  In those cases, either --numeric-ids must be specified, or the user
       or group must be cleared by a suitable --map-user foo= or --map-group foo=.

       Hardlinks will also be restored when possible, but at least currently, no  links  will  be
       made  to  targets  outside  the  restore  tree,  and if the restore tree spans a different
       arrangement of filesystems from the save tree, some hardlink sets may  not  be  completely
       restored.

       Also  note  that  changing  hardlink  sets  on  disk  between  index  and save may produce
       unexpected results.  With the current implementation, bup will  attempt  to  recreate  any
       given  hardlink  set  as  it  existed  at  index time, even if all of the files in the set
       weren't still hardlinked (but were otherwise identical) at save time.

       Note that during the restoration process, access to data within the restore  tree  may  be
       more  permissive  than  it was in the original source.  Unless security is irrelevant, you
       must restore to a private subdirectory, and then move the  resulting  tree  to  its  final
       position.  See the EXAMPLES section for a demonstration.

OPTIONS

       -C, --outdir=outdir
              create and change to directory outdir before extracting the files.

       --numeric-ids
              restore numeric IDs (user, group, etc.) rather than names.

       --exclude-rx=pattern
              exclude  any  path  matching  pattern,  which  must  be a Python regular expression
              (http://docs.python.org/library/re.html).  The pattern will be compared against the
              full  path  rooted at the top of the restore tree, without anchoring, so "x/y" will
              match "ox/yard" or "box/yards".  To exclude the  contents  of  /tmp,  but  not  the
              directory itself, use "^/tmp/.".  (can be specified more than once)

              Note  that  the  root  of  the  restore tree (which matches '^/') is the top of the
              archive tree being restored, and has nothing to do with the filesystem destination.
              Given  "restore  ...   /foo/latest/etc/",  the pattern '^/passwd$' would match if a
              file named passwd had been saved as '/foo/latest/etc/passwd'.

              Examples:

              • '/foo$' - exclude any file named foo

              • '/foo/$' - exclude any directory named foo

              • '/foo/.' - exclude the content of any directory named foo

              • '^/tmp/.' - exclude root-level /tmp's content, but not /tmp itself

       --map-user old=new
              for every path, restore the old (saved) user name as new.  Specifying  ""  for  new
              will  clear  the  user.   For  example "--map-user foo=" will allow the uid to take
              effect for any path that originally had a user of "foo", unless countermanded by  a
              subsequent  "--map-user  foo=..." specification.  See DESCRIPTION above for further
              information.

       --map-group old=new
              for every path, restore the old (saved) group name as new.  Specifying ""  for  new
              will  clear  the  group.  For example "--map-group foo=" will allow the gid to take
              effect for any path that originally had a group of "foo", unless countermanded by a
              subsequent  "--map-group foo=..." specification.  See DESCRIPTION above for further
              information.

       --map-uid old=new
              for every path, restore the old (saved) uid  as  new,  unless  countermanded  by  a
              subsequent  "--map-uid  old=..."   option.  Note that the uid will only be relevant
              for paths with no user.  See DESCRIPTION above for further information.

       --map-gid old=new
              for every path, restore the old (saved) gid  as  new,  unless  countermanded  by  a
              subsequent  "--map-gid  old=..."   option.  Note that the gid will only be relevant
              for paths with no user.  See DESCRIPTION above for further information.

       -v, --verbose
              increase log output.  Given once, prints every directory as it is  restored;  given
              twice, prints every file and directory.

       -q, --quiet
              don't show the progress meter.  Normally, is stderr is a tty, a progress display is
              printed that shows the total number of files restored.

EXAMPLE

       Create a simple test backup set:

              $ bup index -u /etc
              $ bup save -n mybackup /etc/passwd /etc/profile

       Restore just one file:

              $ bup restore /mybackup/latest/etc/passwd
              Restoring: 1, done.

              $ ls -l passwd
              -rw-r--r-- 1 apenwarr apenwarr 1478 2010-09-08 03:06 passwd

       Restore etc to test (no trailing slash):

              $ bup restore -C test /mybackup/latest/etc
              Restoring: 3, done.

              $ find test
              test
              test/etc
              test/etc/passwd
              test/etc/profile

       Restore the contents of etc to test (trailing slash):

              $ bup restore -C test /mybackup/latest/etc/
              Restoring: 2, done.

              $ find test
              test
              test/passwd
              test/profile

       Restore the contents of etc and etc's metadata to test (trailing "/."):

              $ bup restore -C test /mybackup/latest/etc/.
              Restoring: 2, done.

              # At this point test and etc's metadata will match.
              $ find test
              test
              test/passwd
              test/profile

       Restore a tree without risk of unauthorized access:

              # mkdir --mode 0700 restore-tmp

              # bup restore -C restore-tmp /somebackup/latest/foo
              Restoring: 42, done.

              # mv restore-tmp/foo somewhere

              # rmdir restore-tmp

       Restore a tree, remapping an old user and group to a new user and group:

              # ls -l /original/y
              -rw-r----- 1 foo baz  3610 Nov  4 11:31 y
              # bup restore -C dest --map-user foo=bar --map-group baz=bax /x/latest/y
              Restoring: 42, done.
              # ls -l dest/y
              -rw-r----- 1 bar bax  3610 Nov  4 11:31 y

       Restore a tree, remapping an old uid to a new uid.  Note that the old user must be  erased
       so that bup won't prefer it over the uid:

              # ls -l /original/y
              -rw-r----- 1 foo baz  3610 Nov  4 11:31 y
              # ls -ln /original/y
              -rw-r----- 1 1000 1007  3610 Nov  4 11:31 y
              # bup restore -C dest --map-user foo= --map-uid 1000=1042 /x/latest/y
              Restoring: 97, done.
              # ls -ln dest/y
              -rw-r----- 1 1042 1007  3610 Nov  4 11:31 y

       An alternate way to do the same by quashing users/groups universally with --numeric-ids:

              # bup restore -C dest --numeric-ids --map-uid 1000=1042 /x/latest/y
              Restoring: 97, done.

SEE ALSO

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

BUP

       Part of the bup(1) suite.

AUTHORS

       Avery Pennarun <apenwarr@gmail.com>.