xenial (1) rdiff-backup.1.gz

Provided by: rdiff-backup_1.2.8-7_amd64 bug

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.