RDIFF-BACKUP(1)

📦
version 2.2.6 · 7 versions
, in alpine 3.22, alpine 3.23, alpine 3.24, epel 10, epel 9, fedora 43, fedora 44, nixos 26.05, nixpkgs unstable, opensuse-leap 16.0

💖 RDIFF-BACKUP 💖

okay bestie, you're looking at rdiff-backup from Manual 2.2.6 — it's the local/remote mirror and incremental backup queen 👑

✨ NAME ✨

rdiff-backup — local/remote mirror and incremental backup 🪞➕📈

🎀 SYNOPSIS 🎀

rdiff-backup [options...] action [sub-options...] [locations...]
rdiff-backup [--new] [-h|--help|-V|--version]

🦋 DESCRIPTION 🦋

So rdiff-backup is a script, written in python(1), that backs up one directory to another. The target directory ends up being a copy (a mirror) of the source directory, but plot twist — extra reverse diffs get stored in a special sub-directory of that target directory, so you can still recover files you lost a while ago. The whole idea? Combine the best features of a mirror and an incremental backup. it's giving genius fr fr. 💅

It also preserves symlinks, special files, hardlinks, permissions, uid/gid ownership, and modification times. no cap. 🔥

rdiff-backup can also operate in a bandwidth efficient manner over a pipe, just like rsync(1). So 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. Peep the REMOTE OPERATION section for the details. 👀

⚠️ okay so lowkey important: 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. like, actually don't. 😭

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 file included in the rdiff-backup distribution. 🍼

The rdiff-backup commands knows four types of parameters:

  1. generic options valid for all actions,
  2. one action out of backup, calculate, complete, compare, info, list, regress, remove, restore, server, test, verify,
  3. sub-options applicable to each action specifically, even though some are common to multiple actions,
  4. zero, one, two or more location paths, either local or remote.

Note that this documents the new command line interface of rdiff-backup since 2.1+; for the traditional one, check rdiff-backup-old(1) but consider that it is deprecated and will disappear. bestie, it's over for the old one 💀

🌸 Generic options 🌸

  • -h, --help — Prints brief usage information and exits. Add --new to be sure to get this CLI description, and not the old one. Placed after the action, outputs the action's specific help message. 🆘
  • -V, --version — Prints the current version number and exits.
  • --api-version apiversion — Sets the API version to the given integer between minimum and maximum versions as given by the info action. It is the responsibility of the user to make sure that this version is also supported by any server started by this client. 👑 (yes, you are responsible, not the software.)
  • --chars-to-quote, --override-chars-to-quote chars — 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 quote other characters or force quoting, e.g. in case rdiff-backup doesn't recognize a case-insensitive file system, you need to specify this option. chars is a string of characters fit to be used in regexp square brackets (e.g. 'A-Z' as in '[A-Z]').
🚨 Caution 🚨 do NOT change the chars to quote within the same repository! Actually, you only need to set this parameter when creating a new backup repository. Do also NOT quote any character used by rdiff-backup in rdiff-backup-data (any of 'a-z0-9._-')! 🙈
  • --current-time currenttime — 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. ⏰
  • --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). rdiff-backup will generally tell you if it needs this.
🚨 Caution 🚨 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. like, absolutely. 💀
  • --fsync, --no-fsync — This will enable/disable issuing fsync from rdiff-backup altogether. This option is designed to optimize performance on busy backup systems. 🏎️
🚨 Caution 🚨 This may render your backup unusable in case of filesystem failure. Default is hence for fsync to be enabled. 🫶
  • --new, --no-new — enforce (or not) the usage of the new parameters. The default currently is to show the old usage, but this will change in the near future. 👀
  • --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 files statistics. 🧵
  • --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 list increments action, where the time will be given in seconds since the epoch. 🤖 (robot mode, slay)
  • --remote-schema remoteschema — 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 details. 🌐
  • --remote-tempdir dirpath — use path as temporary directory on the remote side of the connection. If set explicitly, remember that "no space left" error messages might apply to this directory. 🗂️
  • --ssh-compression, --no-ssh-compression — use SSH with or without compression with default remote-schema. This option is ignored when using --remote-schema. Compression is on by default. 🗜️
  • --tempdir dirpath — 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. If set explicitly, remember that "no space left" error messages might apply to this directory. 📁
  • --terminal-verbosity {0,1,2,3,4,5,6,7,8,9} — select which verbosity to use for messages on the terminal, the default is given by --verbosity. 📢
  • --use-compatible-timestamps — Create timestamps in which the hour/minute/second separator is a - (hyphen) instead of a : (colon). It is safe to use this option on one backup, and then not use it on another; rdiff-backup supports the intermingling of different timestamp formats. This option is enabled by default on platforms which require that the colon be escaped. 🕰️
  • -v, --verbosity {0,1,2,3,4,5,6,7,8,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, and without using --terminal-verbosity to the terminal.. 🔊

👑 Actions 👑

🌈 backup

backup [CREATION OPTIONS] [COMPRESSION OPTIONS] [SELECTION OPTIONS] [FILESYSTEM OPTIONS] [USER GROUP OPTIONS] [STATISTICS OPTIONS] sourcedir targetdir

back-up a source directory to a target backup repository. that's the whole job bestie 💖

🌈 calculate

calculate [--method average] statfile1 statfile2 [...]

calculate average across multiple statistics files 📊

  • --method average — there is currently only one method and it is the default, but it might change in the future. 🔮

🌈 complete

complete [--cword index] [--unique|--no-unique] -- words [...]

outputs a list of fitting options given already entered parameters. This option is of no relevance to backup tasks, it is only to be used to support programmatic completion like in bash. See the documentation for more details if you plan to write your own completion code, e.g. for an alternative shell. 🐚

  • --cword index — index where the cursor currently is within the list of words. ⌨️
  • --unique,--no-unique — should parameters already entered by the user be offered again, or not? 🤔

🌈 compare

compare [SELECTION OPTIONS] [--method method] [--at time] sourcedir targetdir

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

  • --method method — method used to compare can be either meta, full or hash, where the default is meta, which is also how rdiff-backup decides which file needs to be backed-up. Note that with full, 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 method. With hash only the SHA1 checksum of regular files will be compared. With meta only the metadata of files will be compared (name, size, date, type, etc). 🧬
  • --at time — at which time of the back-up directory should the comparaison take place. The default is now, meaning the latest version. See TIME FORMATS for details. ⏳

🌈 info

outputs information about the current system in YAML format, so that it can be used in a bug report, and exits. 📝

🌈 list files

list files [--changed-since time|--at time] repository

list modified or existing files in a given back-up repository. 🗃️

  • --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. See TIME FORMATS for details. 🕵️
  • --at 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. See TIME FORMATS for details. 📌

🌈 list increments

list increments [--no-size|--size] repository

list increments with date in a given back-up repository. 📅

  • --no-size, --size — shows (or hides 🫣) the size of every increment chillin' in the repo. Default vibe is no sizes shown. But here's the cute part: once you turn sizes on, you're allowed to point at a directory inside a repository and it'll show you just the cumulated sizes of that directory. Bestie that's so handy.

🩹 regress — the "undo my oopsie" action

regress [COMPRESSION OPTIONS] [USER GROUP OPTIONS] [TIMESTAMP OPTIONS] repository

If an rdiff-backup session fails 😭, this action undoes the failed directory. And honestly? It happens automatically — if you try to back up to a directory and the last backup failed, this just kicks in on its own. You can also use --force to undo the last backup even when it wasn't failed (starting with API 201, use --api-version if you need to).

🗑️ remove increments --older-than time [--size] repository

Remove the incremental backup info in the destination directory that's been hanging around longer than the given time — or the oldest one if you don't provide a time at all.

By default rdiff-backup will only delete info from one session at a time. Wanna remove two or more sessions at once? Supply the --force option (and don't worry, rdiff-backup will literally tell you if it's required 💅).

⚠️ Heads up bestie: snapshots of deleted files are covered by this operation. So if you deleted a file two weeks ago, backed up right after, and then ran rdiff-backup with remove increments --older-than 10D today — no trace of that file would remain. Gone. Poof. ✨
  • --older-than time — all the increments older than the given time get deleted. Peep TIME FORMATS for the details.
  • --size — show the size of each increment being removed. Default is to not show sizes.

🧚 restore — bring it back, bestie

restore [CREATION OPTIONS] [COMPRESSION OPTIONS] [SELECTION OPTIONS] [FILESYSTEM OPTIONS] [USER GROUP OPTIONS] [--at time|--increment] source targetdir

Restores a source backup repository at a specific time, or a specific source increment, into a target directory. Check the RESTORING section for the full tea.

  • --at time — the source parameter gets interpreted as a back-up directory, and the content is restored from the given time. See TIME FORMATS for details.
  • --increment — the source parameter is expected to be an increment inside a back-up repository, and it gets restored into the given target directory.

🖥️ server — remote mode, not your business

server [RESTRICT OPTIONS] [--debug]

Enters server mode. Do not invoke this directly — it's meant to be used by another rdiff-backup process on a remote computer.

🔍 test — is anybody home?

test remote_location_1 [remote_location_2 ...]

Tests for the presence of a compatible rdiff-backup server as specified in the remote location argument(s) — and yes, the filename section gets checked for existence too. See the REMOTE OPERATION section for details.

✅ verify — trust but verify fr fr

verify [--at time] location

Checks all the data in the repository at the given time by computing the SHA1 hash of all the regular files and comparing them against the hashes stored in the metadata file. Iconic behavior honestly.

  • --at time — the time of the data that needs verifying. See TIME FORMATS for details.

🗜️ COMPRESSION OPTIONS 🗜️

  • --compression, --no-compression — enable or 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 hold both compressed and uncompressed increments, so being inconsistent with this option is totally fine, no cap. Default is to compress all files — except those excluded, as noted below.
  • --not-compressed-regexp regexp — do not compress increments based on files whose filenames match regexp. The default covers a bunch of common audiovisual and archive files, and you can find it from the help.

🌱 CREATION OPTIONS 🌱

  • --create-full-path — normally only the final directory of the destination path gets created if it doesn't already exist. With this option, all missing directories on the destination path get created. Use this one with care: if there's a typo in the remote path, the remote filesystem could fill up very quickly (by creating a duplicate backup tree 😭). That's exactly why this option is mainly aimed at scripts that automate backups.

📁 FILESYSTEM OPTIONS 📁

  • --acls, --no-acls — enable/disable back-up of Access Control Lists.
  • --carbonfile, --no-carbonfile — enable/disable back-up of carbon files (MacOS X).
  • --eas, --no-eas — enable/disable back-up of Extended Attributes.
  • --resource-forks, --no-resource-forks — enable/disable back-up of resource forks (MacOS X).
  • --hard-links, --no-hard-links — do (or don't) keep hard-link relationships between files. Disabling hard-links generally increases disk space usage but decreases memory usage. Hard-links are disabled by default if the backup source or restore destination is running on native Windows.
  • --compare-inode, --no-compare-inode — stops rdiff-backup from flagging a hardlinked file as changed when its device number and/or inode changes. Super useful when the source filesystem doesn't have 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 generally have the same inode number); and some filesystems don't even have the same inode numbers from use to use. Without this option, rdiff-backup may generate an unnecessary number of tiny diff files 🫠.
  • --never-drop-acls — exits with an error instead of dropping ACLs or ACL entries. Normally dropping can happen (with a warning) because the destination doesn't support them, or because the relevant user/group names don't exist on the destination side.

🔒 RESTRICT OPTIONS 🔒

  • --restrict-path dirpath — requires that all file access stays inside the given path. This switch, along with --restrict-mode, is intended to be used with the server action to give a bit more protection when doing automated remote backups.
🚨 Caution 🚨 Those options are not intended as your only line of defense. So please, bestie, don't do something silly like allow public access to an rdiff-backup server run with --restrict-mode read-only.
  • --restrict-mode {read-write,read-only,update-only} — the restriction mode for the directory given by --restrict-path: either full access (aka read-write), read-only, or only to update an already existing back-up incrementally. Default is read-write.

🎀 SELECTION OPTIONS 🎀

This section only quickly lists the existing options — the FILE SELECTION section explains them in way more detail.

🌸 Globs, Regex, File lists selection

  • --include, --exclude glob — include/exclude the file or files matched by glob (also known as a shell pattern). If a directory gets excluded, then files under that directory get excluded too.
  • --include-globbing-filelist, --exclude-globbing-filelist globsfile — include/exclude according to the listed globs, similar to --include or --exclude.
  • --include-globbing-filelist-stdin, --exclude-globbing-filelist-stdin — like the previous option, but the list of globs comes from standard input.
  • --include-regexp, --exclude-regexp regexp — include/exclude files matching the given regexp (according to Python rules).
  • --include-filelist, --exclude-filelist listfile — include/exclude the files listed in filelist. This is the best fit for an automatically generated list of files — otherwise, use globbing.
  • --include-filelist-stdin, --exclude-filelist-stdin — like the previous one, but the filelist comes from standard input.

🦋 Special files selection

📝 Note All special files are included by default, so explicitly including them isn't generally required. Exceptions are described below.
  • --include-device-files, --exclude-device-files — include/exclude all device files. Useful for security/permissions reasons, or if rdiff-backup isn't handling device files correctly.
  • --include-fifos, --exclude-fifos — include/exclude all fifo files.
  • --include-sockets, --exclude-sockets — include/exclude all socket files.
  • --include-symbolic-links, --exclude-symbolic-links — include/exclude all symbolic links. Contrary to the general rule, symlinks are excluded by default under Windows so that NTFS reparse points aren't backed-up.
  • --include-special-files, --exclude-special-files — include/exclude all the special files listed above.

🌈 Other selections

  • --include-other-filesystems, --exclude-other-filesystems — include/exclude files on file systems (identified by device number) other than the file system that the root of the source directory is on. Default is to include other filesystems.
  • --include-if-present, --exclude-if-present filename — include/exclude directories if they contain the given filename. Files directly inside an included directory are also considered included. This doesn't apply recursively though, so the filename must be present in all directories of a hierarchy for it to be fully included.
  • --max-file-size sizeinbytes — exclude files that are larger than the given size in bytes.
  • --min-file-size sizeinbytes — exclude files that are smaller than the given size in bytes.

📊 STATISTICS OPTIONS 📊

  • --file-statistics, --no-file-statistics — enable/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. Default is to write the statistics file(s).

See the FILES section for more info about statistics files.

  • --no-print-statistics, --print-statistics — summary statistics get printed (or not) after a successful backup. Even if it's disabled (which is the default), this info is still available from the session statistics file. Slay. 💅

⏰ TIMESTAMP OPTIONS ⏰

so this section is one option and it is not your everyday vibe — it's a rescue mission, bestie 🚑

  • --allow-duplicate-timestamps — okay so you ONLY reach for this one if you've hit the cursed situation of metadata mirrors carrying the same timestamp. If that's you, this flag lets you first recover from the failed backup with something like:
rdiff-backup regress --allow-duplicate-timestamps {targetdir}

and after that you still have to go clean up those old duplicate entries using the remove increments action. it's giving ✨two-step✨, no skipping ahead 💅

👥 USER GROUP OPTIONS 👥

if you want the whole story, the USERS AND GROUPS section is right there waiting for you 💖

  • --group-mapping-file mapfile — maps group names and IDs following whatever the group mapping file mapfile says 🌸
  • --user-mapping-file mapfile — maps user names and IDs following whatever the user mapping file mapfile says 🦋
  • --preserve-numerical-ids — if you set this, rdiff-backup preserves uids/gids instead of trying to preserve unames and gnames. numbers over names, periodt 🔢

🌸 RESTORING 🌸

bestie there are literally two ways to tell rdiff-backup to restore a file or directory, and they're both valid:

  1. you can run rdiff-backup restore on a mirror file and define a time to restore from (by default it grabs the latest one) ⏱️
  2. you can run the restore action on an increment file with the sub-option --increment 📂

okay so imagine that in the past you ran:

rdiff-backup backup /usr /usr.backup

to back up the /usr directory into /usr.backup, and now you want a copy of the /usr/local directory exactly how it was 3 days ago, dropped at /usr/local.old 👑

one way to do that is:

rdiff-backup restore --at 3D /usr.backup/local /usr/local.old

up there the 3D means 3 days (for all the other ways to say a time, go peek at the TIME FORMATS section, it's right below). and why /usr.backup/local? because that's the directory holding the current version of usr/local 💡

heads up: the parameter of --at always means an exact time. so 3D is the moment exactly 72 hours before right now. if no backup happened at that moment, rdiff-backup restores the state recorded for the previous backup. so in the case above, if 3D is used and the only backups are from 2 days and 4 days ago, you get /usr/local as it was 4 days ago. not what you asked for but that's the deal 🫠

the second way to restore files is to find the corresponding increment file. it would live 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 tells you it's from 3 days ago 🕰️ note that increment files all end in .diff, .snapshot, .dir, or .missing — and .missing just means the file didn't exist at that time (and finally, some of these may be gzip-compressed, and have an extra .gz to say so). then running:

rdiff-backup restore --increment \
    /backup/rdiff-backup-data/increments/usr/local.{time}.dir \
    /usr/local.old

would also restore the file exactly how you wanted ✨

and if you're not sure which version of a file you even need? honestly the easiest move is either restore from the increment files like just described, or check which increments exist with list increments, and then nail down an exact time with --at. you got this 💅

🕰️ TIME FORMATS 🕰️

rdiff-backup uses time strings in two places, bestie:

firstly — every increment file rdiff-backup creates has the time baked into its filename in the w3 datetime format, as described in a w3 note at https://www.w3.org/TR/NOTE-datetime. basically they look like 2001-07-15T04:09:38-07:00, which is basically {Year}-{Month}-{Day}T{Hours}:{Minutes}:{Seconds}{Timezone}, the time zone being 7 hours behind UTC in this example (hence the minus) 🌍

secondly — the --at, --changed-since, and --older-than options take a time string, which you can hand over in any of several formats:

  1. the string now (refers to the current time) ⏰
  2. a sequence of digits, like 123456890 (indicating the time in seconds after the epoch) 🔢
  3. a string like 2002-01-25T07:00:00+02:00 in datetime format 📅
  4. an interval, which is a number followed by one of the characters s, m, h, D, W, M, or Y (indicating seconds, minutes, hours, days, weeks, months, or years respectively), or a series of such pairs. in this case the string refers to the time that preceded the current time by the length of the interval. for instance, 1h78m" indicates the time that was one hour and 78 minutes ago. the calendar here is unsophisticated: a month is always 30 days, a year is always 365 days, and a day is always 86400 seconds 🗓️
  5. a date format of the form YYYY/MM/DD, YYYY-MM-DD, MM/DD/YYYY, or MM-DD-YYYY, which indicates midnight on the day in question, relative to the current timezone settings. for instance, 2002/3/5, 03-05-2002, and 2002-3-05 all mean March 5th, 2002 (needless to say that starting with the year is less confusing for non-Americans 🌈)
  6. a backup session specification, which is a non-negative integer followed by B. for instance, 0B specifies the time of the current mirror, and 3B specifies the time of the 3rd newest increment 💫

🌐 REMOTE OPERATION 🌐

to reach remote files, rdiff-backup opens up a pipe to a copy of rdiff-backup running on the remote machine. so yes — rdiff-backup must be installed on both ends, no cap 🫶 to open this pipe, rdiff-backup first splits the location into host_info::pathname. then it substitutes host_info into the remote schema, and runs the resulting command, reading its input and output 🎀

the host_info can be anything your version of SSH understands as a destination. assuming it's the standard OpenSSH, it can be:

  • either [user@]hostname
  • or a URI of the form ssh://[user@]hostname[:port]

the default remote schema is ssh -C {h} rdiff-backup --server where host_info is substituted for {h}. 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 to open up a remote pipe. for instance:

rdiff-backup --remote-schema 'cd /usr; {h}' backup \
                    foo 'rdiff-backup server'::bar

is basically equivalent to (but slower than)

rdiff-backup backup foo /usr/bar

now, the quoting lore 📜 if for some reason you need two consecutive colons inside the host_info section of a host_info::pathname argument, or inside the pathname of a local file, you can quote one of them by prepending a backslash. so in a\::b::c, the 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. and 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 \\\\ at the shell prompt to get a literal backslash 😭

you may also use the placeholders {Vx}, {Vy}, and {Vz} for the x.y.z version of rdiff-backup, so you can have multiple versions of rdiff-backup installed on the server and automatically targeted from the client ✨

for example, if you have rdiff-backup 2.1.5 and 2.2.1 installed in virtual environments on the server, respectively under /usr/local/lib/rdiff-backup-2.0 and /usr/local/lib/rdiff-backup-2.1 (we assume that the z-Version isn't relevant to any kind of compatibility), then the client may be called with the following remote schema:

ssh -C {h} /usr/local/lib/rdiff-backup-{Vx}.{Vy} --server

the client will then use the correct version of rdiff-backup based on its own version x.y.z. you'll find more explanations in the migration file in the documentation 💖

if you need to include a literal % in the string specified by --remote-schema, quote it with another %, as in %% (this is due to the compatibility with the deprecated host placeholder %s, which you shouldn't use anymore) 🚫

and finally, if you need to include literal { } (curly braces) in the string specified by --remote-schema, quote them (both) by doubling each of them up, as in {{ foo=0; }} 🎀

⚠️ okay bestie real talk, security time. 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-path and --restrict-mode options to rdiff-backup. for more information, see the web page, the wiki, and the entries for those options on this man page 🛡️

✨ FILE SELECTION ✨

okay bestie, buckle up, this is the part everyone asks about 💅 rdiff-backup has a whole bunch of file selection options. When you run it, it goes rummaging through the source directory you handed it and backs up every file that matches the options you specified. This selection system looks complicated, lowkey, but it's supposed to be flexible and easy-to-use. If you just want the basics, go peek at the selection examples in the examples file that ships with the package, or online at https://rdiff-backup.net/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. No cap.

Important 🙈 include and exclude patterns under Windows solely support slashes / as file separators, given that backslashes \ have a special meaning in regex/glob patterns.

All the available file selection conditions are listed under SELECTION OPTIONS.

Two principles you gotta understand before you really start, fr fr:

  1. pattern matching is stupid about paths, it just does pattern matching and can't interpret patterns like path, especially it can't resolve absolute into relative paths and vice-versa (compare with the -path option of find).
  2. pattern matching is done on the complete path of each found file (no partial matching and no file name matching). Beware that complete path does not mean full path, it can be a complete relative path.

For example, the pattern bar matches the path bar, but doesn't match the path foo/bar and neither the path ./bar. Both are matched by the pattern */bar, as well as by **/bar. This last pattern would match any path containing the file bar, e.g. foo/boz/bar ⭐

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. iconic behaviour tbh.

For instance,

rdiff-backup backup --include /usr \
                    --exclude /usr /usr /backup

is exactly the same as

rdiff-backup 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 backup --include /usr/local/bin \
                    --exclude /usr/local /usr /backup

would backup the /usr/local/bin directory (and its contents), but not /usr/local/doc.

The include, exclude, include-globbing-filelist, and exclude-globbing-filelist options accept extended shell globbing patterns. These patterns can contain the special patterns *, **, ?, and [...]. As in a normal shell, * can be expanded to any string of characters not containing /, ? expands to any character except /, and [...] expands to a single character of those characters specified (ranges are acceptable). The new special pattern, **, expands to any string of characters whether or not it contains /. Furthermore, if the pattern starts with ignorecase: (case insensitive), then this prefix will be removed and any character in the string can be replaced with an upper or lowercase version of itself. she's flexible like that 💖

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 shell is NOT your friend here, she's a hater 🫶)

The --exclude pattern option matches a file if and only if:

  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 if and only if:

  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/**'

And similarly:

--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 + [...] (plus followed by a space) are interpreted as include directives, even if found in a filelist referenced by --exclude-filelist. Similarly, lines starting with - [...] (minus followed by a space) 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

Then --include-globbing-filelist globbing-list.txt would be exactly the same as specifying on the command line:

--include dir/foo --include dir/bar --exclude **

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. sneaky little regex, we love her 💜

👑 USERS AND GROUPS 👑

There can be complications preserving ownership across systems. For instance the username that owns a file on the source system may not exist on the destination. Here is how rdiff-backup maps ownership on the source to the destination (or vice-versa, in the case of restoring):

  1. If the --preserve-numerical-ids option is given, the remote files will always have the same uid and gid, both for ownership and ACL entries. This may cause unames and gnames to change.
  2. Otherwise, attempt to preserve the user and group names for ownership and in ACLs. This may result in files having different uids and gids across systems.
  3. If a name cannot be preserved (e.g. because the username does not exist), preserve the original id, but only in cases of user and group ownership. For ACLs, omit any entry that has a bad user or group name.
  4. The --user-mapping-file and --group-mapping-file options override this behavior. If either of these options is given, the policy described in 2 and 3 above will be followed, but with the mapped user and group instead of the original. If you specify both --preserve-numerical-ids and one of the mapping options, the behavior is undefined 💀 (do not do this bestie, I'm begging)

The user and group mapping files both have the same format:

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. simple as 🍓

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. (yes this is confusing, no I did not make the rules 😭)

See USER GROUP OPTIONS for a list and description of related options.

💾 FILES 💾

okay so rdiff-backup is literally always leaving little files around for you, and here's the tea on all of them 👇

  • any-config-file — bestie. you can make a file with one option / action / sub-option per line and then use it on the command line with an at sign prefix like @any-config-file, and its content gets interpreted as if you'd typed it on the command line. wild. no cap.

so like, if you create a file called mybackup with this inside:

--verbosity
5
backup
source_dir
target_dir

then calling rdiff-backup @mybackup is exactly the same as calling rdiff-backup --verbosity 5 backup source_dir target_dir. iconic, honestly 💅

  • session_statistics, file_statistics — every single session, rdiff-backup saves its various stats into two files: the session statistics file at rdiff-backup-data/session_statistics.{datetime}.data, and the files statistics at rdiff-backup-data/directory_statistics.{datetime}.data. both are text files and they hold pretty similar info — how many files changed, how many got deleted, the total size of increment files created, etc. ✨

the difference tho: the session statistics file is meant to be very readable and only describes the session as a whole. the files statistics file is more compact (and slightly less readable 🥴) but it describes every directory backed up. it also may be compressed to save space.

also peep STATISTICS OPTIONS and the --null-separator option. iykyk.

  • backup.log, restore.log, error_log — rdiff-backup saves 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 lands in this file coincides with the messages shown on stdout or stderr, though you can change that with the --terminal-verbosity option.

errors during backup also get written to a file rdiff-backup-data/error_log.{datetime}.data. 📝

heads up bestie: the log files are not compressed and can become quite large if rdiff-backup is run with high verbosity. like, she's chatty and she's keeping receipts.

🌸 ENVIRONMENT 🌸

the vibes your shell can set before rdiff-backup even shows up:

  • RDIFF_BACKUP_VERBOSITY=[0-9] — the default verbosity for log file and terminal. can be overwritten by the corresponding options -v/--verbosity and --terminal-verbosity. ✨
  • RDIFF_BACKUP_DEBUG=[address][:port] — sets a non-default listening address and/or port (the default is 127.0.0.1:4444) for rpdb. valid values are address, address:port or :port. 🐛
  • RDIFF_BACKUP_API_VERSION={[dictionary]} — overwrites the actual, default, max and/or min value of the API VERSION using a YAML object, e.g. {actual: 201, default: 201}. this environment variable is rather meant for development and test purposes, to change the values without modifying the code — so use with care, fr fr. 🙈

🚦 RETURN CODES 🚦

real talk: the following return codes have not been fully implemented, so test before you rely on them. also note that they can be combined, so that for example a return code 3 might be returned if a warning was found, then an error. 💀
  • 0 - OK — the action was completely successful 🎉
  • 1 - ERROR — something fatal happened, the whole action failed 😭
  • 2 - WARNING — any kind of unexpected behavior without complete failure 🫠
  • 4 - FILE ERROR — the action failed on a single file (or more), but it wasn't the reason for a complete failure
  • 8 - FILE WARNING — the action stumbled on a single file (or more), or detected differences in a comparaison 👀
Tip 🎀 any other error code can and should be reported as a bug.

🐛 BUGS 🐛

👑 AUTHORS 👑

  • Ben Escoto ben@emerose.org (retired) 🌈
  • Eric Lavarde ewl+rdiffbackup@lavar.de (active) 🔥

🦋 SEE ALSO 🦋

rdiff-backup-old(1), python(1), rdiff(1), rsync(1), ssh(1).

the main rdiff-backup web page is at https://rdiff-backup.net/. it has more documentation, links to the mailing list and source code. go read it bestie, it's giving main character energy 📚✨

and that's the whole page, we did it 🥹💖 this was rdiff-backup from September 2023, page RDIFF-BACKUP(1) — slay, mwah, go back up your stuff 💅🎀

📦 where this page comes from