[Rdiff-backup-commits] Changes to rdiff-backup/rdiff-backup.1 [r1-0]

[Ben Escoto]

Index: rdiff-backup/rdiff-backup.1
diff -u /dev/null rdiff-backup/rdiff-backup.1:1.65.2.1
--- /dev/null   Tue Oct 25 06:36:07 2005
+++ rdiff-backup/rdiff-backup.1 Tue Oct 25 06:36:04 2005
@@ -0,0 +1,925 @@
+.TH RDIFF-BACKUP 1 "AUGUST 2001" "Version 0.2.1" "User Manuals" \" -*- nroff 
-*-
+.SH NAME
+rdiff-backup \- local/remote mirror and incremental backup
+.SH SYNOPSIS
+.B rdiff-backup
+.BI [ options ]
+.BI [[[ user@ ] host1.foo ]:: source_directory ]
+.BI [[[ user@ ] host2.foo ]:: destination_directory ]
+
+.B rdiff-backup
+.B {{ -l | --list-increments }
+.BI "| --remove-older-than " time_interval
+.BI "| --list-at-time " time
+.BI "| --list-changed-since " time
+.B "| --list-increment-sizes "}
+.BI [[[ user@ ] host2.foo ]:: destination_directory ]
+
+.B rdiff-backup --calculate-average
+.I statfile1 statfile2 ...
+
+.B rdiff-backup --test-server
+.BI [ user1 ] @host1.net1 :: path
+.BI [[ user2 ] @host2.net2 :: path ]
+.I ...
+
+.SH DESCRIPTION
+.B rdiff-backup
+is a script, written in
+.BR 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.
+
+.B rdiff-backup
+can also operate
+in a bandwidth efficient manner over a pipe, like
+.BR 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
+.B rdiff-backup
+is installed in the user's PATH on the remote system.  For information
+on other options, see the section on
+.B REMOTE OPERATION.
+
+Note that you
+.B 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.
+
+.SH OPTIONS
+.TP
+.B -b, --backup-mode
+Force backup mode even if first argument appears to be an increment or
+mirror file.
+.TP
+.B --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.
+.TP
+.B --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.
+.TP
+.B --compare
+This is equivalent to
+.BI '--compare-at-time " now" '
+.TP
+.BI "--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.
+.TP
+.BI "--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.
+.TP
+.BI "--current-time " seconds
+This option is useful mainly for testing.  If set, rdiff-backup will
+it for the current time instead of consulting the clock.  The argument
+is the number of seconds since the epoch.
+.TP
+.BI "--exclude " shell_pattern
+Exclude the file or files matched by
+.IR shell_pattern .
+If a directory is matched, then files under that directory will also
+be matched.  See the
+.B FILE SELECTION
+section for more information.
+.TP
+.B "--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.
+.TP
+.B "--exclude-fifos"
+Exclude all fifo files.
+.TP
+.BI "--exclude-filelist " filename
+Excludes the files listed in 
+.IR filename .
+If
+.I filename
+is handwritten you probably want
+.B --include-globbing-filelist
+instead.  See the
+.B FILE SELECTION
+section for more information.
+.TP
+.B --exclude-filelist-stdin
+Like
+.B --exclude-filelist,
+but the list of files will be read from standard input.  See the
+.B FILE SELECTION
+section for more information.
+.TP
+.BR "--exclude-globbing-filelist " filename
+Like
+.B --exclude-filelist
+but each line of the filelist will be interpreted according to the
+same rules as
+.B --include
+and
+.B --exclude.
+.TP
+.B --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.
+.TP
+.BI "--exclude-regexp " regexp
+Exclude files matching the given regexp.  Unlike the
+.B --exclude
+option, this option does not match files in a directory it matches.
+See the
+.B FILE SELECTION
+section for more information.
+.TP
+.B --exclude-special-files
+Exclude all device files, fifo files, socket files, and symbolic links.
+.TP
+.B "--exclude-sockets"
+Exclude all socket files.
+.TP
+.B "--exclude-symbolic-links"
+Exclude all symbolic links.
+.TP
+.B --force
+Authorize the updating or overwriting of a destination path.
+rdiff-backup will generally tell you if it needs this.
+.TP
+.BI "--group-mapping-file " filename
+Map group names and ids according the the group mapping file
+.IR filename .
+See the
+.B USERS AND GROUPS
+section for more information.
+.TP
+.BI "--include " shell_pattern
+Similar to
+.B --exclude
+but include matched files instead.  Unlike
+.BR --exclude ,
+this option will also match parent directories of matched files
+(although not necessarily their contents).  See the
+.B FILE SELECTION
+section for more information.
+.TP
+.BI "--include-filelist " filename
+Like
+.BR --exclude-filelist ,
+but include the listed files instead.  If
+.I filename
+is handwritten you probably want
+.B --exclude-globbing-filelist
+instead.  See the
+.B FILE SELECTION
+section for more information.
+.TP
+.B --include-filelist-stdin
+Like
+.BR --include-filelist ,
+but read the list of included files from standard input.
+.TP
+.BI "--include-globbing-filelist " filename
+Like
+.B --include-filelist
+but each line of the filelist will be interpreted according to the
+same rules as
+.B --include
+and
+.B --exclude.
+.TP
+.BI "--include-regexp " regexp
+Include files matching the regular expression
+.IR regexp .
+Only files explicitly matched by
+.I regexp
+will be included by this option.  See the
+.B FILE SELECTION
+section for more information.
+.TP
+.B --include-special-files
+Include all device files, fifo files, socket files, and symbolic links.
+.TP
+.B --include-symbolic-links
+Include all symbolic links.
+.TP
+.BI "--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.
+.TP
+.BI "--list-changed-since " time
+List the files that have changed in the destination directory since
+the given time.  See
+.B TIME FORMATS
+for the format of
+.IR 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.
+.TP
+.B "-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.
+.TP
+.B --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.
+.TP
+.B --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.
+.TP
+.B --no-compare-inode
+This relatively esoteric option prevents rdiff-backup from flagging a
+file as changed when its inode changes.  This option may be useful if
+you are backing up two different directories to the same rdiff-backup
+destination directory.  The downside is that hard link information may
+get messed up, as the metadata file may no longer have the correct
+inode information.
+.TP
+.B --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.
+.TP
+.B "--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.
+.TP
+.B --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.
+.TP
+.BI --no-hard-links
+Don't replicate hard links on destination side.  Note that because
+metadata is written to a separate file, hard link information will not
+be lost even if the --no-hard-links option is given (however, mirror
+files will not be linked).  If many hard-linked files are present,
+this option can drastically decrease memory usage.
+.TP
+.B --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.
+.TP
+.B --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
+.B -l
+or
+.B --list-increments
+switches, where the time will be given in seconds since the epoch.
+.TP
+.B --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
+.B STATISTICS
+section for more information.
+.TP
+.BI "-r, --restore-as-of " restore_time
+Restore the specified directory as it was as of
+.IR restore_time .
+See the
+.B TIME FORMATS
+section for more information on the format of
+.IR restore_time ,
+and see the
+.B RESTORING
+section for more information on restoring.
+.TP
+.BI "--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
+.B REMOTE OPERATION
+section for more information.
+.TP
+.BI "--remove-older-than " time_spec
+Remove the incremental backup information in the destination directory
+that has been around longer than the given time.
+.I 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.  If you want to, for instance, backup a directory and
+remove old files in it, you must run rdiff-backup twice.
+
+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.
+.TP
+.BI "--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
+.B 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.
+.TP
+.BI "--restrict-read-only " path
+Like
+.BR --restrict ,
+but also reject all write requests.
+.TP
+.BI "--restrict-update-only " path
+Like
+.BR --restrict ,
+but only allow writes as part of an incremental backup.  Requests for other 
types of writes (for instance, deleting 
+.IR path )
+will be rejected.
+.TP
+.B --server
+Enter server mode (not to be invoked directly, but instead used by
+another rdiff-backup process on a remote computer).
+.TP
+.B --ssh-no-compression
+When running ssh, do not use the -C option to enable compression.
+.B --ssh-no-compression
+is ignored if you specify a new schema using
+.B --remote-schema.
+.TP
+.BI "--terminal-verbosity " [0-9]
+Select which messages will be displayed to the terminal.  If missing
+the level defaults to the verbosity level.
+.TP
+.B --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.
+.TP
+.BI "--user-mapping-file " filename
+Map user names and ids according to the user mapping file
+.IR filename .
+See the
+.B USERS and GROUPS
+section for more information.
+.TP
+.BI -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.
+.TP
+.B "-V, --version"
+Print the current version and exit
+
+.SH 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
+.B -r
+or
+.B --restore-as-of
+options.  Secondly, you can run it on an increment file.
+.PP
+For example, suppose in the past you have run:
+.PP
+.RS
+rdiff-backup /usr /usr.backup
+.PP
+.RE
+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.
+.PP
+One way to do this is to run:
+.PP
+.RS
+rdiff-backup -r 3D /usr.backup/local /usr/local.old
+.PP
+.RE
+where above the "3D" means 3 days (for other ways to specify the time,
+see the
+.B TIME FORMATS
+section).  The /usr.backup/local directory was selected, because that
+is the directory containing the current version of /usr/local.
+.PP
+Note that the option to
+.B --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.
+.PP
+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:
+.PP
+.RS
+rdiff-backup /backup/rdiff-backup-data/increments/usr/local.<time>.dir 
/usr/local.old
+.PP
+.RE
+would also restore the file as desired.
+.PP
+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.
+
+.SH 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.
+.PP
+Secondly, the
+.BI -r , " --restore-as-of" ", and " --remove-older-than
+options take a time string, which can be given in any of several
+formats:
+.IP 1.
+the string "now" (refers to the current time)
+.IP 2.
+a sequences of digits, like "123456890" (indicating the time in
+seconds after the epoch)
+.IP 3.
+A string like "2002-01-25T07:00:00+02:00" in datetime format 
+.IP 4.
+An interval, which is a number followed by one of the characters s, m,
+h, D, W, M, or Y (indicating seconds, minutes, hourse, 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.
+.IP 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.
+.IP 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.
+
+.SH 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.
+.PP
+The default remote schema is 'ssh -C %s rdiff-backup --server' where
+host_info is substituted for '%s'.  So if the host_info is
address@hidden, then rdiff-backup runs 'ssh address@hidden rdiff-backup
+--server'.  Using --remote-schema, rdiff-backup can invoke an
+arbitrary command in order to open up a remote pipe.  For instance,
+.RS
+rdiff-backup --remote-schema 'cd /usr; %s' foo 'rdiff-backup
+--server'::bar
+.RE
+is basically equivalent to (but slower than)
+.RS
+rdiff-backup foo /usr/bar
+.RE
+.PP
+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 arbitary server files by "backing up" over
+them.  Such a setup can be made more secure by using the sshd
+configuration option
+.B command="rdiff-backup --server"
+possibly along with the
+.B --restrict*
+options to rdiff-backup.  For more information, see the web page, the
+wiki, and the entries for the
+.B --restrict*
+options on this man page.
+
+.SH FILE SELECTION
+.B rdiff-backup
+supports file selection options similar to (but different from)
+.BR rsync (1).
+When rdiff-backup is run, it searches through the given source
+directory and backs up all the files specified by the file selection
+system.  The system may appear complicated, but it is supposed to be flexible
+and easy-to-use.
+
+The file selection system comprises a number of file
+selection conditions, which are set using one of the following command
+line options:
+.BR --exclude , --exclude-filelist ,
+.BR --exclude-device-files , --exclude-fifos ,
+.BR --exclude-sockets , --exclude-symbolic-links ,
+.BR --exclude-globbing-filelist ,
+.BR --exclude-filelist-stdin , --exclude-regexp , --exclude-special-files ,
+.BR --include ,
+.BR --include-filelist , --include-globbing-filelist ,
+.BR --include-filelist-stdin ,
+and
+.BR --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,
+.PP
+.RS
+rdiff-backup --include /usr --exclude /usr /usr /backup
+.PP
+.RE
+is exactly the same as
+.PP
+.RS
+rdiff-backup /usr /backup
+.PP
+.RE
+because the include and exclude directives match exactly the same
+files, and the
+.B --include
+comes first, giving it precedence.  Similarly,
+.PP
+.RS
+rdiff-backup --include /usr/local/bin --exclude /usr/local /usr /backup
+.PP
+.RE
+would backup the /usr/local/bin directory (and its contents), but not
+/usr/local/doc.
+
+The
+.BR include ,
+.BR exclude ,
+.BR include-globbing-filelist ,
+and
+.B exclude-globbing-filelist
+options accept
+.IR "extended shell globbing patterns" .
+These patterns can contain the special patterns
+.BR * ,
+.BR ** ,
+.BR ? ,
+and
+.BR [...] .
+As in a normal shell,
+.B *
+can be expanded to any string of characters not containing "/",
+.B ?
+expands to any character except "/", and
+.B [...]
+expands to a single character of those characters specified (ranges
+are acceptable).  The new special pattern,
+.BR ** ,
+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.
+
+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
+.BI "--exclude " pattern
+option matches a file iff:
+.TP
+.B 1.
+.I pattern
+can be expanded into the file's filename, or
+.TP
+.B 2.
+the file is inside a directory matched by the option.
+.PP
+.RE
+Conversely,
+.BI "--include " pattern
+matches a file iff:
+.TP
+.B 1.
+.I pattern
+can be expanded into the file's filename,
+.TP
+.B 2.
+the file is inside a directory matched by the option, or
+.TP
+.B 3.
+the file is a directory which contains a file matched by the option.
+.PP
+.RE
+For example,
+.PP
+.RS
+.B --exclude
+/usr/local
+.PP
+.RE
+matches /usr/local, /usr/local/lib, and /usr/local/lib/netscape.  It
+is the same as --exclude /usr/local --exclude '/usr/local/**'.
+.PP
+.RS
+.B --include
+/usr/local
+.PP
+.RE
+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,
+.PP
+.RS
+.B --include
+ignorecase:'/usr/[a-z0-9]foo/*/**.py'
+.PP
+.RE
+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
+.BR --include-filelist ,
+.BR --exclude-filelist ,
+.BR --include-filelist-stdin ,
+and
+.B --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
+.I extended shell patterns
+are, with a few exceptions:
+.TP
+.B 1.
+Globbing patterns like
+.BR * ,
+.BR ** ,
+.BR ? ,
+and
+.B [...]
+are not expanded.
+.TP
+.B 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.
+.TP
+.B 3.
+Lines starting with "+ " are interpreted as include directives, even
+if found in a filelist referenced by
+.BR --exclude-filelist .
+Similarly, lines starting with "- " exclude files even if they are
+found within an include filelist.
+
+.RE
+For example, if the file "list.txt" contains the lines:
+
+.RS
+/usr/local
+.RE
+.RS
+- /usr/local/doc
+.RE
+.RS
+/usr/local/bin
+.RE
+.RS
++ /var
+.RE
+.RS
+- /var
+
+.RE
+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
+.B --include-globbing-filelist
+and
+.B --exclude-globbing-filelist
+options also specify filelists, but each line in the filelist will be
+interpreted as a globbing pattern the way
+.B --include
+and
+.B --exclude
+options are interpreted (although "+ " and "- " prefixing is still
+allowed).  For instance, if the file "globbing-list.txt" contains the
+lines:
+
+.RE
+.RS
+dir/foo
+.RE
+.RS
++ dir/bar
+.RE
+.RS
+- **
+
+.RE
+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
+.B --include-regexp
+and
+.B --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
+.B --include
+and
+.B --exclude
+options, the regular expression options don't match files containing
+or contained in matched files.  So for instance
+.PP
+.RS
+--include '[0-9]{7}(?!foo)'
+.PP
+.RE
+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.
+
+.SH 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:
+
+.TP
+.B 1.
+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.
+.TP
+.B 2.
+If this fails (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.
+.TP
+.B 3.
+However, the
+.B --user-mapping-file
+and
+.B --group-mapping-file
+options can override this behavior.  If either of these options is
+given, the policy descriped in 1 and 2 above will be followed, but
+with the mapped user and group instead of the original.
+
+.RE
+The user and group mapping files both have the same form:
+
+.RS
+old_name_or_id1:new_name_or_id1
+.RE
+.RS
+old_name_or_id2:new_name_or_id2
+.RE
+.RS
+<etc>
+.RE
+
+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.
+
+.SH 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
+.B --print-statistics
+and
+.BR --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 diplayed to
+stdout or stderr, although this can be changed with the
+.B --terminal-verbosity
+option.
+
+The log file is not compressed and can become quite large if
+rdiff-backup is run with high verbosity.
+
+.SH EXIT STATUS
+If rdiff-backup finishes successfully, the exit status will be 0.  If
+there is an 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
+.BR cron (8)
+or similar) it is probably a good idea to check the exit code.
+
+.SH BUGS
+rdiff-backup uses the shell command
+.BR mknod (1)
+to backup device files (e.g. /dev/ttyS0), so device files won't be
+handled correctly on systems with non-standard mknod syntax.
+.PP
+Files whose names are close to the maximum length (e.g. 235 chars if
+the maximum is 255) may be skipped because the filenames of related
+increment files would be too long.
+.PP
+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.
+
+.SH AUTHOR
+Ben Escoto <address@hidden>
+.PP
+Feel free to ask me questions or send me bug reports, but you may want to see 
the web page, mentioned below, first.
+
+.SH SEE ALSO
+.BR python (1),
+.BR rdiff (1),
+.BR rsync (1),
+.BR ssh (1).
+The main rdiff-backup web page is at
+.IR http://www.nongnu.org/rdiff-backup/ .
+It has more information, links to the mailing list and CVS, etc.
+