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