.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-changed-since " time } .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 exacty copy (mirror) of the source directory, but extra reverse diffs are stored in the 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 (if it is running as root), 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. .SH OPTIONS .TP .B -b, --backup-mode Force backup mode even if first argument appears to be an increment 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 .BI "--chars-to-quote " chars If this option is set, any characters in .I chars present in filenames on the source side will be quoted on the destination side, so that they do not appear in filenames on the remote side. See .B --quoting-char and .BR --windows-mode . .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 .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 .BI "--exclude-filelist " filename Excludes the files listed in .I filename 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 .BI "--exclude-mirror " regexp Exclude files in the mirror area matching regexp. This argument can be used multiple times. The rdiff-backup-data directory is automatically excluded, so this option rarely needs to be used. .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, fifos, sockets, and symlinks. This option is implied by --windows-mode. .TP .B --force Authorize the updating or overwriting of a destination path. rdiff-backup will generally tell you if it needs this. .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. 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. .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 .BI "--list-changed-since " time List the files that have changed since the given time. See .B TIME FORMATS for the format of .IR time . .TP .B "-l, --list-increments" List the number and date of partial incremental backups contained in the specified destination directory. This option is incompatible with backing up or restoring and must be run in a separate instance of rdiff-backup. .TP .B "-m, --mirror-only" Do not create an rdiff-backup-data directory or make any increments. In this mode rdiff-backup is similar to rsync (but usually slower). .TP .B --no-compare-inode This relative 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 is "(?i).*\\.(gz|z|bz|bz2|tgz|zip|rpm|deb|jpg|gif|png|jp2|mp3|ogg|avi|wmv|mpeg|mpg|rm|mov)$" .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 increase 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 "--quoting-char " char Use the specified character for quoting characters specified to be escaped by the .B --chars-to-quote option. The default is the semicolon ";". See also .BR --windows-mode . .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-cmd " command This command has been depreciated as of version 0.4.1. Use --remote-schema instead. .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. Note that this option is incompatible with backing up or restoring and must be run in a separate instance of rdiff-backup. Remember also that snapshots of deleted files are covered by this operation, so if you deleted a file and backed up two weeks ago, and then run --remove-older-than 10D today, no trace of that file will remain. .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 -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 .TP .B --windows-mode This option is short for "--chars to quote A-Z: --windows-time-format --no-hard-links --exclude-special-files" and is appropriate when backing a normal unix file system to one that doesn't allow colons in filenames, is not case sensitive, and cannot store special files or hard links. If this switch is used for backing up, it must also be used when restoring, listing increments, etc. .SH EXAMPLES Simplest case---backup directory foo to directory bar, with increments in bar/rdiff-backup-data: .PP .RS rdiff-backup foo bar .PP .RE This is exactly the same as previous example because trailing slashes are ignored: .PP .RS rdiff-backup foo/ bar/ .PP .RE Back files up from /home/bob to /mnt/backup, leaving increments in /mnt/backup/rdiff-backup-data. Do not back up directory /home/bob/tmp or any files in it. .PP .RS rdiff-backup --exclude /home/bob/tmp /home/bob /mnt/backup .PP .RE The file selection options can be combined in various ways. The following command backs up the whole file system to /usr/local/backup. However, the entire /usr directory is skipped, with the exception of /usr/local, which is included, except for /usr/local/backup, which is excluded to prevent a circularity: .PP .RS rdiff-backup --exclude /usr/local/backup --include /usr/local --exclude /usr / /usr/local/backup .PP .RE You can also use regular expressions in the --exclude statements. This will skip any files whose full pathnames contain the word "cache", or any files whose name is "tmp", "temp", "TMP", "tEmP", etc. .PP .RS rdiff-backup --exclude-regexp cache --exclude-regexp '(?i)/te?mp$' /home/bob /mnt/backup .PP .RE After the previous command was completed, this command will list the backups present on the destination disk: .PP .RS rdiff-backup --list-increments /mnt/backup .PP .RE If space is running out on the /mnt/backup directory, older incremental backups can be erased. The following command erases backup information older than a week: .PP .RS rdiff-backup --remove-older-than 7D /mnt/backup .PP .RE The following reads the file important-data.2001-07-15T04:09:38-07:00.dir and restores the resulting directory important-data as it was on Februrary 14, 2001, calling the new directory "temp". Note that rdiff-backup goes into restore mode because it recognizes the suffix of the file. The -v9 means keep lots of logging information. .PP .RS rdiff-backup -v9 important-data.2001-07-15T04:09:38-07:00.dir temp .PP .RE This command causes rdiff-backup to backup the directory /some/local-dir to the directory /whatever/remote-dir on the machine hostname.net. It uses ssh to open the necessary pipe to the remote copy of rdiff-backup. Here the username on the local machine and on hostname.net are the same. .PP .RS rdiff-backup /some/local-dir hostname.net::/whatever/remote-dir .PP .RE This command logs into hostname.net as smith and restores the remote increment old-file on a remote computer to the current directory on the local computer: .PP .RS rdiff-backup smith@hostname.net::/foo/rdiff-backup-data/increments/bar/old-file.2001-11-09T12:43:53-04:00.diff .PP .RE Backup foo on one remote machine to bar on another. This will probably be slower than running rdiff-backup from either machine. .PP .RS rdiff-backup smith@host1::foo jones@host2::bar .PP .RE Test to see if the specified ssh command really opens up a working rdiff-backup server on the remote side. .RS rdiff-backup --test-server hostname.net::/ignored .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.