    RDIFF-BACKUP(1)                  User Manuals                  RDIFF-BACKUP(1)

## 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 direc-
           tory  to  another.  The target directory ends up a copy (mirror) of the
           source directory, but extra reverse diffs are stored in a special  sub-
           directory 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, spe-
           cial 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 incre-
                  ment 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 direc-
                  tory 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.  Reg-
                  ular 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 direc-
                  tory  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/per-
                  missions 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 handwrit-
                  ten  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 infor-
                  mation.

           --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 back-
                  ing-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  informa-
                  tion.

           --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 con-
                  tained 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 subdirec-
                  tory is allowable; then only the sizes of the mirror and  incre-
                  ments 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.  Nor-
                  mally 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 unnec-
                  essary 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 direc-
                  tory.  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  ar-
                  chive 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-sensi-
                  tive,  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 informa-
                  tion 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,  min-
                  utes,  hours,  days,  weeks, months, or years respectively, or a
                  number of these concatenated.  For example, 32m  means  32  min-
                  utes,  and 3W2D10h7s means 3 weeks, 2 days, 10 hours, and 7 sec-
                  onds.  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  opera-
                  tion.  Thus if you deleted a file two weeks ago, backed up imme-
                  diately 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  compres-
                  sion.   --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 informa-
                  tion.

           --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 file-
                  name.  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  com-
                  puting 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/incre-
           ments/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/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.

## 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  file-
           names  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, read-
           ing 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  prepend-
           ing  a  backslash.  So in 'a\::b::c', host_info is 'a::b' and the path-
           name 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 exam-
           ples  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  condi-
           tions,  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 pat-
           terns can contain the special patterns *, **, ?, and [...].   As  in  a
           normal  shell,  *  can be expanded to any string of characters not con-
           taining "/", ?  expands to any character except "/", and [...]  expands
           to a single character of those characters specified (ranges are accept-
           able).  The new special pattern, **, expands to any string  of  charac-
           ters  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 charac-
           ters,  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 con-
           ditions.   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 specifi-
           cation  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 inter-
           preted 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 expres-
           sion.  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  restor-
           ing):

           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 own-
                  ership 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  over-
                  ride  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 ":", fol-
           lowed 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_statis-
           tics.<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-sepa-
           rator.

           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  (usu-
           ally  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 (snap-
           shots 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.

    Version 1.2.3                    DECEMBER 2008                 RDIFF-BACKUP(1)