man pages section 1: User Commands

Exit Print View

Updated: July 2014

rdiff-backup (1)


rdiff-backup - local/remote mirror and incremental backup


rdiff-backup [options] [[[user@]]::source_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@]]::destination_directory

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

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


User Manuals                                      RDIFF-BACKUP(1)

     rdiff-backup - local/remote mirror and incremental backup

     rdiff-backup [options] [[[user@]]::source_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@]]::destination_directory

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

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

     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 sym-
     links, special files, hardlinks, permissions, uid/gid owner-
     ship, and modification times.

     rdiff-backup can also operate in a bandwidth efficient  man-
     ner  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

     Note that you should not write to  the  mirror  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.

     -b, --backup-mode

Version 1.3.3        Last change: March 2009                    1

User Manuals                                      RDIFF-BACKUP(1)

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

          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.

          Enable backup of MacOS X carbonfile information.

          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

          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 dif-
          fers  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.

          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.

          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.

          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

Version 1.3.3        Last change: March 2009                    2

User Manuals                                      RDIFF-BACKUP(1)

          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 all device files.  This can be useful for secu-
          rity/permissions reasons or if rdiff-backup is not han-
          dling device files correctly.

          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.

          Like --exclude-filelist, but the list of files will  be
          read  from standard input.  See the FILE SELECTION sec-
          tion 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.

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

          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

Version 1.3.3        Last change: March 2009                    3

User Manuals                                      RDIFF-BACKUP(1)

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

          Exclude all device files, fifo files, socket files, and
          symbolic links.

          Exclude all socket files.

          Exclude  all  symbolic  links. This option is automati-
          cally 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

          Authorize  a  more  drastic modification of a directory
          than usual (for instance, when overwriting of a  desti-
          nation  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.

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

Version 1.3.3        Last change: March 2009                    4

User Manuals                                      RDIFF-BACKUP(1)

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

          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 sec-
          tion for more information.

          Include all device files, fifo files, socket files, and
          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  speci-
          fied, 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

          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

Version 1.3.3        Last change: March 2009                    5

User Manuals                                      RDIFF-BACKUP(1)


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

          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 Access Control Lists - disable backup of ACLs

          Disable backup of MacOS X carbonfile information

          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 situa-
          tions 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 num-
          bers); 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  unneces-
          sary numbers of tiny diff files.

          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 con-
          tain compressed and uncompressed increments,  so  using
          this option inconsistently is fine.

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

          No Extended Attributes support - disable backup of EAs.

          This  will  disable writing to the file_statistics file

Version 1.3.3        Last change: March 2009                    6

User Manuals                                      RDIFF-BACKUP(1)

          in the rdiff-backup-data directory.  rdiff-backup  will
          run slightly quicker and take up a bit less space.

          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 des-
          tination is running on native Windows.

          Use nulls (\0) instead of newlines (\n) as line separa-
          tors, which may help when dealing with  filenames  con-
          taining  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.

          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

          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.

          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.

          If set, summary statistics will be printed after a suc-
          cessful 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

Version 1.3.3        Last change: March 2009                    7

User Manuals                                      RDIFF-BACKUP(1)

     --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 desti-
          nation  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 inter-
          val 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 ses-
          sions  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  selec-
          tion  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 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

Version 1.3.3        Last change: March 2009                    8

User Manuals                                      RDIFF-BACKUP(1)

          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.

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

          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  tem-
          porary  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  termi-
          nal.   If  missing  the level defaults to the verbosity

          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.

          Create timestamps in which the hour/minute/second sepa-
          rator  is  a  -  (hyphen) instead of a : (colon). It is
          safe to use this option on one backup, and then not use
          it  on another; rdiff-backup supports the intermingling
          of different timestamp formats. This option is  enabled
          by default on platforms which require that the colon be

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

Version 1.3.3        Last change: March 2009                    9

User Manuals                                      RDIFF-BACKUP(1)

          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

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

     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  direc-
     tory,  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  corre-
     sponding  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-

Version 1.3.3        Last change: March 2009                   10

User Manuals                                      RDIFF-BACKUP(1)

     compressed, and have an extra ".gz" to indicate this).  Then

          rdiff-backup           /backup/rdiff-backup-data/incre-
          ments/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.

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

     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  respec-
          tively),  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.

Version 1.3.3        Last change: March 2009                   11

User Manuals                                      RDIFF-BACKUP(1)

     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.

     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, then rdiff-backup runs  'ssh   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 char-
     acter 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  arbi-
     trary  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

Version 1.3.3        Last change: March 2009                   12

User Manuals                                      RDIFF-BACKUP(1)

     the --restrict* options to rdiff-backup.  For more  informa-
     tion,  see  the  web page, the wiki, and the entries for the
     --restrict* options on this man page.

     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 exam-
     ples in the examples.html file included in the  package,  or
     on the web at

     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 selec-
     tion 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  prece-
     dence.  Similarly,

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

Version 1.3.3        Last change: March 2009                   13

User Manuals                                      RDIFF-BACKUP(1)

     would backup the  /usr/local/bin  directory  (and  its  con-
     tents), 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 char-
     acter in the string can be replaced with an upper- or lower-
     case version of itself.

     If you need to match filenames which contain the above glob-
     bing 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:

     pattern can be expanded into the file's filename,

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

     the file is a directory which contains a file matched by the

     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/**'.

Version 1.3.3        Last change: March 2009                   14

User Manuals                                      RDIFF-BACKUP(1)

          --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 directo-
     ries  to  make  sure that included subdirectories have some-
     where to go.  Finally,

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

     would match a file like /usR/5fOO/hello/there/   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 spec-
     ification,  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

     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/doc
     + /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

Version 1.3.3        Last change: March 2009                   15

User Manuals                                      RDIFF-BACKUP(1)

     file list should not  contain  conflicting  file  specifica-

     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

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

     There  can be complications preserving ownership across sys-
     tems.  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

Version 1.3.3        Last change: March 2009                   16

User Manuals                                      RDIFF-BACKUP(1)

          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 --pre-
          serve-numerical-ids and one of the mapping options, the
          behavior is undefined.

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


     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.

     Every session rdiff-backup saves various statistics into two
     files, the session statistics file at rdiff-backup-data/ses-
     sion_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 com-
     pressed to save space.

Version 1.3.3        Last change: March 2009                   17

User Manuals                                      RDIFF-BACKUP(1)

     Statistics-related options  include  --print-statistics  and

     Also,  rdiff-backup  will  save  various messages to the log
     file, which is rdiff-backup-data/backup.log for backup  ses-
     sions  and  rdiff-backup-data/restore.log  for  restore ses-
     sions.  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.

     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 spe-
     cific value).  When setting up rdiff-backup to run automati-
     cally  (as  from  cron(8)  or similar) it is probably a good
     idea to check the exit code.

     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 work-
     around is to disable compression  for  large  uncompressable

     Ben Escoto <>

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

     See  attributes(5)  for  descriptions   of   the   following

     |Availability   | backup/rdiff-backup |
     |Stability      | Uncommitted         |

Version 1.3.3        Last change: March 2009                   18

User Manuals                                      RDIFF-BACKUP(1)

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

     This  software  was   built   from   source   available   at    The  original
     community source was downloaded from  http://download.savan-

     Further  information about this software can be found on the
     open        source        community        website        at

Version 1.3.3        Last change: March 2009                   19