1RDIFF-BACKUP(1) Manual 2.2.6 RDIFF-BACKUP(1)
2
6 rdiff-backup - local/remote mirror and incremental backup
7
9 rdiff-backup [options...] action [sub-options...] [locations...]
10 rdiff-backup [--new] [-h|--help|-V|--version]
11
13 rdiff-backup is a script, written in python(1) that backs up one
14 directory to another. The target directory ends up a copy (mirror) of
15 the source directory, but extra reverse diffs are stored in a special
16 sub-directory of that target directory, so you can still recover files
17 lost some time ago. The idea is to combine the best features of a
18 mirror and an incremental backup. rdiff-backup also preserves symlinks,
19 special files, hardlinks, permissions, uid/gid ownership, and
20 modification times.
21 rdiff-backup can also operate in a bandwidth efficient manner over a
23 pipe, like rsync(1). Thus you can use ssh and rdiff-backup to securely
24 back a hard drive up to a remote location, and only the differences
25 will be transmitted. Using the default settings, rdiff-backup requires
26 that the remote system accept ssh connections, and that rdiff-backup is
27 installed in the user’s PATH on the remote system. See the REMOTE
28 OPERATION section for details.
29 Note that you should not write to the mirror directory except with
31 rdiff-backup. Many of the increments are stored as reverse diffs, so if
32 you delete or modify a file, you may lose the ability to restore
33 previous versions of that file.
34 Finally, this man page is intended more as a precise description of the
36 behavior and syntax of rdiff-backup. New users may want to check out
37 the examples file included in the rdiff-backup distribution.
38 The rdiff-backup commands knows four types of parameters
40 1. generic options valid for all actions,
42 2. one action out of backup, calculate, complete, compare, info, list,
44 regress, remove, restore, server, test, verify,
45 3. sub-options applicable to each action specifically, even though
47 some are common to multiple actions,
48 4. zero, one, two or more location paths, either local or remote.
50 Note that this documents the new command line interface of rdiff-backup
52 since 2.1+; for the traditional one, check rdiff-backup-old(1) but
53 consider that it is deprecated and will disappear.
54 Generic options
56 -h, --help
57 Prints brief usage information and exits. Add --new to be sure to
58 get this CLI description, and not the old one. Placed after the
59 action, outputs the action’s specific help message.
60 -V, --version
62 Prints the current version number and exits.
63 --api-version apiversion
65 Sets the API version to the given integer between minimum and
66 maximum versions as given by the info action. It is the
67 responsibility of the user to make sure that this version is also
68 supported by any server started by this client.
69 --chars-to-quote, --override-chars-to-quote chars
71 If the filesystem to which we are backing up is not case-sensitive,
72 automatic "quoting" of characters occurs. For example, a file
73 'Developer.doc' will be converted into ';068eveloper.doc'. To quote
74 other characters or force quoting, e.g. in case rdiff-backup
75 doesn’t recognize a case-insensitive file system, you need to
76 specify this option. chars is a string of characters fit to be used
77 in regexp square brackets (e.g. 'A-Z' as in '[A-Z]').
78 Caution
80 do NOT change the chars to quote within the same repository!
81 Actually, you only need to set this parameter when creating a
82 new backup repository. Do also NOT quote any character used by
83 rdiff-backup in rdiff-backup-data (any of 'a-z0-9._-')!
84 --current-time currenttime
86 This option is useful mainly for testing. If set, rdiff-backup will
87 use it for the current time instead of consulting the clock. The
88 argument is the number of seconds since the epoch.
89 --force
91 Authorize a more drastic modification of a directory than usual
92 (for instance, when overwriting of a destination path, or when
93 removing multiple sessions with remove). rdiff-backup will
94 generally tell you if it needs this.
95 Caution
97 You can cause data loss if you mis-use this option.
98 Furthermore, do NOT use this option when doing a restore, as it
99 will DELETE files, unless you absolutely know what you are
100 doing.
101 --fsync, --no-fsync
103 This will enable/disable issuing fsync from rdiff-backup
104 altogether. This option is designed to optimize performance on busy
105 backup systems.
106 Caution
108 This may render your backup unusable in case of filesystem
109 failure. Default is hence for fsync to be enabled.
110 --new, --no-new
112 enforce (or not) the usage of the new parameters. The default
113 currently is to show the old usage, but this will change in the
114 near future.
115 --null-separator
117 Use nulls (\0) instead of newlines (\n) as line separators, which
118 may help when dealing with filenames containing newlines. This
119 affects the expected format of the files specified by the
120 --{include|exclude}-filelist[-stdin] switches as well as the format
121 of the files statistics.
122 --parsable-output
124 If set, rdiff-backup’s output will be tailored for easy parsing by
125 computers, instead of convenience for humans. Currently this only
126 applies when listing increments using the list increments action,
127 where the time will be given in seconds since the epoch.
128 --remote-schema remoteschema
130 Specify an alternate method of connecting to a remote computer.
131 This is necessary to get rdiff-backup not to use ssh for remote
132 backups, or if, for instance, rdiff-backup is not in the PATH on
133 the remote side. See the REMOTE OPERATION section for details.
134 --remote-tempdir dirpath
136 use path as temporary directory on the remote side of the
137 connection. If set explicitly, remember that "no space left" error
138 messages might apply to this directory.
139 --ssh-compression, --no-ssh-compression
141 use SSH with or without compression with default remote-schema.
142 This option is ignored when using --remote-schema. Compression is
143 on by default.
144 --tempdir dirpath
146 Sets the directory that rdiff-backup uses for temporary files to
147 the given path. The environment variables TMPDIR, TEMP, and TMP can
148 also be used to set the temporary files directory. See the
149 documentation of the Python tempfile module for more information.
150 If set explicitly, remember that "no space left" error messages
151 might apply to this directory.
152 --terminal-verbosity {0,1,2,3,4,5,6,7,8,9}
154 select which verbosity to use for messages on the terminal, the
155 default is given by --verbosity.
156 --use-compatible-timestamps
158 Create timestamps in which the hour/minute/second separator is a -
159 (hyphen) instead of a : (colon). It is safe to use this option on
160 one backup, and then not use it on another; rdiff-backup supports
161 the intermingling of different timestamp formats. This option is
162 enabled by default on platforms which require that the colon be
163 escaped.
164 -v, --verbosity {0,1,2,3,4,5,6,7,8,9}
166 Specify verbosity level (0 is totally silent, 3 is the default, and
167 9 is noisiest). This determines how much is written to the log
168 file, and without using --terminal-verbosity to the terminal..
169 Actions
171 backup [CREATION OPTIONS] [COMPRESSION OPTIONS] [SELECTION OPTIONS]
172 [FILESYSTEM OPTIONS] [USER GROUP OPTIONS] [STATISTICS OPTIONS]
173 sourcedir targetdir
174 back-up a source directory to a target backup repository.
175 calculate [--method average] statfile1 statfile2 [...]
177 calculate average across multiple statistics files
178 --method average
180 there is currently only one method and it is the default, but
181 it might change in the future.
182 complete [--cword index] [--unique|--no-unique] -- words [...]
184 outputs a list of fitting options given already entered parameters.
185 This option is of no relevance to backup tasks, it is only to be
186 used to support programmatic completion like in bash. See the
187 documentation for more details if you plan to write your own
188 completion code, e.g. for an alternative shell.
189 --cword index
191 index where the cursor currently is within the list of words.
192 --unique,--no-unique
194 should parameters already entered by the user be offered again,
195 or not?
196 compare [SELECTION OPTIONS] [--method method] [--at time] sourcedir
198 targetdir
199 Compare a directory with the backup set at the given time. This can
200 be useful to see how archived data differs from current data, or to
201 check that a backup is current.
202 --method method
204 method used to compare can be either meta, full or hash, where
205 the default is meta, which is also how rdiff-backup decides
206 which file needs to be backed-up. Note that with full, the
207 repository data will be copied in its entirety to the source
208 side and compared byte by byte. This is the slowest but most
209 complete compare method. With hash only the SHA1 checksum of
210 regular files will be compared. With meta only the metadata of
211 files will be compared (name, size, date, type, etc).
212 --at time
214 at which time of the back-up directory should the comparaison
215 take place. The default is now, meaning the latest version. See
216 TIME FORMATS for details.
217 info
219 outputs information about the current system in YAML format, so
220 that it can be used in a bug report, and exits.
221 list files [--changed-since time|--at time] repository
223 list modified or existing files in a given back-up repository.
224 --changed-since time
226 List the files that have changed in the destination directory
227 since the given time. See TIME FORMATS for the format of time.
228 If a directory in the archive is specified, list only the files
229 under that directory. This option does not read the source
230 directory; it is used to compare the contents of two different
231 rdiff-backup sessions. See TIME FORMATS for details.
232 --at time
234 List the files in the archive that were present at the given
235 time. If a directory in the archive is specified, list only the
236 files under that directory. See TIME FORMATS for details.
237 list increments [--no-size|--size] repository
239 list increments with date in a given back-up repository.
240 --no-size,--size
242 Show or not the size of each increment in the repository. The
243 default is to not show sizes. When showing sizes, it becomes
244 allowable to specify a directory within a repository, then only
245 the cumulated sizes of that directory will be shown.
246 regress [COMPRESSION OPTIONS] [USER GROUP OPTIONS] [TIMESTAMP OPTIONS]
248 repository
249 If an rdiff-backup session fails, this action will undo the failed
250 directory. This happens automatically if you attempt to back-up to
251 a directory and the last backup failed. You can use the --force
252 option to undo the last backup even if it wasn’t failed (starting
253 with API 201, use --api-version if necessary).
254 remove increments --older-than time [--size] repository
256 Remove the incremental backup information in the destination
257 directory that has been around longer than the given time, or the
258 oldest one if no time is provided.
259 By default, rdiff-backup will only delete information from one
261 session at a time. To remove two or more sessions at the same time,
262 supply the --force option (rdiff-backup will tell you if it is
263 required).
264 Note that snapshots of deleted files are covered by this operation.
266 Thus if you deleted a file two weeks ago, backed up immediately
267 afterwards, and then ran rdiff-backup with 'remove increments
268 --older-than 10D' today, no trace of that file would remain.
269 --older-than time
271 all the increments older than the given time will be deleted.
272 See TIME FORMATS for details.
273 --size
275 Show the size of each increment being removed. The default is
276 to not show sizes.
277 restore [CREATION OPTIONS] [COMPRESSION OPTIONS] [SELECTION OPTIONS]
279 [FILESYSTEM OPTIONS] [USER GROUP OPTIONS] [--at time|--increment]
280 source targetdir
281 restore a source backup repository at a specific time or a specific
282 source increment to a target directory. See RESTORING for details.
283 --at time
285 the source parameter is interpreted as a back-up directory, and
286 the content is restored from the given time. See TIME FORMATS
287 for details.
288 --increment
290 the source parameter is expected to be an increment within a
291 back-up repository, to be restored into the given target
292 directory.
293 server [RESTRICT OPTIONS] [--debug]
295 Enter server mode (not to be invoked directly, but instead used by
296 another rdiff-backup process on a remote computer).
297 --debug
299 Start the server in debug mode so that it stops on an early
300 breakpoint and can be remotely debugged using rpdb
301 <https://github.com/tamentis/rpdb>. See the developer’s
302 documentation
303 <https://github.com/rdiff-backup/rdiff-backup/blob/master/docs/DEVELOP.adoc#debug-client-server-mode>
304 for details.
305 test remote_location_1 [remote_location_2 ...]
307 Test for the presence of a compatible rdiff-backup server as
308 specified in the remote location argument(s) (of which the filename
309 section will be checked for existence). See the REMOTE OPERATION
310 section for details.
311 verify [--at time] location
313 Check all the data in the repository at the given time by computing
314 the SHA1 hash of all the regular files and comparing them with the
315 hashes stored in the metadata file.
316 --at time
318 the time of the data which needs to be verified. See TIME
319 FORMATS for details.
320
322 --compression, --no-compression
323 Enable or disable the default gzip compression of most of the
324 .snapshot and .diff increment files stored in the rdiff-backup-data
325 directory. A backup volume can contain compressed and uncompressed
326 increments, so using this option inconsistently is fine. Default is
327 to compress all files, except those excluded as noted below.
328 --not-compressed-regexp regexp
330 Do not compress increments based on files whose filenames match
331 regexp. The default includes many common audiovisual and archive
332 files, and may be found from the help.
333
335 --create-full-path
336 Normally only the final directory of the destination path will be
337 created if it does not exist. With this option, all missing
338 directories on the destination path will be created. Use this
339 option with care: if there is a typo in the remote path, the remote
340 filesystem could fill up very quickly (by creating a duplicate
341 backup tree). For this reason this option is primarily aimed at
342 scripts which automate backups.
343
345 --acls, --no-acls
346 enable/disable back-up of Access Control Lists.
347 --carbonfile, --no-carbonfile
349 enable/disable back-up of carbon files (MacOS X).
350 --eas, --no-eas
352 enable/disable back-up of Extended Attributes.
353 --resource-forks, --no-resource-forks
355 enable/disable back-up of resource forks (MacOS X).
356 --hard-links, --no-hard-links
358 do (or not) keep hard-link relationships between files. Disabling
359 hard-links generally increases the disk space usage but decreases
360 memory usage. Hard-links are disabled by default if the backup
361 source or restore destination is running on native Windows.
362 --compare-inode, --no-compare-inode
364 This option prevents rdiff-backup from flagging a hardlinked file
365 as changed when its device number and/or inode changes. This option
366 is useful in situations where the source filesystem lacks
367 persistent device and/or inode numbering. For example, network
368 filesystems may have mount-to-mount differences in their device
369 number (but possibly stable inode numbers); USB/1394 devices may
370 come up at different device numbers each remount (but would
371 generally have same inode number); and there are filesystems which
372 don’t even have the same inode numbers from use to use. Without the
373 option rdiff-backup may generate unnecessary numbers of tiny diff
374 files.
375 --never-drop-acls
377 Exit with error instead of dropping ACLs or ACL entries. Normally
378 this may happen (with a warning) because the destination does not
379 support them or because the relevant user/group names do not exist
380 on the destination side.
381
383 --restrict-path dirpath
384 Require that all file access be inside the given path. This switch,
385 and --restrict-mode, are intended to be used with the server action
386 to provide a bit more protection when doing automated remote
387 backups.
388 Caution
390 Those options are not intended as your only line of defense so
391 please don’t do something silly like allow public access to an
392 rdiff-backup server run with --restrict-mode read-only.
393 --restrict-mode {read-write,read-only,update-only}
395 restriction mode for the directory given by --restrict-path, either
396 full access (aka read-write), read-only, or only to update
397 incrementally an already existing back-up (default is read-write).
398
400 This section only quickly lists the existing options, the section FILE
401 SELECTION explains those more in details.
402 Globs, Regex, File lists selection
404 --include,--exclude glob
405 Include/exclude the file or files matched by glob (also known as
406 shell pattern). If a directory is excluded, then files under that
407 directory will also be excluded.
408 --include-globbing-filelist,--exclude-globbing-filelist globsfile
410 Include/exclude according to the listed globs, similar to --include
411 or --exclude.
412 --include-globbing-filelist-stdin,--exclude-globbing-filelist-stdin
414 Like the previous option but the list of globs is coming from
415 standard input.
416 --include-regexp,--exclude-regexp regexp
418 Include/exclude files matching the given regexp (according to
419 Python rules).
420 --include-filelist,--exclude-filelist listfile
422 Include/exclude the files listed in filelist. This is a best fit
423 for an automatically generated list of files, else use globbing.
424 --include-filelist-stdin,--exclude-filelist-stdin
426 Like the previous but the filelist is coming from standard input.
427 Special files selection
429 Note
430 All special files are included by default, so that including them
431 explicitly isn’t generally required. Exceptions are described.
432 --include-device-files,--exclude-device-files
434 Include/exclude all device files. This can be useful for
435 security/permissions reasons or if rdiff-backup is not handling
436 device files correctly.
437 --include-fifos,--exclude-fifos
439 Include/exclude all fifo files.
440 --include-sockets,--exclude-sockets
442 Include/exclude all socket files.
443 --include-symbolic-links,--exclude-symbolic-links
445 Include/exclude all symbolic links. Contrary to the general rule,
446 symlinks are excluded by default under Windows so that NTFS reparse
447 points aren’t backed-up.
448 --include-special-files,--exclude-special-files
450 Include/exclude all the special files listed above.
451 Other selections
453 --include-other-filesystems,--exclude-other-filesystems
454 Include/exclude files on file systems (identified by device number)
455 other than the file system the root of the source directory is on.
456 The default is to include other filesystems.
457 --include-if-present,--exclude-if-present filename
459 Include/exclude directories if they contain the given filename.
460 Files directly in an included directory are also considered
461 included. This doesn’t apply recursively though so that the
462 filename must be present in all directories of a hierarchy for it
463 to be fully included.
464 --max-file-size sizeinbytes
466 Exclude files that are larger than the given size in bytes.
467 --min-file-size sizeinbytes
469 Exclude files that are smaller than the given size in bytes.
470
472 --file-statistics, --no-file-statistics
473 Enable/disable writing to the 'file_statistics' file in the
474 rdiff-backup-data directory. rdiff-backup will run slightly quicker
475 and take up a bit less space. Default is to write the statistics
476 file(s).
477 See the FILES section for more information about statistics files.
479 --no-print-statistics, --print-statistics
481 Summary statistics will be printed (or not) after a successful
482 backup. Even if disabled (the default), this information will still
483 be available from the session statistics file.
484
486 --allow-duplicate-timestamps
487 This option is only to be used if you encounter the issue of
488 metadata mirrors with the same timestamp. In such cases, you may
489 use this flag to first recover from the failed backup with
490 something like
491 rdiff-backup regress --allow-duplicate-timestamps {targetdir}
493 after which you will need to remove those old duplicate entries
495 using the remove increments action.
496
498 See the USERS AND GROUPS section for more information.
499 --group-mapping-file mapfile
501 Map group names and IDs according to the group mapping file
502 mapfile.
503 --user-mapping-file mapfile
505 Map user names and IDs according to the user mapping file mapfile.
506 --preserve-numerical-ids
508 If set, rdiff-backup will preserve uids/gids instead of trying to
509 preserve unames and gnames.
510
512 There are two ways to tell rdiff-backup to restore a file or directory:
513 1. you can run rdiff-backup restore on a mirror file and define a time
515 from which to restore (by default the latest one).
516 2. you can run the restore action on an increment file with the
518 sub-option --increment.
519 For example, suppose in the past you have run:
521 rdiff-backup backup /usr /usr.backup
523 to back up the '/usr' directory into the '/usr.backup' directory, and
525 now want a copy of the '/usr/local' directory the way it was 3 days ago
526 placed at '/usr/local.old'.
527 One way to do this is to run:
529 rdiff-backup restore --at 3D /usr.backup/local /usr/local.old
531 here above the '3D' means 3 days (for other ways to specify the time,
533 see the TIME FORMATS section). The '/usr.backup/local' directory was
534 selected, because that is the directory containing the current version
535 of 'usr/local'.
536 Note that the parameter of --at always specifies an exact time. (So
538 '3D' refers to the moment 72 hours before the present). If there was no
539 backup made at that time, rdiff-backup restores the state recorded for
540 the previous backup. For instance, in the above case, if '3D' is used,
541 and there are only backups from 2 days and 4 days ago, '/usr/local' as
542 it was 4 days ago will be restored.
543 The second way to restore files involves finding the corresponding
545 increment file. It would be in the
546 '/backup/rdiff-backup-data/increments/usr' directory, and its name
547 would be something like 'local.2002-11-09T12:43:53-04:00.dir' where the
548 time indicates it is from 3 days ago. Note that the increment files all
549 end in '.diff', '.snapshot', '.dir', or '.missing', where '.missing'
550 just means that the file didn’t exist at that time (finally, some of
551 these may be gzip-compressed, and have an extra '.gz' to indicate
552 this). Then running:
553 rdiff-backup restore --increment \
555 /backup/rdiff-backup-data/increments/usr/local.{time}.dir \
556 /usr/local.old
557 would also restore the file as desired.
559 If you are not sure exactly which version of a file you need, it is
561 probably easiest to either restore from the increments files as
562 described immediately above, or to see which increments are available
563 with 'list increments', and then specify an exact time with --at.
564
566 rdiff-backup uses time strings in two places.
567 Firstly, all of the increment files rdiff-backup creates will have the
569 time in their filenames in the w3 datetime format as described in a w3
570 note at https://www.w3.org/TR/NOTE-datetime. Basically they look like
571 '2001-07-15T04:09:38-07:00', which is basically
572 "{Year}-{Month}-{Day}T{Hours}:{Minutes}:{Seconds}{Timezone}", the time
573 zone being 7 hours behind UTC in this example (hence the minus).
574 Secondly, the --at, --changed-since, --older-than options take a time
576 string, which can be given in any of several formats:
577 1. the string 'now' (refers to the current time)
579 2. a sequences of digits, like '123456890' (indicating the time in
581 seconds after the epoch)
582 3. A string like '2002-01-25T07:00:00+02:00' in datetime format
584 4. An interval, which is a number followed by one of the characters s,
586 m, h, D, W, M, or Y (indicating seconds, minutes, hours, days,
587 weeks, months, or years respectively), or a series of such pairs.
588 In this case the string refers to the time that preceded the
589 current time by the length of the interval. For instance, '1h78m"'
590 indicates the time that was one hour and 78 minutes ago. The
591 calendar here is unsophisticated: a month is always 30 days, a year
592 is always 365 days, and a day is always 86400 seconds.
593 5. A date format of the form "YYYY/MM/DD", "YYYY-MM-DD", "MM/DD/YYYY",
595 or "MM-DD-YYYY", which indicates midnight on the day in question,
596 relative to the current timezone settings. For instance,
597 '2002/3/5', '03-05-2002', and '2002-3-05' all mean March 5th, 2002
598 (needless to say that starting with the year is less confusing for
599 non-Americans).
600 6. A backup session specification which is a non-negative integer
602 followed by 'B'. For instance, '0B' specifies the time of the
603 current mirror, and '3B' specifies the time of the 3rd newest
604 increment.
605
607 In order to access remote files, rdiff-backup opens up a pipe to a copy
608 of rdiff-backup running on the remote machine. Thus rdiff-backup must
609 be installed on both ends. To open this pipe, rdiff-backup first splits
610 the location into 'host_info::pathname'. It then substitutes
611 'host_info' into the remote schema, and runs the resulting command,
612 reading its input and output.
613 The 'host_info' can be anything understood as a destination by your
615 version of SSH. Assuming it is the standard OpenSSH, it can be:
616 • either '[user@]hostname'
618 • or a URI of the form 'ssh://[user@]hostname[:port]'.
620 The default remote schema is 'ssh -C {h} rdiff-backup --server' where
622 'host_info' is substituted for '{h}'. So if the 'host_info' is
623 'user@host.net', then rdiff-backup runs 'ssh user@host.net rdiff-backup
624 --server'. Using --remote-schema, rdiff-backup can invoke an arbitrary
625 command in order to open up a remote pipe. For instance,
626 rdiff-backup --remote-schema 'cd /usr; {h}' backup \
628 foo 'rdiff-backup server'::bar
629 is basically equivalent to (but slower than)
631 rdiff-backup backup foo /usr/bar
633 Concerning quoting, if for some reason you need to put two consecutive
635 colons in the 'host_info' section of a 'host_info::pathname' argument,
636 or in the pathname of a local file, you can quote one of them by
637 prepending a backslash. So in 'a\::b::c', 'host_info' is 'a::b' and the
638 pathname is 'c'. Similarly, if you want to refer to a local file whose
639 filename contains two consecutive colons, like 'strange::file', you’ll
640 have to quote one of the colons as in 'strange\::file'. Because the
641 backslash is a quote character in these circumstances, it too must be
642 quoted to get a literal backslash, so 'foo\::\\bar' evaluates to
643 'foo::\bar'. To make things more complicated, because the backslash is
644 also a common shell quoting character, you may need to type in '\\\\'
645 at the shell prompt to get a literal backslash.
646 You may also use the placehoders '{Vx}', '{Vy}' and '{Vz}' for the
648 'x.y.z' version of rdiff-backup, so that you can have multiple versions
649 of rdiff-backup installed on the server, and automatically targeted
650 from the client.
651 For example, if you have rdiff-backup 2.1.5 and 2.2.1 installed in
653 virtual environments on the server, respectively under
654 '/usr/local/lib/rdiff-backup-2.0' and '/usr/local/lib/rdiff-backup-2.1'
655 (we assume that the z-Version isn’t relevant to any kind of
656 compatibility), then the client may be called with the following remote
657 schema:
658 ssh -C {h} /usr/local/lib/rdiff-backup-{Vx}.{Vy} --server
660 The client will then use the correct version of rdiff-backup based on
662 its own version 'x.y.z'. You’ll find more explanations in the migration
663 file in the documentation.
664 If you need to include a literal '%' in the string specified by
666 --remote-schema, quote it with another '%', as in '%%' (this is due to
667 the compatibility with the deprecated host placeholder '%s', which you
668 shouldn’t use anymore).
669 And finally, if you need to include literal '{ }' (curly braces) in the
671 the string specified by --remote-schema, quote them (both) by doubling
672 each of them up, as in '{{ foo=0; }}'.
673 Although ssh itself may be secure, using rdiff-backup in the default
675 way presents some security risks. For instance if the server is run as
676 root, then an attacker who compromised the client could then use
677 rdiff-backup to overwrite arbitrary server files by "backing up" over
678 them. Such a setup can be made more secure by using the sshd
679 configuration option 'command="rdiff-backup server"' possibly along
680 with the --restrict-path and --restrict-mode options to rdiff-backup.
681 For more information, see the web page, the wiki, and the entries for
682 those options on this man page.
683
685 rdiff-backup has a number of file selection options. When rdiff-backup
686 is run, it searches through the given source directory and backs up all
687 the files matching the specified options. This selection system may
688 appear complicated, but it is supposed to be flexible and easy-to-use.
689 If you just want to learn the basics, first look at the selection
690 examples in the examples file included in the package, or on the web at
691 https://rdiff-backup.net/examples.html.
692 rdiff-backup’s selection system was originally inspired by rsync(1),
694 but there are many differences. For instance, trailing backslashes have
695 no special significance.
696 Important
698 include and exclude patterns under Windows solely support slashes
699 '/' as file separators, given that backslashes '\' have a special
700 meaning in regex/glob patterns.
701 All the available file selection conditions are listed under SELECTION
703 OPTIONS.
704 Two principles need to be understood before really starting:
706 1. pattern matching is stupid about paths, it just does pattern
708 matching and can’t interpret patterns like path, especially it
709 can’t resolve absolute into relative paths and vice-versa (compare
710 with the '-path' option of find).
711 2. pattern matching is done on the complete path of each found file
713 (no partial matching and no file name matching). Beware that
714 complete path does not mean full path, it can be a complete
715 relative path.
716 For example, the pattern 'bar' matches the path 'bar', but doesn’t
718 match the path 'foo/bar' and neither the path './bar'. Both are matched
719 by the pattern '*/bar', as well as by '**/bar'. This last pattern would
720 match any path containing the file 'bar', e.g. 'foo/boz/bar'.
721 Each file selection condition either matches or doesn’t match a given
723 file. A given file is excluded by the file selection system exactly
724 when the first matching file selection condition specifies that the
725 file be excluded; otherwise the file is included. When backing up, if a
726 file is excluded, rdiff-backup acts as if that file does not exist in
727 the source directory. When restoring, an excluded file is considered
728 not to exist in either the source or target directories.
729 For instance,
731 rdiff-backup backup --include /usr \
733 --exclude /usr /usr /backup
734 is exactly the same as
736 rdiff-backup backup /usr /backup
738 because the include and exclude directives match exactly the same
740 files, and the --include comes first, giving it precedence. Similarly,
741 rdiff-backup backup --include /usr/local/bin \
743 --exclude /usr/local /usr /backup
744 would backup the '/usr/local/bin' directory (and its contents), but not
746 '/usr/local/doc'.
747 The include, exclude, include-globbing-filelist, and
749 exclude-globbing-filelist options accept extended shell globbing
750 patterns. These patterns can contain the special patterns '*', '**',
751 '?', and '[...]'. As in a normal shell, '*' can be expanded to any
752 string of characters not containing '/', '?' expands to any character
753 except '/', and '[...]' expands to a single character of those
754 characters specified (ranges are acceptable). The new special pattern,
755 '**', expands to any string of characters whether or not it contains
756 '/'. Furthermore, if the pattern starts with 'ignorecase:' (case
757 insensitive), then this prefix will be removed and any character in the
758 string can be replaced with an upper or lowercase version of itself.
759 If you need to match filenames which contain the above globbing
761 characters, they may be escaped using a backslash '\'. The backslash
762 will only escape the character following it so for '**' you will need
763 to use '\*\*' to avoid escaping it to the '*' globbing character.
764 Remember that you may need to quote these characters when typing them
766 into a shell, so the shell does not interpret the globbing patterns
767 before rdiff-backup sees them.
768 The --exclude pattern option matches a file if and only if:
770 1. pattern can be expanded into the file’s filename, or
772 2. the file is inside a directory matched by the option.
774 Conversely, --include pattern matches a file if and only if:
776 1. pattern can be expanded into the file’s filename,
778 2. the file is inside a directory matched by the option, or
780 3. the file is a directory which contains a file matched by the
782 option.
783 For example,
785 --exclude /usr/local
787 matches '/usr/local', '/usr/local/lib', and '/usr/local/lib/netscape'.
789 It is the same as
790 --exclude /usr/local --exclude '/usr/local/**'
792 And similarly:
794 --include /usr/local
796 specifies that '/usr', '/usr/local', '/usr/local/lib', and
798 '/usr/local/lib/netscape' (but not '/usr/doc') all be backed up. Thus
799 you don’t have to worry about including parent directories to make sure
800 that included subdirectories have somewhere to go. Finally,
801 --include ignorecase:'/usr/[a-z0-9]foo/*/**.py'
803 would match a file like '/usr/5fOO/hello/there/world.py'. If it did
805 match anything, it would also match '/usr'. If there is no existing
806 file that the given pattern can be expanded into, the option will not
807 match '/usr'.
808 The --include-filelist, --exclude-filelist, --include-filelist-stdin,
810 and --exclude-filelist-stdin options also introduce file selection
811 conditions. They direct rdiff-backup to read in a file, each line of
812 which is a file specification, and to include or exclude the matching
813 files. Lines are separated by newlines or nulls, depending on whether
814 the --null-separator switch was given. Each line in a filelist is
815 interpreted similarly to the way extended shell patterns are, with a
816 few exceptions:
817 1. Globbing patterns like '*', '**', '?', and '[...]' are not
819 expanded.
820 2. Include patterns do not match files in a directory that is
822 included. So '/usr/local' in an include file will not match
823 '/usr/local/doc'.
824 3. Lines starting with '+ [...]' (plus followed by a space) are
826 interpreted as include directives, even if found in a filelist
827 referenced by --exclude-filelist. Similarly, lines starting with '-
828 [...]' (minus followed by a space) exclude files even if they are
829 found within an include filelist.
830 For example, if the file 'list.txt' contains the lines:
832 /usr/local
834 - /usr/local/doc
835 /usr/local/bin
836 + /var
837 - /var
838 then '--include-filelist list.txt' would include '/usr', '/usr/local',
840 and '/usr/local/bin'. It would exclude '/usr/local/doc',
841 '/usr/local/doc/python', etc. It neither excludes nor includes
842 '/usr/local/man', leaving the fate of this directory to the next
843 specification condition. Finally, it is undefined what happens with
844 '/var'. A single file list should not contain conflicting file
845 specifications.
846 The --include-globbing-filelist and --exclude-globbing-filelist options
848 also specify filelists, but each line in the filelist will be
849 interpreted as a globbing pattern the way --include and --exclude
850 options are interpreted (although '+ ' and '- ' prefixing is still
851 allowed). For instance, if the file 'globbing-list.txt' contains the
852 lines:
853 dir/foo
855 Then '--include-globbing-filelist globbing-list.txt' would be exactly
857 the same as specifying on the command line:
858 --include dir/foo --include dir/bar --exclude **
860 Finally, the --include-regexp and --exclude-regexp allow files to be
862 included and excluded if their filenames match a python regular
863 expression. Regular expression syntax is too complicated to explain
864 here, but is covered in Python’s library reference. Unlike the
865 --include and --exclude options, the regular expression options don’t
866 match files containing or contained in matched files. So for instance
867 --include '[0-9]{7}(?!foo)'
869 matches any files whose full pathnames contain 7 consecutive digits
871 which aren’t followed by 'foo'. However, it wouldn’t match '/home' even
872 if '/home/ben/1234567' existed.
873
875 There can be complications preserving ownership across systems. For
876 instance the username that owns a file on the source system may not
877 exist on the destination. Here is how rdiff-backup maps ownership on
878 the source to the destination (or vice-versa, in the case of
879 restoring):
880 1. If the --preserve-numerical-ids option is given, the remote files
882 will always have the same uid and gid, both for ownership and ACL
883 entries. This may cause unames and gnames to change.
884 2. Otherwise, attempt to preserve the user and group names for
886 ownership and in ACLs. This may result in files having different
887 uids and gids across systems.
888 3. If a name cannot be preserved (e.g. because the username does not
890 exist), preserve the original id, but only in cases of user and
891 group ownership. For ACLs, omit any entry that has a bad user or
892 group name.
893 4. The --user-mapping-file and --group-mapping-file options override
895 this behavior. If either of these options is given, the policy
896 described in 2 and 3 above will be followed, but with the mapped
897 user and group instead of the original. If you specify both
898 --preserve-numerical-ids and one of the mapping options, the
899 behavior is undefined.
900 The user and group mapping files both have the same format:
902 old_name_or_id1:new_name_or_id1
904 old_name_or_id2:new_name_or_id2
905 [...etc...]
906 Each line should contain a name or id, followed by a colon ':',
908 followed by another name or id. If a name or id is not listed, they are
909 treated in the default way described above.
910 When restoring, the above behavior is also followed, but note that the
912 original source user/group information will be the input, not the
913 already mapped user/group information present in the backup repository.
914 For instance, suppose you have mapped all the files owned by alice in
915 the source so that they are owned by ben in the repository, and now you
916 want to restore, making sure the files owned originally by alice are
917 still owned by alice. In this case there is no need to use any of the
918 mapping options. However, if you wanted to restore the files so that
919 the files originally owned by alice on the source are now owned by ben,
920 you would have to use the mapping options, even though you just want
921 the unames of the repository’s files preserved in the restored files.
922 See USER GROUP OPTIONS for a list and description of related options.
924
926 any-config-file
927 you can create a file with one option/action/sub-option per line
928 and use it on the command line with an at sign prefix like
929 @any-config-file and its content will be interpreted as if given on
930 the command line.
931 For example, creating a file 'mybackup' with following content:
933 --verbosity
935 5
936 backup
937 source_dir
938 target_dir
939 and calling 'rdiff-backup @mybackup' will be the same as calling
941 'rdiff-backup --verbosity 5 backup source_dir target_dir'.
942 session_statistics, file_statistics
944 Every session rdiff-backup saves various statistics into two files,
945 the session statistics file at
946 'rdiff-backup-data/session_statistics.{datetime}.data' and the
947 files statistics at
948 'rdiff-backup-data/directory_statistics.{datetime}.data'. They are
949 both text files and contain similar information: how many files
950 changed, how many were deleted, the total size of increment files
951 created, etc. However, the session statistics file is intended to
952 be very readable and only describes the session as a whole. The
953 files statistics file is more compact (and slightly less readable)
954 but describes every directory backed up. It also may be compressed
955 to save space.
956 See also STATISTICS OPTIONS and the --null-separator option.
958 backup.log, restore.log, error_log
960 rdiff-backup will save various messages to the log file, which is
961 'rdiff-backup-data/backup.log' for backup sessions and
962 'rdiff-backup-data/restore.log' for restore sessions. Generally
963 what is written to this file will coincide with the messages
964 displayed to stdout or stderr, although this can be changed with
965 the --terminal-verbosity option.
966 Errors during backup are also written to a file
968 'rdiff-backup-data/error_log.{datetime}.data'.
969 The log files are not compressed and can become quite large if
971 rdiff-backup is run with high verbosity.
972
974 RDIFF_BACKUP_VERBOSITY=[0-9]
975 the default verbosity for log file and terminal, can be overwritten
976 by the corresponding options -v/--verbosity and
977 --terminal-verbosity.
978 RDIFF_BACKUP_DEBUG=[address][:port]
980 set a non-default listening address and/or port (default is
981 127.0.0.1:4444) for rpdb. Valid values are address, address:port
982 or :port.
983 RDIFF_BACKUP_API_VERSION={[dictionary]}
985 Overwrite the 'actual', 'default', 'max' and/or 'min' value of the
986 API VERSION using a YAML object, e.g. {actual: 201, default: 201}.
987 This environment variable is rather meant for development and test
988 purposes to change the values without modifying the code, so use
989 with care.
990
992 The following return codes have not been fully implemented so test
993 before you rely on them. Also note that they can be combined, so that
994 for example a return code 3 might be returned if a warning was found,
995 then an error.
996 0 - OK
998 the action was completely successful
999 1 - ERROR
1001 something fatal happened, the whole action failed
1002 2 - WARNING
1004 any kind of unexpected behavior without complete failure
1005 4 - FILE ERROR
1007 the action failed on a single file (or more), but it wasn’t the
1008 reason for a complete failure
1009 8 - FILE WARNING
1011 the action stumbled on a single file (or more), or detected
1012 differences in a comparaison
1013 Tip
1015 any other error code can and should be reported as a bug.
1016
1018 See GitHub issues
1019 https://github.com/rdiff-backup/rdiff-backup/issues
1020 In doubt subscribe to and ask the mailing list
1022 https://lists.nongnu.org/mailman/listinfo/rdiff-backup-users
1023
1025 • Ben Escoto ben@emerose.org (retired)
1026 • Eric Lavarde ewl+rdiffbackup@lavar.de (active)
1028
1030 rdiff-backup-old(1), python(1), rdiff(1), rsync(1), ssh(1).
1031 The main rdiff-backup web page is at https://rdiff-backup.net/. It has
1033 more documentation, links to the mailing list and source code.
1034rdiff-backup September 2023 RDIFF-BACKUP(1)