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