rdiff-backup {{ -l | --list-increments } | --remove-older-than time_interval | --list-at-time time | --list-changed-since time | --list-increment-sizes } [[[user@]host2.foo]::destination_directory ]

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

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

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.

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

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

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

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

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

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

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

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

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

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

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

-V, --version

Print the current version and exit

For example, suppose in the past you have run:

rdiff-backup /usr /usr.backup

One way to do this is to run:

rdiff-backup -r 3D /usr.backup/local /usr/local.old

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

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.

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

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.

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

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