Man Linux: Main Page and Category List

NAME

       rdiff-backup - local/remote mirror and incremental backup

SYNOPSIS

       rdiff-backup      [options]      [[[user@]host1.foo]::source_directory]
       [[[user@]host2.foo]::destination_directory]

       rdiff-backup  {{  -l  |  --list-increments  }   |   --remove-older-than
       time_interval  |  --list-at-time  time  |  --list-changed-since  time |
       --list-increment-sizes   |   --verify    |    --verify-at-time    time}
       [[[user@]host2.foo]::destination_directory]

       rdiff-backup --calculate-average statfile1 statfile2 ...

       rdiff-backup           --test-server           [user1]@host1.net1::path
       [[user2]@host2.net2::path] ...

DESCRIPTION

       rdiff-backup is a script,  written  in  python(1)  that  backs  up  one
       directory  to another.  The target directory ends up a copy (mirror) of
       the source directory, but extra reverse diffs are stored in  a  special
       subdirectory  of  that target directory, so you can still recover files
       lost some time ago.  The idea is to combine  the  best  features  of  a
       mirror   and   an  incremental  backup.   rdiff-backup  also  preserves
       symlinks, special files, hardlinks, permissions, uid/gid ownership, and
       modification times.

       rdiff-backup  can  also  operate in a bandwidth efficient manner over a
       pipe, like rsync(1).  Thus you can use ssh and rdiff-backup to securely
       back  a  hard  drive  up to a remote location, and only the differences
       will be transmitted.  Using the default settings, rdiff-backup requires
       that the remote system accept ssh connections, and that rdiff-backup is
       installed in the user’s PATH on the remote system.  For information  on
       other options, see the section on REMOTE OPERATION.

       Note  that  you  should  not  write to the mirror directory except with
       rdiff-backup.  Many of the increments are stored as reverse  diffs,  so
       if  you  delete  or  modify a file, you may lose the ability to restore
       previous versions of that file.

       Finally, this man page is intended more as a precise description of the
       behavior  and  syntax of rdiff-backup.  New users may want to check out
       the examples.html file included in the rdiff-backup distribution.

OPTIONS

       -b, --backup-mode
              Force backup mode even  if  first  argument  appears  to  be  an
              increment or mirror file.

       --calculate-average
              Enter  calculate average mode.  The arguments should be a number
              of statistics files.  rdiff-backup will print the average of the
              listed statistics files and exit.

       --carbonfile
              Enable backup of MacOS X carbonfile information.

       --check-destination-dir
              If an rdiff-backup session fails, running rdiff-backup with this
              option on the destination dir will undo  the  failed  directory.
              This  happens  automatically  if  you  attempt  to  back up to a
              directory and the last backup failed.

       --compare
              This is equivalent to ’--compare-at-time now--compare-at-time time
              Compare a directory with the backup set at the given time.  This
              can  be  useful  to  see  how archived data differs from current
              data, or to check that a backup is current.  This only  compares
              metadata,  in  the  same way rdiff-backup decides whether a file
              has changed.

       --compare-full
              This is equivalent to ’--compare-full-at-time now--compare-full-at-time time
              Compare a directory with the backup set at the given  time.   To
              compare regular files, the repository data will be copied in its
              entirety to the source side and compared byte by byte.  This  is
              the slowest but most complete compare option.

       --compare-hash
              This is equivalent to ’--compare-hash-at-time now--compare-hash-at-time time
              Compare  a  directory  with  the  backup  set at the given time.
              Regular files will be compared by computing their SHA1 digest on
              the  source  side and comparing it to the digest recorded in the
              metadata.

       --create-full-path
              Normally only the final directory of the destination  path  will
              be  created  if it does not exist. With this option, all missing
              directories on the destination path will be  created.  Use  this
              option  with  care:  if  there is a typo in the remote path, the
              remote filesystem could fill up  very  quickly  (by  creating  a
              duplicate backup tree). For this reason this option is primarily
              aimed at scripts which automate backups.

       --current-time seconds
              This option is useful mainly for testing.  If set,  rdiff-backup
              will  use  it  for  the  current  time instead of consulting the
              clock.  The argument is the number of seconds since the epoch.

       --exclude shell_pattern
              Exclude the file  or  files  matched  by  shell_pattern.   If  a
              directory  is matched, then files under that directory will also
              be  matched.   See  the  FILE   SELECTION   section   for   more
              information.

       --exclude-device-files
              Exclude   all   device   files.    This   can   be   useful  for
              security/permissions reasons or if rdiff-backup is not  handling
              device files correctly.

       --exclude-fifos
              Exclude all fifo files.

       --exclude-filelist filename
              Excludes   the   files  listed  in  filename.   If  filename  is
              handwritten  you   probably   want   --exclude-globbing-filelist
              instead.  See the FILE SELECTION section for more information.

       --exclude-filelist-stdin
              Like --exclude-filelist, but the list of files will be read from
              standard  input.   See  the  FILE  SELECTION  section  for  more
              information.

       --exclude-globbing-filelist filename
              Like  --exclude-filelist  but  each line of the filelist will be
              interpreted  according  to  the  same  rules  as  --include  and
              --exclude.

       --exclude-globbing-filelist-stdin
              Like  --exclude-globbing-filelist, but the list of files will be
              read from standard input.

       --exclude-other-filesystems
              Exclude files on file  systems  (identified  by  device  number)
              other  than  the file system the root of the source directory is
              on.

       --exclude-regexp regexp
              Exclude files matching the given regexp.  Unlike  the  --exclude
              option,  this  option  does  not  match  files in a directory it
              matches.  See the FILE SELECTION section for more information.

       --exclude-special-files
              Exclude all device files, fifo files, socket files, and symbolic
              links.

       --exclude-sockets
              Exclude all socket files.

       --exclude-symbolic-links
              Exclude all symbolic links. This option is automatically enabled
              if the backup source is  running  on  native  Windows  to  avoid
              backing-up NTFS reparse points.

       --exclude-if-present filename
              Exclude directories if filename is present. This option needs to
              come before any other include or exclude options.

       --force
              Authorize a more drastic modification of a directory than  usual
              (for  instance,  when overwriting of a destination path, or when
              removing multiple sessions  with  --remove-older-than).   rdiff-
              backup  will  generally tell you if it needs this.  WARNING: You
              can cause data loss if you mis-use this option.  Furthermore, do
              NOT  use  this  option  when  doing a restore, as it will DELETE
              FILES, unless you absolutely know what you are doing.

       --group-mapping-file filename
              Map group names and ids according the  the  group  mapping  file
              filename.    See   the   USERS   AND  GROUPS  section  for  more
              information.

       --include shell_pattern
              Similar to --exclude but include matched files instead.   Unlike
              --exclude,  this  option  will  also match parent directories of
              matched files (although not necessarily  their  contents).   See
              the FILE SELECTION section for more information.

       --include-filelist filename
              Like  --exclude-filelist,  but include the listed files instead.
              If filename is handwritten you probably want --include-globbing-
              filelist  instead.   See  the  FILE  SELECTION  section for more
              information.

       --include-filelist-stdin
              Like --include-filelist, but read the  list  of  included  files
              from standard input.

       --include-globbing-filelist filename
              Like  --include-filelist  but  each line of the filelist will be
              interpreted  according  to  the  same  rules  as  --include  and
              --exclude.

       --include-globbing-filelist-stdin
              Like  --include-globbing-filelist, but the list of files will be
              read from standard input.

       --include-regexp regexp
              Include files matching  the  regular  expression  regexp.   Only
              files  explicitly  matched  by  regexp  will be included by this
              option.  See the FILE SELECTION section for more information.

       --include-special-files
              Include all device files, fifo files, socket files, and symbolic
              links.

       --include-symbolic-links
              Include all symbolic links.

       --list-at-time time
              List  the  files  in  the archive that were present at the given
              time.  If a directory in the archive is specified, list only the
              files under that directory.

       --list-changed-since time
              List  the  files  that have changed in the destination directory
              since the given time.  See TIME FORMATS for the format of  time.
              If  a directory in the archive is specified, list only the files
              under that directory.  This option  does  not  read  the  source
              directory;  it  is used to compare the contents of two different
              rdiff-backup sessions.

       -l, --list-increments
              List  the  number  and  date  of  partial  incremental   backups
              contained  in the specified destination directory.  No backup or
              restore will take place if this option is given.

       --list-increment-sizes
              List the total size of all the increment  and  mirror  files  by
              time.   This  may  be helpful in deciding how many increments to
              keep,   and   when   to   --remove-older-than.    Specifying   a
              subdirectory is allowable; then only the sizes of the mirror and
              increments pertaining to that subdirectory will be listed.

       --max-file-size size
              Exclude files that are larger than the given size in bytes

       --min-file-size size
              Exclude files that are smaller than the given size in bytes

       --never-drop-acls
              Exit with  error  instead  of  dropping  acls  or  acl  entries.
              Normally   this   may   happen  (with  a  warning)  because  the
              destination does  not  support  them  or  because  the  relevant
              user/group names do not exist on the destination side.

       --no-acls
              No Access Control Lists - disable backup of ACLs

       --no-carbonfile
              Disable backup of MacOS X carbonfile information

       --no-compare-inode
              This  option  prevents  rdiff-backup  from flagging a hardlinked
              file as changed when its device  number  and/or  inode  changes.
              This  option is useful in situations where the source filesystem
              lacks persistent device and/or inode  numbering.   For  example,
              network filesystems may have mount-to-mount differences in their
              device number (but  possibly  stable  inode  numbers);  USB/1394
              devices  may  come  up  at different device numbers each remount
              (but would generally have same  inode  number);  and  there  are
              filesystems  which  don’t  even have the same inode numbers from
              use to  use.   Without  the  option  rdiff-backup  may  generate
              unnecessary numbers of tiny diff files.

       --no-compression
              Disable  the  default  gzip compression of most of the .snapshot
              and  .diff  increment  files  stored  in  the  rdiff-backup-data
              directory.    A   backup   volume  can  contain  compressed  and
              uncompressed increments, so using this option inconsistently  is
              fine.

       --no-compression-regexp  regexp
              Do  not compress increments based on files whose filenames match
              regexp.   The  default  includes  many  common  audiovisual  and
              archive files, and may be found in Globals.py.

       --no-eas
              No Extended Attributes support - disable backup of EAs.

       --no-file-statistics
              This  will  disable  writing  to the file_statistics file in the
              rdiff-backup-data directory.   rdiff-backup  will  run  slightly
              quicker and take up a bit less space.

       --no-hard-links
              Don’t  replicate  hard links on destination side.  If many hard-
              linked files are present, this option can  drastically  decrease
              memory  usage.   This option is enabled by default if the backup
              source or restore destination is running on native Windows.

       --null-separator
              Use nulls (\0) instead of  newlines  (\n)  as  line  separators,
              which  may help when dealing with filenames containing newlines.
              This affects the expected format of the files specified  by  the
              --{include|exclude}-filelist[-stdin]  switches  as  well  as the
              format of the directory statistics file.

       --parsable-output
              If set, rdiff-backup’s output will be tailored for easy  parsing
              by computers, instead of convenience for humans.  Currently this
              only applies when listing increments using  the  -l  or  --list-
              increments  switches,  where  the  time will be given in seconds
              since the epoch.

       --override-chars-to-quote
              If the filesystem to which  we  are  backing  up  is  not  case-
              sensitive,   automatic   ’quoting’  of  characters  occurs.  For
              example,  a  file  ’Developer.doc’  will   be   converted   into
              ’;068eveloper.doc’.  To  override  this  behavior,  you  need to
              specify this option.

       --preserve-numerical-ids
              If set, rdiff-backup will preserve uids/gids instead  of  trying
              to preserve unames and gnames.  See the USERS AND GROUPS section
              for more information.

       --print-statistics
              If set, summary statistics will be printed  after  a  successful
              backup.   If  not  set, this information will still be available
              from the session statistics file.  See  the  STATISTICS  section
              for more information.

       -r, --restore-as-of restore_time
              Restore  the  specified  directory as it was as of restore_time.
              See the TIME FORMATS section for more information on the  format
              of   restore_time,  and  see  the  RESTORING  section  for  more
              information on restoring.

       --remote-cmd cmd
              Deprecated. Please use --remote-schema instead

       --remote-schema schema
              Specify an alternate method of connecting to a remote  computer.
              This  is necessary to get rdiff-backup not to use ssh for remote
              backups, or if, for instance, rdiff-backup is not in the PATH on
              the  remote  side.   See  the  REMOTE OPERATION section for more
              information.

       --remote-tempdir path
              Adds the --tempdir  option  with  argument  path  when  invoking
              remote instances of rdiff-backup.

       --remove-older-than time_spec
              Remove  the  incremental  backup  information in the destination
              directory that has been  around  longer  than  the  given  time.
              time_spec  can be either an absolute time, like "2002-01-04", or
              a time interval.  The time interval is an  integer  followed  by
              the  character  s,  m,  h,  D,  W,  M, or Y, indicating seconds,
              minutes, hours, days, weeks, months, or years respectively, or a
              number  of  these  concatenated.   For  example,  32m  means  32
              minutes, and 3W2D10h7s means 3 weeks, 2 days, 10  hours,  and  7
              seconds.   In this context, a month means 30 days, a year is 365
              days, and a day is always 86400 seconds.

              rdiff-backup cannot remove-older-than and back up or restore  in
              a  single  session.   In  order  to  both backup a directory and
              remove old files in it, you must run rdiff-backup twice.

              By default, rdiff-backup will only delete information  from  one
              session  at  a time.  To remove two or more sessions at the same
              time, supply the --force option (rdiff-backup will tell  you  if
              --force is required).

              Note  that  snapshots  of  deleted  files  are  covered  by this
              operation.  Thus if you deleted a file two weeks ago, backed  up
              immediately afterwards, and then ran rdiff-backup with --remove-
              older-than 10D today,  no  trace  of  that  file  would  remain.
              Finally,  file selection options such as --include and --exclude
              don’t affect --remove-older-than.

       --restrict path
              Require that all file access be inside  the  given  path.   This
              switch,  and the following two, are intended to be used with the
              --server switch to provide a  bit  more  protection  when  doing
              automated  remote  backups.   They are not intended as your only
              line of defense so please don’t do something  silly  like  allow
              public  access  to  an  rdiff-backup server run with --restrict-
              read-only.

       --restrict-read-only path
              Like --restrict, but also reject all write requests.

       --restrict-update-only path
              Like --restrict, but only allow writes as part of an incremental
              backup.   Requests  for  other  types  of  writes (for instance,
              deleting path) will be rejected.

       --server
              Enter server mode (not to be invoked directly, but instead  used
              by another rdiff-backup process on a remote computer).

       --ssh-no-compression
              When   running   ssh,  do  not  use  the  -C  option  to  enable
              compression.  --ssh-no-compression is ignored if you  specify  a
              new schema using --remote-schema.

       --tempdir path
              Sets the directory that rdiff-backup uses for temporary files to
              the given path. The environment variables TMPDIR, TEMP, and  TMP
              can  also  be used to set the temporary files directory. See the
              documentation  of  the   Python   tempfile   module   for   more
              information.

       --terminal-verbosity [0-9]
              Select  which  messages  will  be displayed to the terminal.  If
              missing the level defaults to the verbosity level.

       --test-server
              Test for the presence of a  compatible  rdiff-backup  server  as
              specified  in  the  following  host::filename  argument(s).  The
              filename section will be ignored.

       --user-mapping-file filename
              Map user names and  ids  according  to  the  user  mapping  file
              filename.    See   the   USERS   AND  GROUPS  section  for  more
              information.

       -v[0-9], --verbosity [0-9]
              Specify verbosity level (0 is totally silent, 3 is the  default,
              and  9 is noisiest).  This determines how much is written to the
              log file.

       --verify
              This is short for --verify-at-time now

       --verify-at-time now
              Check all the data in  the  repository  at  the  given  time  by
              computing  the  SHA1 hash of all the regular files and comparing
              them with the hashes stored in the metadata file.

       -V, --version
              Print the current version and exit

RESTORING

       There are two ways to tell rdiff-backup to restore a file or directory.
       Firstly,  you  can  run rdiff-backup on a mirror file and use the -r or
       --restore-as-of options.  Secondly, you can  run  it  on  an  increment
       file.

       For example, suppose in the past you have run:

              rdiff-backup /usr /usr.backup

       to  back  up the /usr directory into the /usr.backup directory, and now
       want a copy of the /usr/local directory the  way  it  was  3  days  ago
       placed at /usr/local.old.

       One way to do this is to run:

              rdiff-backup -r 3D /usr.backup/local /usr/local.old

       where  above the "3D" means 3 days (for other ways to specify the time,
       see the TIME FORMATS section).   The  /usr.backup/local  directory  was
       selected,  because that is the directory containing the current version
       of /usr/local.

       Note that the option to --restore-as-of always specifies an exact time.
       (So  "3D" refers to the instant 72 hours before the present.)  If there
       was no backup made  at  that  time,  rdiff-backup  restores  the  state
       recorded  for the previous backup.  For instance, in the above case, if
       "3D" is used, and there are only backups from 2 days and  4  days  ago,
       /usr/local as it was 4 days ago will be restored.

       The  second  way  to  restore  files involves finding the corresponding
       increment   file.    It   would   be   in   the   /backup/rdiff-backup-
       data/increments/usr  directory,  and  its  name would be something like
       "local.2002-11-09T12:43:53-04:00.dir" where the time  indicates  it  is
       from  3  days  ago.   Note that the increment files all end in ".diff",
       ".snapshot", ".dir", or ".missing", where ".missing"  just  means  that
       the file didn’t exist at that time (finally, some of these may be gzip-
       compressed, and have an extra ".gz" to indicate this).  Then running:

              rdiff-backup                               /backup/rdiff-backup-
              data/increments/usr/local.<time>.dir /usr/local.old

       would also restore the file as desired.

       If  you  are  not  sure exactly which version of a file you need, it is
       probably easiest  to  either  restore  from  the  increments  files  as
       described  immediately  above, or to see which increments are available
       with  -l/--list-increments,  and  then   specify   exact   times   into
       -r/--restore-as-of.

TIME FORMATS

       rdiff-backup  uses  time  strings  in  two places.  Firstly, all of the
       increment files rdiff-backup  creates  will  have  the  time  in  their
       filenames  in  the  w3  datetime  format  as  described in a w3 note at
       http://www.w3.org/TR/NOTE-datetime.    Basically   they    look    like
       "2001-07-15T04:09:38-07:00",  which  means  what  it  looks  like.  The
       "-07:00" section means the time zone is 7 hours behind UTC.

       Secondly, the -r, --restore-as-of, and --remove-older-than options take
       a time string, which can be given in any of several formats:

       1.     the string "now" (refers to the current time)

       2.     a  sequences of digits, like "123456890" (indicating the time in
              seconds after the epoch)

       3.     A string like "2002-01-25T07:00:00+02:00" in datetime format

       4.     An interval, which is a number followed by one of the characters
              s,  m,  h,  D,  W,  M, or Y (indicating seconds, minutes, hours,
              days, weeks, months, or years respectively), or a series of such
              pairs.  In this case the string refers to the time that preceded
              the current time by the length of the interval.   For  instance,
              "1h78m" indicates the time that was one hour and 78 minutes ago.
              The calendar here is unsophisticated: a month is always 30 days,
              a year is always 365 days, and a day is always 86400 seconds.

       5.     A date format of the form YYYY/MM/DD, YYYY-MM-DD, MM/DD/YYYY, or
              MM-DD-YYYY, which indicates midnight on  the  day  in  question,
              relative  to  the  current  timezone  settings.   For  instance,
              "2002/3/5", "03-05-2002", and "2002-3-05" all  mean  March  5th,
              2002.

       6.     A  backup  session specification which is a non-negative integer
              followed by ’B’.  For instance, ’0B’ specifies the time  of  the
              current  mirror,  and  ’3B’ specifies the time of the 3rd newest
              increment.

REMOTE OPERATION

       In order to access remote files, rdiff-backup opens up a pipe to a copy
       of  rdiff-backup running on the remote machine.  Thus rdiff-backup must
       be installed on both ends.   To  open  this  pipe,  rdiff-backup  first
       splits  the  filename  into  host_info::pathname.   It then substitutes
       host_info into the remote  schema,  and  runs  the  resulting  command,
       reading its input and output.

       The  default  remote  schema is ’ssh -C %s rdiff-backup --server’ where
       host_info  is  substituted  for  ’%s’.   So   if   the   host_info   is
       user@host.net,  then  rdiff-backup runs ’ssh user@host.net rdiff-backup
       --server’.  Using --remote-schema, rdiff-backup can invoke an arbitrary
       command in order to open up a remote pipe.  For instance,
              rdiff-backup  --remote-schema  ’cd  /usr;  %s’ foo ’rdiff-backup
              --server’::bar
       is basically equivalent to (but slower than)
              rdiff-backup foo /usr/bar

       Concerning quoting, if for some reason you need to put two  consecutive
       colons  in  the host_info section of a host_info::pathname argument, or
       in the pathname of  a  local  file,  you  can  quote  one  of  them  by
       prepending  a backslash.  So in ’a\::b::c’, host_info is ’a::b’ and the
       pathname is ’c’.  Similarly, if you want to refer to a local file whose
       filename  contains two consecutive colons, like ’strange::file’, you’ll
       have to quote one of the colons as in  ’strange\::file’.   Because  the
       backslash  is  a quote character in these circumstances, it too must be
       quoted to get  a  literal  backslash,  so  ’foo\::\\bar’  evaluates  to
       ’foo::\bar’.  To make things more complicated, because the backslash is
       also a common shell quoting character, you may need to type  in  ’\\\\’
       at  the  shell  prompt to get a literal backslash (if it makes you feel
       better, I had to type  in  8  backslashes  to  get  that  in  this  man
       page...).   And finally, to include a literal % in the string specified
       by --remote-schema, quote it with another %, as in %%.

       Although ssh itself may be secure, using rdiff-backup  in  the  default
       way presents some security risks.  For instance if the server is run as
       root, then an attacker who compromised the client could then use rdiff-
       backup  to  overwrite arbitrary server files by "backing up" over them.
       Such a setup can be made more secure by using  the  sshd  configuration
       option   command="rdiff-backup   --server"   possibly  along  with  the
       --restrict* options to rdiff-backup.  For more information, see the web
       page, the wiki, and the entries for the --restrict* options on this man
       page.

FILE SELECTION

       rdiff-backup has a number of file selection options.  When rdiff-backup
       is run, it searches through the given source directory and backs up all
       the files matching the specified options.  This  selection  system  may
       appear  complicated, but it is supposed to be flexible and easy-to-use.
       If you just want to learn the  basics,  first  look  at  the  selection
       examples  in  the examples.html file included in the package, or on the
       web at http://rdiff-backup.nongnu.org/examples.html

       rdiff-backup’s selection system was originally  inspired  by  rsync(1),
       but  there  are  many differences.  (For instance, trailing backslashes
       have no special significance.)

       The  file  selection  system  comprises  a  number  of  file  selection
       conditions,  which  are  set  using  one  of the following command line
       options:   --exclude,    --exclude-filelist,    --exclude-device-files,
       --exclude-fifos,      --exclude-sockets,      --exclude-symbolic-links,
       --exclude-globbing-filelist,         --exclude-globbing-filelist-stdin,
       --exclude-filelist-stdin,   --exclude-regexp,  --exclude-special-files,
       --include, --include-filelist, --include-globbing-filelist,  --include-
       globbing-filelist-stdin,   --include-filelist-stdin,   and   --include-
       regexp.  Each file selection condition either matches or doesn’t  match
       a  given  file.   A given file is excluded by the file selection system
       exactly when the first matching file selection condition specifies that
       the file be excluded; otherwise the file is included.  When backing up,
       if a file is excluded, rdiff-backup acts as if that file does not exist
       in   the  source  directory.   When  restoring,  an  excluded  file  is
       considered not to exist in either the source or target directories.

       For instance,

              rdiff-backup --include /usr --exclude /usr /usr /backup

       is exactly the same as

              rdiff-backup /usr /backup

       because the include and  exclude  directives  match  exactly  the  same
       files, and the --include comes first, giving it precedence.  Similarly,

              rdiff-backup --include /usr/local/bin --exclude /usr/local  /usr
              /backup

       would  backup  the /usr/local/bin directory (and its contents), but not
       /usr/local/doc.

       The include, exclude, include-globbing-filelist, and  exclude-globbing-
       filelist  options  accept  extended  shell  globbing  patterns.   These
       patterns can contain the special patterns *, **, ?, and [...].  As in a
       normal  shell,  *  can  be  expanded  to  any  string of characters not
       containing "/", ?  expands to  any  character  except  "/",  and  [...]
       expands to a single character of those characters specified (ranges are
       acceptable).  The new special pattern, **, expands  to  any  string  of
       characters whether or not it contains "/".  Furthermore, if the pattern
       starts with "ignorecase:" (case insensitive), then this prefix will  be
       removed  and any character in the string can be replaced with an upper-
       or lowercase version of itself.

       If you need  to  match  filenames  which  contain  the  above  globbing
       characters,  they  may  be escaped using a backslash "\". The backslash
       will only escape the character following it so for ** you will need  to
       use "\*\*" to avoid escaping it to the * globbing character.

       Remember  that  you may need to quote these characters when typing them
       into a shell, so the shell does not  interpret  the  globbing  patterns
       before rdiff-backup sees them.

       The --exclude pattern option matches a file iff:

       1.     pattern can be expanded into the file’s filename, or

       2.     the file is inside a directory matched by the option.

       Conversely, --include pattern matches a file iff:

       1.     pattern can be expanded into the file’s filename,

       2.     the file is inside a directory matched by the option, or

       3.     the  file  is  a  directory which contains a file matched by the
              option.

       For example,

              --exclude /usr/local

       matches /usr/local, /usr/local/lib, and /usr/local/lib/netscape.  It is
       the same as --exclude /usr/local --exclude ’/usr/local/**’.

              --include /usr/local

       specifies     that     /usr,     /usr/local,     /usr/local/lib,    and
       /usr/local/lib/netscape (but not /usr/doc) all be backed up.  Thus  you
       don’t  have  to  worry  about including parent directories to make sure
       that included subdirectories have somewhere to go.  Finally,

              --include ignorecase:’/usr/[a-z0-9]foo/*/**.py’

       would match a file  like  /usR/5fOO/hello/there/world.py.   If  it  did
       match anything, it would also match /usr.  If there is no existing file
       that the given pattern can be expanded into, the option will not  match
       /usr.

       The  --include-filelist,  --exclude-filelist, --include-filelist-stdin,
       and --exclude-filelist-stdin  options  also  introduce  file  selection
       conditions.   They  direct rdiff-backup to read in a file, each line of
       which is a file specification, and to include or exclude  the  matching
       files.   Lines are separated by newlines or nulls, depending on whether
       the --null-separator switch was given.  Each  line  in  a  filelist  is
       interpreted  similarly  to  the way extended shell patterns are, with a
       few exceptions:

       1.     Globbing patterns like *, **, ?, and [...]  are not expanded.

       2.     Include patterns do not match  files  in  a  directory  that  is
              included.   So  /usr/local  in  an  include  file will not match
              /usr/local/doc.

       3.     Lines starting with "+ " are interpreted as include  directives,
              even  if  found  in a filelist referenced by --exclude-filelist.
              Similarly, lines starting with "- " exclude files even  if  they
              are found within an include filelist.

       For example, if the file "list.txt" contains the lines:

              /usr/local
              - /usr/local/doc
              /usr/local/bin
              + /var
              - /var

       then  "--include-filelist list.txt" would include /usr, /usr/local, and
       /usr/local/bin.       It      would       exclude       /usr/local/doc,
       /usr/local/doc/python,   etc.    It   neither   excludes  nor  includes
       /usr/local/man,  leaving  the  fate  of  this  directory  to  the  next
       specification  condition.   Finally,  it is undefined what happens with
       /var.   A  single  file  list  should  not  contain  conflicting   file
       specifications.

       The --include-globbing-filelist and --exclude-globbing-filelist options
       also  specify  filelists,  but  each  line  in  the  filelist  will  be
       interpreted  as  a  globbing  pattern  the  way --include and --exclude
       options are interpreted (although "+ " and  "-  "  prefixing  is  still
       allowed).   For  instance, if the file "globbing-list.txt" contains the
       lines:

              dir/foo
              + dir/bar
              - **

       Then "--include-globbing-filelist globbing-list.txt" would  be  exactly
       the  same  as specifying "--include dir/foo --include dir/bar --exclude
       **" on the command line.

       Finally, the --include-regexp and --exclude-regexp allow  files  to  be
       included  and  excluded  if  their  filenames  match  a  python regular
       expression.  Regular expression syntax is too  complicated  to  explain
       here,  but  is  covered  in  Python’s  library  reference.   Unlike the
       --include and --exclude options, the regular expression  options  don’t
       match files containing or contained in matched files.  So for instance

              --include ’[0-9]{7}(?!foo)’

       matches  any  files  whose  full pathnames contain 7 consecutive digits
       which aren’t followed by ’foo’.  However, it wouldn’t match /home  even
       if /home/ben/1234567 existed.

USERS AND GROUPS

       There  can  be  complications preserving ownership across systems.  For
       instance the username that owns a file on the  source  system  may  not
       exist  on  the destination.  Here is how rdiff-backup maps ownership on
       the  source  to  the  destination  (or  vice-versa,  in  the  case   of
       restoring):

       1.     If  the  --preserve-numerical-ids  option  is  given, the remote
              files will always have the same uid and gid, both for  ownership
              and ACL entries.  This may cause unames and gnames to change.

       2.     Otherwise,  attempt  to  preserve  the  user and group names for
              ownership  and  in  ACLs.   This  may  result  in  files  having
              different uids and gids across systems.

       3.     If  a  name  cannot be preserved (e.g. because the username does
              not exist), preserve the original id, but only in cases of  user
              and  group  ownership.   For ACLs, omit any entry that has a bad
              user or group name.

       4.     The   --user-mapping-file   and   --group-mapping-file   options
              override  this  behavior.   If either of these options is given,
              the policy described in 2 and 3 above will be followed, but with
              the  mapped  user  and  group  instead  of the original.  If you
              specify both --preserve-numerical-ids and  one  of  the  mapping
              options, the behavior is undefined.

       The user and group mapping files both have the same form:

              old_name_or_id1:new_name_or_id1
              old_name_or_id2:new_name_or_id2
              <etc>

       Each  line  should  contain  a  name  or  id,  followed by a colon ":",
       followed by another name or id.  If a name or id is  not  listed,  they
       are treated in the default way described above.

       When  restoring, the above behavior is also followed, but note that the
       original source user/group information  will  be  the  input,  not  the
       already mapped user/group information present in the backup repository.
       For instance, suppose you have mapped all the files owned by  alice  in
       the source so that they are owned by ben in the repository, and now you
       want to restore, making sure the files owned originally  by  alice  are
       still  owned by alice.  In this case there is no need to use any of the
       mapping options.  However, if you wanted to restore the files  so  that
       the files originally owned by alice on the source are now owned by ben,
       you would have to use the mapping options, even though  you  just  want
       the unames of the repository’s files preserved in the restored files.

STATISTICS

       Every session rdiff-backup saves various statistics into two files, the
       session        statistics         file         at         rdiff-backup-
       data/session_statistics.<time>.data  and  the directory statistics file
       at rdiff-backup-data/directory_statistics.<time>.data.  They  are  both
       text files and contain similar information: how many files changed, how
       many were deleted, the total size  of  increment  files  created,  etc.
       However,  the  session  statistics file is intended to be very readable
       and only describes the session as a whole.   The  directory  statistics
       file  is  more compact (and slightly less readable) but describes every
       directory backed up.  It also may be compressed to save space.

       Statistics-related  options  include  --print-statistics  and   --null-
       separator.

       Also, rdiff-backup will save various messages to the log file, which is
       rdiff-backup-data/backup.log  for  backup  sessions  and  rdiff-backup-
       data/restore.log  for  restore  sessions.  Generally what is written to
       this file will coincide  with  the  messages  displayed  to  stdout  or
       stderr,  although  this  can  be  changed with the --terminal-verbosity
       option.

       The log file is not compressed and can become  quite  large  if  rdiff-
       backup is run with high verbosity.

EXIT STATUS

       If  rdiff-backup  finishes successfully, the exit status will be 0.  If
       there is  an  unrecoverable  (critical)  error,  it  will  be  non-zero
       (usually  1, but don’t depend on this specific value).  When setting up
       rdiff-backup to run automatically (as from cron(8) or  similar)  it  is
       probably a good idea to check the exit code.

BUGS

       The  gzip  library  in versions 2.2 and earlier of python (but fixed in
       2.3a1) has trouble producing files over 2GB in length.  This  bug  will
       prevent   rdiff-backup   from  producing  large  compressed  increments
       (snapshots or diffs).  A workaround is to disable compression for large
       uncompressable files.

AUTHOR

       Ben Escoto <ben@emerose.org>

       Feel  free to ask me questions or send me bug reports, but you may want
       to see the web page, mentioned below, first.

SEE ALSO

       python(1), rdiff(1), rsync(1), ssh(1).  The main rdiff-backup web  page
       is  at http://rdiff-backup.nongnu.org/.  It has more information, links
       to the mailing list and CVS, etc.