1RDIFF-BACKUP(1) User Manuals RDIFF-BACKUP(1)
2
6 rdiff-backup - local/remote mirror and incremental backup
7
9 rdiff-backup [options] [[[user@]host1.foo]::source_directory]
10 [[[user@]host2.foo]::destination_directory]
11 rdiff-backup {{ -l | --list-increments } | --remove-older-than time_in‐
13 terval | --list-at-time time | --list-changed-since time | --list-in‐
14 crement-sizes | --verify | --verify-at-time time}
15 [[[user@]host2.foo]::destination_directory]
16 rdiff-backup --calculate-average statfile1 statfile2 ...
18 rdiff-backup --test-server [user1]@host1.net1::path
20 [[user2]@host2.net2::path] ...
21
24 rdiff-backup is a script, written in python(1) that backs up one direc‐
25 tory to another. The target directory ends up a copy (mirror) of the
26 source directory, but extra reverse diffs are stored in a special sub‐
27 directory of that target directory, so you can still recover files lost
28 some time ago. The idea is to combine the best features of a mirror
29 and an incremental backup. rdiff-backup also preserves symlinks, spe‐
30 cial files, hardlinks, permissions, uid/gid ownership, and modification
31 times.
32 rdiff-backup can also operate in a bandwidth efficient manner over a
34 pipe, like rsync(1). Thus you can use ssh and rdiff-backup to securely
35 back a hard drive up to a remote location, and only the differences
36 will be transmitted. Using the default settings, rdiff-backup requires
37 that the remote system accept ssh connections, and that rdiff-backup is
38 installed in the user's PATH on the remote system. For information on
39 other options, see the section on REMOTE OPERATION.
40 Note that you should not write to the mirror directory except with
42 rdiff-backup. Many of the increments are stored as reverse diffs, so
43 if you delete or modify a file, you may lose the ability to restore
44 previous versions of that file.
45 Finally, this man page is intended more as a precise description of the
47 behavior and syntax of rdiff-backup. New users may want to check out
48 the examples.html file included in the rdiff-backup distribution.
49
52 --allow-duplicate-timestamps
53 This option is only to be used if you encounter the issue of
54 metadata mirrors with the same timestamp. In such cases, you may
55 use this flag to first recover from the failed backup with some‐
56 thing like rdiff-backup --allow-duplicate-timestamps --check-
57 destination-dir <targetdir> after which you will need to remove
58 those old duplicate entries using the --remove-older-than param‐
59 eter.
60 -b, --backup-mode
62 Force backup mode even if first argument appears to be an incre‐
63 ment or mirror file.
64 --calculate-average
66 Enter calculate average mode. The arguments should be a number
67 of statistics files. rdiff-backup will print the average of the
68 listed statistics files and exit.
69 --carbonfile
71 Enable backup of MacOS X carbonfile information.
72 --check-destination-dir
74 If an rdiff-backup session fails, running rdiff-backup with this
75 option on the destination dir will undo the failed directory.
76 This happens automatically if you attempt to back up to a direc‐
77 tory and the last backup failed.
78 --compare
80 This is equivalent to '--compare-at-time now'
81 --compare-at-time time
83 Compare a directory with the backup set at the given time. This
84 can be useful to see how archived data differs from current
85 data, or to check that a backup is current. This only compares
86 metadata, in the same way rdiff-backup decides whether a file
87 has changed.
88 --compare-full
90 This is equivalent to '--compare-full-at-time now'
91 --compare-full-at-time time
93 Compare a directory with the backup set at the given time. To
94 compare regular files, the repository data will be copied in its
95 entirety to the source side and compared byte by byte. This is
96 the slowest but most complete compare option.
97 --compare-hash
99 This is equivalent to '--compare-hash-at-time now'
100 --compare-hash-at-time time
102 Compare a directory with the backup set at the given time. Reg‐
103 ular files will be compared by computing their SHA1 digest on
104 the source side and comparing it to the digest recorded in the
105 metadata.
106 --create-full-path
108 Normally only the final directory of the destination path will
109 be created if it does not exist. With this option, all missing
110 directories on the destination path will be created. Use this
111 option with care: if there is a typo in the remote path, the re‐
112 mote filesystem could fill up very quickly (by creating a dupli‐
113 cate backup tree). For this reason this option is primarily
114 aimed at scripts which automate backups.
115 --current-time seconds
117 This option is useful mainly for testing. If set, rdiff-backup
118 will use it for the current time instead of consulting the
119 clock. The argument is the number of seconds since the epoch.
120 --exclude shell_pattern
122 Exclude the file or files matched by shell_pattern. If a direc‐
123 tory is matched, then files under that directory will also be
124 matched. See the FILE SELECTION section for more information.
125 --exclude-device-files
127 Exclude all device files. This can be useful for security/per‐
128 missions reasons or if rdiff-backup is not handling device files
129 correctly.
130 --exclude-fifos
132 Exclude all fifo files.
133 --exclude-filelist filename
135 Excludes the files listed in filename. If filename is handwrit‐
136 ten you probably want --exclude-globbing-filelist instead. See
137 the FILE SELECTION section for more information.
138 --exclude-filelist-stdin
140 Like --exclude-filelist, but the list of files will be read from
141 standard input. See the FILE SELECTION section for more infor‐
142 mation.
143 --exclude-globbing-filelist filename
145 Like --exclude-filelist but each line of the filelist will be
146 interpreted according to the same rules as --include and --ex‐
147 clude.
148 --exclude-globbing-filelist-stdin
150 Like --exclude-globbing-filelist, but the list of files will be
151 read from standard input.
152 --exclude-other-filesystems
154 Exclude files on file systems (identified by device number)
155 other than the file system the root of the source directory is
156 on.
157 --exclude-regexp regexp
159 Exclude files matching the given regexp. Unlike the --exclude
160 option, this option does not match files in a directory it
161 matches. See the FILE SELECTION section for more information.
162 --exclude-special-files
164 Exclude all device files, fifo files, socket files, and symbolic
165 links.
166 --exclude-sockets
168 Exclude all socket files.
169 --exclude-symbolic-links
171 Exclude all symbolic links. This option is automatically enabled
172 if the backup source is running on native Windows to avoid back‐
173 ing-up NTFS reparse points.
174 --exclude-if-present filename
176 Exclude directories if filename is present. This option needs to
177 come before any other include or exclude options.
178 --force
180 Authorize a more drastic modification of a directory than usual
181 (for instance, when overwriting of a destination path, or when
182 removing multiple sessions with --remove-older-than). rdiff-
183 backup will generally tell you if it needs this. WARNING: You
184 can cause data loss if you mis-use this option. Furthermore, do
185 NOT use this option when doing a restore, as it will DELETE
186 FILES, unless you absolutely know what you are doing.
187 --group-mapping-file filename
189 Map group names and ids according the the group mapping file
190 filename. See the USERS AND GROUPS section for more informa‐
191 tion.
192 --include shell_pattern
194 Similar to --exclude but include matched files instead. Unlike
195 --exclude, this option will also match parent directories of
196 matched files (although not necessarily their contents). See
197 the FILE SELECTION section for more information.
198 --include-filelist filename
200 Like --exclude-filelist, but include the listed files instead.
201 If filename is handwritten you probably want --include-globbing-
202 filelist instead. See the FILE SELECTION section for more in‐
203 formation.
204 --include-filelist-stdin
206 Like --include-filelist, but read the list of included files
207 from standard input.
208 --include-globbing-filelist filename
210 Like --include-filelist but each line of the filelist will be
211 interpreted according to the same rules as --include and --ex‐
212 clude.
213 --include-globbing-filelist-stdin
215 Like --include-globbing-filelist, but the list of files will be
216 read from standard input.
217 --include-regexp regexp
219 Include files matching the regular expression regexp. Only
220 files explicitly matched by regexp will be included by this op‐
221 tion. See the FILE SELECTION section for more information.
222 --include-special-files
224 Include all device files, fifo files, socket files, and symbolic
225 links.
226 --include-symbolic-links
228 Include all symbolic links.
229 --list-at-time time
231 List the files in the archive that were present at the given
232 time. If a directory in the archive is specified, list only the
233 files under that directory.
234 --list-changed-since time
236 List the files that have changed in the destination directory
237 since the given time. See TIME FORMATS for the format of time.
238 If a directory in the archive is specified, list only the files
239 under that directory. This option does not read the source di‐
240 rectory; it is used to compare the contents of two different
241 rdiff-backup sessions.
242 -l, --list-increments
244 List the number and date of partial incremental backups con‐
245 tained in the specified destination directory. No backup or re‐
246 store will take place if this option is given.
247 --list-increment-sizes
249 List the total size of all the increment and mirror files by
250 time. This may be helpful in deciding how many increments to
251 keep, and when to --remove-older-than. Specifying a subdirec‐
252 tory is allowable; then only the sizes of the mirror and incre‐
253 ments pertaining to that subdirectory will be listed.
254 --max-file-size size
256 Exclude files that are larger than the given size in bytes
257 --min-file-size size
259 Exclude files that are smaller than the given size in bytes
260 --never-drop-acls
262 Exit with error instead of dropping acls or acl entries. Nor‐
263 mally this may happen (with a warning) because the destination
264 does not support them or because the relevant user/group names
265 do not exist on the destination side.
266 --no-acls
268 No Access Control Lists - disable backup of ACLs
269 --no-carbonfile
271 Disable backup of MacOS X carbonfile information
272 --no-compare-inode
274 This option prevents rdiff-backup from flagging a hardlinked
275 file as changed when its device number and/or inode changes.
276 This option is useful in situations where the source filesystem
277 lacks persistent device and/or inode numbering. For example,
278 network filesystems may have mount-to-mount differences in their
279 device number (but possibly stable inode numbers); USB/1394 de‐
280 vices may come up at different device numbers each remount (but
281 would generally have same inode number); and there are filesys‐
282 tems which don't even have the same inode numbers from use to
283 use. Without the option rdiff-backup may generate unnecessary
284 numbers of tiny diff files.
285 --no-compression
287 Disable the default gzip compression of most of the .snapshot
288 and .diff increment files stored in the rdiff-backup-data direc‐
289 tory. A backup volume can contain compressed and uncompressed
290 increments, so using this option inconsistently is fine.
291 --no-compression-regexp regexp
293 Do not compress increments based on files whose filenames match
294 regexp. The default includes many common audiovisual and ar‐
295 chive files, and may be found in Globals.py.
296 --no-eas
298 No Extended Attributes support - disable backup of EAs.
299 --no-file-statistics
301 This will disable writing to the file_statistics file in the
302 rdiff-backup-data directory. rdiff-backup will run slightly
303 quicker and take up a bit less space.
304 --no-fsync
306 This will disable issuing fsync from rdiff-backup altogether.
307 This option is designed to optimize performance on busy backup
308 systems. Use with caution. This may render your backup unusable
309 in case of filesystem failure.
310 --no-hard-links
312 Don't replicate hard links on destination side. If many hard-
313 linked files are present, this option can drastically decrease
314 memory usage. This option is enabled by default if the backup
315 source or restore destination is running on native Windows.
316 --null-separator
318 Use nulls (\0) instead of newlines (\n) as line separators,
319 which may help when dealing with filenames containing newlines.
320 This affects the expected format of the files specified by the
321 --{include|exclude}-filelist[-stdin] switches as well as the
322 format of the directory statistics file.
323 --parsable-output
325 If set, rdiff-backup's output will be tailored for easy parsing
326 by computers, instead of convenience for humans. Currently this
327 only applies when listing increments using the -l or --list-in‐
328 crements switches, where the time will be given in seconds since
329 the epoch.
330 --override-chars-to-quote
332 If the filesystem to which we are backing up is not case-sensi‐
333 tive, automatic 'quoting' of characters occurs. For example, a
334 file 'Developer.doc' will be converted into ';068eveloper.doc'.
335 To override this behavior, you need to specify this option.
336 --preserve-numerical-ids
338 If set, rdiff-backup will preserve uids/gids instead of trying
339 to preserve unames and gnames. See the USERS AND GROUPS section
340 for more information.
341 --print-statistics
343 If set, summary statistics will be printed after a successful
344 backup. If not set, this information will still be available
345 from the session statistics file. See the STATISTICS section
346 for more information.
347 -r, --restore-as-of restore_time
349 Restore the specified directory as it was as of restore_time.
350 See the TIME FORMATS section for more information on the format
351 of restore_time, and see the RESTORING section for more informa‐
352 tion on restoring.
353 --remote-cmd cmd
355 Deprecated. Please use --remote-schema instead
356 --remote-schema schema
358 Specify an alternate method of connecting to a remote computer.
359 This is necessary to get rdiff-backup not to use ssh for remote
360 backups, or if, for instance, rdiff-backup is not in the PATH on
361 the remote side. See the REMOTE OPERATION section for more in‐
362 formation.
363 --remote-tempdir path
365 Adds the --tempdir option with argument path when invoking re‐
366 mote instances of rdiff-backup.
367 --remove-older-than time_spec
369 Remove the incremental backup information in the destination di‐
370 rectory that has been around longer than the given time.
371 time_spec can be either an absolute time, like "2002-01-04", or
372 a time interval. The time interval is an integer followed by
373 the character s, m, h, D, W, M, or Y, indicating seconds, min‐
374 utes, hours, days, weeks, months, or years respectively, or a
375 number of these concatenated. For example, 32m means 32 min‐
376 utes, and 3W2D10h7s means 3 weeks, 2 days, 10 hours, and 7 sec‐
377 onds. In this context, a month means 30 days, a year is 365
378 days, and a day is always 86400 seconds.
379 rdiff-backup cannot remove-older-than and back up or restore in
381 a single session. In order to both backup a directory and re‐
382 move old files in it, you must run rdiff-backup twice.
383 By default, rdiff-backup will only delete information from one
385 session at a time. To remove two or more sessions at the same
386 time, supply the --force option (rdiff-backup will tell you if
387 --force is required).
388 Note that snapshots of deleted files are covered by this opera‐
390 tion. Thus if you deleted a file two weeks ago, backed up imme‐
391 diately afterwards, and then ran rdiff-backup with --remove-
392 older-than 10D today, no trace of that file would remain. Fi‐
393 nally, file selection options such as --include and --exclude
394 don't affect --remove-older-than.
395 --restrict path
397 Require that all file access be inside the given path. This
398 switch, and the following two, are intended to be used with the
399 --server switch to provide a bit more protection when doing au‐
400 tomated remote backups. They are not intended as your only line
401 of defense so please don't do something silly like allow public
402 access to an rdiff-backup server run with --restrict-read-only.
403 --restrict-read-only path
405 Like --restrict, but also reject all write requests.
406 --restrict-update-only path
408 Like --restrict, but only allow writes as part of an incremental
409 backup. Requests for other types of writes (for instance,
410 deleting path) will be rejected.
411 --server
413 Enter server mode (not to be invoked directly, but instead used
414 by another rdiff-backup process on a remote computer).
415 --ssh-no-compression
417 When running ssh, do not use the -C option to enable compres‐
418 sion. --ssh-no-compression is ignored if you specify a new
419 schema using --remote-schema.
420 --tempdir path
422 Sets the directory that rdiff-backup uses for temporary files to
423 the given path. The environment variables TMPDIR, TEMP, and TMP
424 can also be used to set the temporary files directory. See the
425 documentation of the Python tempfile module for more informa‐
426 tion.
427 --terminal-verbosity [0-9]
429 Select which messages will be displayed to the terminal. If
430 missing the level defaults to the verbosity level.
431 --test-server
433 Test for the presence of a compatible rdiff-backup server as
434 specified in the following host::filename argument(s). The
435 filename section will be ignored.
436 --use-compatible-timestamps
438 Create timestamps in which the hour/minute/second separator is a
439 - (hyphen) instead of a : (colon). It is safe to use this option
440 on one backup, and then not use it on another; rdiff-backup sup‐
441 ports the intermingling of different timestamp formats. This op‐
442 tion is enabled by default on platforms which require that the
443 colon be escaped.
444 --user-mapping-file filename
446 Map user names and ids according to the user mapping file file‐
447 name. See the USERS AND GROUPS section for more information.
448 -v[0-9], --verbosity [0-9]
450 Specify verbosity level (0 is totally silent, 3 is the default,
451 and 9 is noisiest). This determines how much is written to the
452 log file.
453 --verify
455 This is short for --verify-at-time now
456 --verify-at-time now
458 Check all the data in the repository at the given time by com‐
459 puting the SHA1 hash of all the regular files and comparing them
460 with the hashes stored in the metadata file.
461 -V, --version
463 Print the current version and exit
464
467 RDIFF_BACKUP_VERBOSITY=[0-9]
468 Sets the default verbosity for log file and terminal, can be
469 overwritten by the corresponding options "-v/--verbosity" and
470 "--terminal-verbosity".
471
474 There are two ways to tell rdiff-backup to restore a file or directory.
475 Firstly, you can run rdiff-backup on a mirror file and use the -r or
476 --restore-as-of options. Secondly, you can run it on an increment
477 file.
478 For example, suppose in the past you have run:
480 rdiff-backup /usr /usr.backup
482 to back up the /usr directory into the /usr.backup directory, and now
484 want a copy of the /usr/local directory the way it was 3 days ago
485 placed at /usr/local.old.
486 One way to do this is to run:
488 rdiff-backup -r 3D /usr.backup/local /usr/local.old
490 where above the "3D" means 3 days (for other ways to specify the time,
492 see the TIME FORMATS section). The /usr.backup/local directory was se‐
493 lected, because that is the directory containing the current version of
494 /usr/local.
495 Note that the option to --restore-as-of always specifies an exact time.
497 (So "3D" refers to the instant 72 hours before the present.) If there
498 was no backup made at that time, rdiff-backup restores the state
499 recorded for the previous backup. For instance, in the above case, if
500 "3D" is used, and there are only backups from 2 days and 4 days ago,
501 /usr/local as it was 4 days ago will be restored.
502 The second way to restore files involves finding the corresponding in‐
504 crement file. It would be in the /backup/rdiff-backup-data/incre‐
505 ments/usr directory, and its name would be something like "lo‐
506 cal.2002-11-09T12:43:53-04:00.dir" where the time indicates it is from
507 3 days ago. Note that the increment files all end in ".diff", ".snap‐
508 shot", ".dir", or ".missing", where ".missing" just means that the file
509 didn't exist at that time (finally, some of these may be gzip-com‐
510 pressed, and have an extra ".gz" to indicate this). Then running:
511 rdiff-backup /backup/rdiff-backup-data/increments/usr/lo‐
513 cal.<time>.dir /usr/local.old
514 would also restore the file as desired.
516 If you are not sure exactly which version of a file you need, it is
518 probably easiest to either restore from the increments files as de‐
519 scribed immediately above, or to see which increments are available
520 with -l/--list-increments, and then specify exact times into -r/--re‐
521 store-as-of.
522
525 rdiff-backup uses time strings in two places. Firstly, all of the in‐
526 crement files rdiff-backup creates will have the time in their file‐
527 names in the w3 datetime format as described in a w3 note at
528 https://www.w3.org/TR/NOTE-datetime. Basically they look like
529 "2001-07-15T04:09:38-07:00", which means what it looks like. The
530 "-07:00" section means the time zone is 7 hours behind UTC.
531 Secondly, the -r, --restore-as-of, and --remove-older-than options take
533 a time string, which can be given in any of several formats:
534 1. the string "now" (refers to the current time)
536 2. a sequences of digits, like "123456890" (indicating the time in
538 seconds after the epoch)
539 3. A string like "2002-01-25T07:00:00+02:00" in datetime format
541 4. An interval, which is a number followed by one of the characters
543 s, m, h, D, W, M, or Y (indicating seconds, minutes, hours,
544 days, weeks, months, or years respectively), or a series of such
545 pairs. In this case the string refers to the time that preceded
546 the current time by the length of the interval. For instance,
547 "1h78m" indicates the time that was one hour and 78 minutes ago.
548 The calendar here is unsophisticated: a month is always 30 days,
549 a year is always 365 days, and a day is always 86400 seconds.
550 5. A date format of the form YYYY/MM/DD, YYYY-MM-DD, MM/DD/YYYY, or
552 MM-DD-YYYY, which indicates midnight on the day in question,
553 relative to the current timezone settings. For instance,
554 "2002/3/5", "03-05-2002", and "2002-3-05" all mean March 5th,
555 2002.
556 6. A backup session specification which is a non-negative integer
558 followed by 'B'. For instance, '0B' specifies the time of the
559 current mirror, and '3B' specifies the time of the 3rd newest
560 increment.
561
564 In order to access remote files, rdiff-backup opens up a pipe to a copy
565 of rdiff-backup running on the remote machine. Thus rdiff-backup must
566 be installed on both ends. To open this pipe, rdiff-backup first
567 splits the filename into host_info::pathname. It then substitutes
568 host_info into the remote schema, and runs the resulting command, read‐
569 ing its input and output.
570 The default remote schema is 'ssh -C %s rdiff-backup --server' where
572 host_info is substituted for '%s'. So if the host_info is
573 user@host.net, then rdiff-backup runs 'ssh user@host.net rdiff-backup
574 --server'. Using --remote-schema, rdiff-backup can invoke an arbitrary
575 command in order to open up a remote pipe. For instance,
576 rdiff-backup --remote-schema 'cd /usr; %s' foo 'rdiff-backup
577 --server'::bar
578 is basically equivalent to (but slower than)
579 rdiff-backup foo /usr/bar
580 Concerning quoting, if for some reason you need to put two consecutive
582 colons in the host_info section of a host_info::pathname argument, or
583 in the pathname of a local file, you can quote one of them by prepend‐
584 ing a backslash. So in 'a\::b::c', host_info is 'a::b' and the path‐
585 name is 'c'. Similarly, if you want to refer to a local file whose
586 filename contains two consecutive colons, like 'strange::file', you'll
587 have to quote one of the colons as in 'strange\::file'. Because the
588 backslash is a quote character in these circumstances, it too must be
589 quoted to get a literal backslash, so 'foo\::\\bar' evaluates to
590 'foo::\bar'. To make things more complicated, because the backslash is
591 also a common shell quoting character, you may need to type in '\\\\'
592 at the shell prompt to get a literal backslash (if it makes you feel
593 better, I had to type in 8 backslashes to get that in this man
594 page...). And finally, to include a literal % in the string specified
595 by --remote-schema, quote it with another %, as in %%.
596 Although ssh itself may be secure, using rdiff-backup in the default
598 way presents some security risks. For instance if the server is run as
599 root, then an attacker who compromised the client could then use rdiff-
600 backup to overwrite arbitrary server files by "backing up" over them.
601 Such a setup can be made more secure by using the sshd configuration
602 option command="rdiff-backup --server" possibly along with the --re‐
603 strict* options to rdiff-backup. For more information, see the web
604 page, the wiki, and the entries for the --restrict* options on this man
605 page.
606
609 rdiff-backup has a number of file selection options. When rdiff-backup
610 is run, it searches through the given source directory and backs up all
611 the files matching the specified options. This selection system may
612 appear complicated, but it is supposed to be flexible and easy-to-use.
613 If you just want to learn the basics, first look at the selection exam‐
614 ples in the examples.html file included in the package, or on the web
615 at https://rdiff-backup.net/docs/examples.html
616 rdiff-backup's selection system was originally inspired by rsync(1),
618 but there are many differences. (For instance, trailing backslashes
619 have no special significance.)
620 The file selection system comprises a number of file selection condi‐
622 tions, which are set using one of the following command line options:
623 --exclude, --exclude-filelist, --exclude-device-files, --exclude-fifos,
624 --exclude-sockets, --exclude-symbolic-links, --exclude-globbing-
625 filelist, --exclude-globbing-filelist-stdin, --exclude-filelist-stdin,
626 --exclude-regexp, --exclude-special-files, --include, --include-
627 filelist, --include-globbing-filelist, --include-globbing-filelist-
628 stdin, --include-filelist-stdin, and --include-regexp. Each file se‐
629 lection condition either matches or doesn't match a given file. A
630 given file is excluded by the file selection system exactly when the
631 first matching file selection condition specifies that the file be ex‐
632 cluded; otherwise the file is included. When backing up, if a file is
633 excluded, rdiff-backup acts as if that file does not exist in the
634 source directory. When restoring, an excluded file is considered not
635 to exist in either the source or target directories.
636 For instance,
638 rdiff-backup --include /usr --exclude /usr /usr /backup
640 is exactly the same as
642 rdiff-backup /usr /backup
644 because the include and exclude directives match exactly the same
646 files, and the --include comes first, giving it precedence. Similarly,
647 rdiff-backup --include /usr/local/bin --exclude /usr/local /usr
649 /backup
650 would backup the /usr/local/bin directory (and its contents), but not
652 /usr/local/doc.
653 The include, exclude, include-globbing-filelist, and exclude-globbing-
655 filelist options accept extended shell globbing patterns. These pat‐
656 terns can contain the special patterns *, **, ?, and [...]. As in a
657 normal shell, * can be expanded to any string of characters not con‐
658 taining "/", ? expands to any character except "/", and [...] expands
659 to a single character of those characters specified (ranges are accept‐
660 able). The new special pattern, **, expands to any string of charac‐
661 ters whether or not it contains "/". Furthermore, if the pattern
662 starts with "ignorecase:" (case insensitive), then this prefix will be
663 removed and any character in the string can be replaced with an upper-
664 or lowercase version of itself.
665 If you need to match filenames which contain the above globbing charac‐
667 ters, they may be escaped using a backslash "\". The backslash will
668 only escape the character following it so for ** you will need to use
669 "\*\*" to avoid escaping it to the * globbing character.
670 Remember that you may need to quote these characters when typing them
672 into a shell, so the shell does not interpret the globbing patterns be‐
673 fore rdiff-backup sees them.
674 The --exclude pattern option matches a file iff:
676 1. pattern can be expanded into the file's filename, or
678 2. the file is inside a directory matched by the option.
680 Conversely, --include pattern matches a file iff:
682 1. pattern can be expanded into the file's filename,
684 2. the file is inside a directory matched by the option, or
686 3. the file is a directory which contains a file matched by the op‐
688 tion.
689 For example,
691 --exclude /usr/local
693 matches /usr/local, /usr/local/lib, and /usr/local/lib/netscape. It is
695 the same as --exclude /usr/local --exclude '/usr/local/**'.
696 --include /usr/local
698 specifies that /usr, /usr/local, /usr/local/lib, and /usr/lo‐
700 cal/lib/netscape (but not /usr/doc) all be backed up. Thus you don't
701 have to worry about including parent directories to make sure that in‐
702 cluded subdirectories have somewhere to go. Finally,
703 --include ignorecase:'/usr/[a-z0-9]foo/*/**.py'
705 would match a file like /usR/5fOO/hello/there/world.py. If it did
707 match anything, it would also match /usr. If there is no existing file
708 that the given pattern can be expanded into, the option will not match
709 /usr.
710 The --include-filelist, --exclude-filelist, --include-filelist-stdin,
712 and --exclude-filelist-stdin options also introduce file selection con‐
713 ditions. They direct rdiff-backup to read in a file, each line of
714 which is a file specification, and to include or exclude the matching
715 files. Lines are separated by newlines or nulls, depending on whether
716 the --null-separator switch was given. Each line in a filelist is in‐
717 terpreted similarly to the way extended shell patterns are, with a few
718 exceptions:
719 1. Globbing patterns like *, **, ?, and [...] are not expanded.
721 2. Include patterns do not match files in a directory that is in‐
723 cluded. So /usr/local in an include file will not match
724 /usr/local/doc.
725 3. Lines starting with "+ " are interpreted as include directives,
727 even if found in a filelist referenced by --exclude-filelist.
728 Similarly, lines starting with "- " exclude files even if they
729 are found within an include filelist.
730 For example, if the file "list.txt" contains the lines:
732 /usr/local
734 - /usr/local/doc
735 /usr/local/bin
736 + /var
737 - /var
738 then "--include-filelist list.txt" would include /usr, /usr/local, and
740 /usr/local/bin. It would exclude /usr/local/doc, /usr/lo‐
741 cal/doc/python, etc. It neither excludes nor includes /usr/local/man,
742 leaving the fate of this directory to the next specification condition.
743 Finally, it is undefined what happens with /var. A single file list
744 should not contain conflicting file specifications.
745 The --include-globbing-filelist and --exclude-globbing-filelist options
747 also specify filelists, but each line in the filelist will be inter‐
748 preted as a globbing pattern the way --include and --exclude options
749 are interpreted (although "+ " and "- " prefixing is still allowed).
750 For instance, if the file "globbing-list.txt" contains the lines:
751 dir/foo
753 + dir/bar
754 - **
755 Then "--include-globbing-filelist globbing-list.txt" would be exactly
757 the same as specifying "--include dir/foo --include dir/bar --exclude
758 **" on the command line.
759 Finally, the --include-regexp and --exclude-regexp allow files to be
761 included and excluded if their filenames match a python regular expres‐
762 sion. Regular expression syntax is too complicated to explain here,
763 but is covered in Python's library reference. Unlike the --include and
764 --exclude options, the regular expression options don't match files
765 containing or contained in matched files. So for instance
766 --include '[0-9]{7}(?!foo)'
768 matches any files whose full pathnames contain 7 consecutive digits
770 which aren't followed by 'foo'. However, it wouldn't match /home even
771 if /home/ben/1234567 existed.
772
775 There can be complications preserving ownership across systems. For
776 instance the username that owns a file on the source system may not ex‐
777 ist on the destination. Here is how rdiff-backup maps ownership on the
778 source to the destination (or vice-versa, in the case of restoring):
779 1. If the --preserve-numerical-ids option is given, the remote
782 files will always have the same uid and gid, both for ownership
783 and ACL entries. This may cause unames and gnames to change.
784 2. Otherwise, attempt to preserve the user and group names for own‐
786 ership and in ACLs. This may result in files having different
787 uids and gids across systems.
788 3. If a name cannot be preserved (e.g. because the username does
790 not exist), preserve the original id, but only in cases of user
791 and group ownership. For ACLs, omit any entry that has a bad
792 user or group name.
793 4. The --user-mapping-file and --group-mapping-file options over‐
795 ride this behavior. If either of these options is given, the
796 policy described in 2 and 3 above will be followed, but with the
797 mapped user and group instead of the original. If you specify
798 both --preserve-numerical-ids and one of the mapping options,
799 the behavior is undefined.
800 The user and group mapping files both have the same form:
802 old_name_or_id1:new_name_or_id1
804 old_name_or_id2:new_name_or_id2
805 <etc>
806 Each line should contain a name or id, followed by a colon ":", fol‐
808 lowed by another name or id. If a name or id is not listed, they are
809 treated in the default way described above.
810 When restoring, the above behavior is also followed, but note that the
812 original source user/group information will be the input, not the al‐
813 ready mapped user/group information present in the backup repository.
814 For instance, suppose you have mapped all the files owned by alice in
815 the source so that they are owned by ben in the repository, and now you
816 want to restore, making sure the files owned originally by alice are
817 still owned by alice. In this case there is no need to use any of the
818 mapping options. However, if you wanted to restore the files so that
819 the files originally owned by alice on the source are now owned by ben,
820 you would have to use the mapping options, even though you just want
821 the unames of the repository's files preserved in the restored files.
822
826 Every session rdiff-backup saves various statistics into two files, the
827 session statistics file at rdiff-backup-data/session_statis‐
828 tics.<time>.data and the directory statistics file at rdiff-backup-
829 data/directory_statistics.<time>.data. They are both text files and
830 contain similar information: how many files changed, how many were
831 deleted, the total size of increment files created, etc. However, the
832 session statistics file is intended to be very readable and only de‐
833 scribes the session as a whole. The directory statistics file is more
834 compact (and slightly less readable) but describes every directory
835 backed up. It also may be compressed to save space.
836 Statistics-related options include --print-statistics and --null-sepa‐
838 rator.
839 Also, rdiff-backup will save various messages to the log file, which is
841 rdiff-backup-data/backup.log for backup sessions and rdiff-backup-
842 data/restore.log for restore sessions. Generally what is written to
843 this file will coincide with the messages displayed to stdout or
844 stderr, although this can be changed with the --terminal-verbosity op‐
845 tion.
846 The log file is not compressed and can become quite large if rdiff-
848 backup is run with high verbosity.
849
852 If rdiff-backup finishes successfully, the exit status will be 0. If
853 there is an unrecoverable (critical) error, it will be non-zero (usu‐
854 ally 1, but don't depend on this specific value). When setting up
855 rdiff-backup to run automatically (as from cron(8) or similar) it is
856 probably a good idea to check the exit code.
857
860 The gzip library in versions 2.2 and earlier of python (but fixed in
861 2.3a1) has trouble producing files over 2GB in length. This bug will
862 prevent rdiff-backup from producing large compressed increments (snap‐
863 shots or diffs). A workaround is to disable compression for large in‐
864 compressible files.
865
868 Ben Escoto <ben@emerose.org>
869 Feel free to ask me questions or send me bug reports, but you may want
871 to see the web page, mentioned below, first.
872
875 python(1), rdiff(1), rsync(1), ssh(1). The main rdiff-backup web page
876 is at https://rdiff-backup.net/. It has more information, links to the
877 mailing list and CVS, etc.
878Version 2.0.5 July 2021 RDIFF-BACKUP(1)