# rdiff-backup(1) [debian man page]

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 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 direc-
tories 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  cor-
rectly.

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

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

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

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  ()	instead of newlines (
) 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

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

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

--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 concate-
nated.  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  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	of
defense so please don't do something silly like allow public access to an rdiff-backup server run with --restrict-read-only.

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/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/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 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 cur-
rent time by the length of the interval.	For instance, "1h78m" indicates the time that was one hour and 78 minutes ago.	The calen-
dar 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,  rela-
tive 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 cur-
rent 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 arbi-
trary 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::ar'.  To make things more complicated, because	the  back-
slash  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 speci-
fied 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 selec-
tion  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
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.  Simi-
larly, 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  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 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 --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:

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

Version 1.2.8							    March 2009							   RDIFF-BACKUP(1)