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 } [[[user@]host2.foo]::destination_directory]
15 rdiff-backup --calculate-average statfile1 statfile2 ...
17 rdiff-backup --test-server [user1]@host1.net1::path
19 [[user2]@host2.net2::path] ...
20
23 rdiff-backup is a script, written in python(1) that backs up one direc‐
24 tory to another. The target directory ends up a copy (mirror) of the
25 source directory, but extra reverse diffs are stored in a special sub‐
26 directory of that target directory, so you can still recover files lost
27 some time ago. The idea is to combine the best features of a mirror
28 and an incremental backup. rdiff-backup also preserves symlinks, spe‐
29 cial files, hardlinks, permissions, uid/gid ownership, and modification
30 times.
31 rdiff-backup can also operate in a bandwidth efficient manner over a
33 pipe, like rsync(1). Thus you can use ssh and rdiff-backup to securely
34 back a hard drive up to a remote location, and only the differences
35 will be transmitted. Using the default settings, rdiff-backup requires
36 that the remote system accept ssh connections, and that rdiff-backup is
37 installed in the user's PATH on the remote system. For information on
38 other options, see the section on REMOTE OPERATION.
39 Note that you should not write to the mirror directory except with
41 rdiff-backup. Many of the increments are stored as reverse diffs, so
42 if you delete or modify a file, you may lose the ability to restore
43 previous versions of that file.
44 Finally, this man page is intended more as a precise description of the
46 behavior and syntax of rdiff-backup. New users may want to check out
47 the examples.html file included in the rdiff-backup distribution.
48
51 -b, --backup-mode
52 Force backup mode even if first argument appears to be an incre‐
53 ment or mirror file.
54 --calculate-average
56 Enter calculate average mode. The arguments should be a number
57 of statistics files. rdiff-backup will print the average of the
58 listed statistics files and exit.
59 --check-destination-dir
61 If an rdiff-backup session fails, running rdiff-backup with this
62 option on the destination dir will undo the failed directory.
63 This happens automatically if you attempt to back up to a direc‐
64 tory and the last backup failed.
65 --compare
67 This is equivalent to '--compare-at-time now'
68 --compare-at-time time
70 Compare a directory with the backup set at the given time. This
71 can be useful to see how archived data differs from current
72 data, or to check that a backup is current.
73 --create-full-path
75 Normally only the final directory of the destination path will
76 be created if it does not exist. With this option, all missing
77 directories on the destination path will be created. Use this
78 option with care: if there is a typo in the remote path, the
79 remote filesystem could fill up very quickly (by creating a
80 duplicate backup tree). For this reason this option is primarily
81 aimed at scripts which automate backups.
82 --current-time seconds
84 This option is useful mainly for testing. If set, rdiff-backup
85 will it for the current time instead of consulting the clock.
86 The argument is the number of seconds since the epoch.
87 --exclude shell_pattern
89 Exclude the file or files matched by shell_pattern. If a direc‐
90 tory is matched, then files under that directory will also be
91 matched. See the FILE SELECTION section for more information.
92 --exclude-device-files
94 Exclude all device files. This can be useful for security/per‐
95 missions reasons or if rdiff-backup is not handling device files
96 correctly.
97 --exclude-fifos
99 Exclude all fifo files.
100 --exclude-filelist filename
102 Excludes the files listed in filename. If filename is handwrit‐
103 ten you probably want --include-globbing-filelist instead. See
104 the FILE SELECTION section for more information.
105 --exclude-filelist-stdin
107 Like --exclude-filelist, but the list of files will be read from
108 standard input. See the FILE SELECTION section for more infor‐
109 mation.
110 --exclude-globbing-filelist filename
112 Like --exclude-filelist but each line of the filelist will be
113 interpreted according to the same rules as --include and
114 --exclude.
115 --exclude-globbing-filelist-stdin
117 Like --exclude-globbing-filelist, but the list of files will be
118 read from standard input.
119 --exclude-other-filesystems
121 Exclude files on file systems (identified by device number)
122 other than the file system the root of the source directory is
123 on.
124 --exclude-regexp regexp
126 Exclude files matching the given regexp. Unlike the --exclude
127 option, this option does not match files in a directory it
128 matches. See the FILE SELECTION section for more information.
129 --exclude-special-files
131 Exclude all device files, fifo files, socket files, and symbolic
132 links.
133 --exclude-sockets
135 Exclude all socket files.
136 --exclude-symbolic-links
138 Exclude all symbolic links.
139 --force
141 Authorize a more drastic modification of a directory than usual
142 (for instance, when overwriting of a destination path, or when
143 removing multiple sessions with --remove-older-than). rdiff-
144 backup will generally tell you if it needs this.
145 --group-mapping-file filename
147 Map group names and ids according the the group mapping file
148 filename. See the USERS AND GROUPS section for more informa‐
149 tion.
150 --include shell_pattern
152 Similar to --exclude but include matched files instead. Unlike
153 --exclude, this option will also match parent directories of
154 matched files (although not necessarily their contents). See
155 the FILE SELECTION section for more information.
156 --include-filelist filename
158 Like --exclude-filelist, but include the listed files instead.
159 If filename is handwritten you probably want --exclude-globbing-
160 filelist instead. See the FILE SELECTION section for more
161 information.
162 --include-filelist-stdin
164 Like --include-filelist, but read the list of included files
165 from standard input.
166 --include-globbing-filelist filename
168 Like --include-filelist but each line of the filelist will be
169 interpreted according to the same rules as --include and
170 --exclude.
171 --include-globbing-filelist-stdin
173 Like --include-globbing-filelist, but the list of files will be
174 read from standard input.
175 --include-regexp regexp
177 Include files matching the regular expression regexp. Only
178 files explicitly matched by regexp will be included by this
179 option. See the FILE SELECTION section for more information.
180 --include-special-files
182 Include all device files, fifo files, socket files, and symbolic
183 links.
184 --include-symbolic-links
186 Include all symbolic links.
187 --list-at-time time
189 List the files in the archive that were present at the given
190 time. If a directory in the archive is specified, list only the
191 files under that directory.
192 --list-changed-since time
194 List the files that have changed in the destination directory
195 since the given time. See TIME FORMATS for the format of time.
196 If a directory in the archive is specified, list only the files
197 under that directory. This option does not read the source
198 directory; it is used to compare the contents of two different
199 rdiff-backup sessions.
200 -l, --list-increments
202 List the number and date of partial incremental backups con‐
203 tained in the specified destination directory. No backup or
204 restore will take place if this option is given.
205 --list-increment-sizes
207 List the total size of all the increment and mirror files by
208 time. This may be helpful in deciding how many increments to
209 keep, and when to --remove-older-than. Specifying a subdirec‐
210 tory is allowable; then only the sizes of the mirror and incre‐
211 ments pertaining to that subdirectory will be listed.
212 --never-drop-acls
214 Exit with error instead of dropping acls or acl entries. Nor‐
215 mally this may happen (with a warning) because the destination
216 does not support them or because the relevant user/group names
217 do not exist on the destination side.
218 --no-compare-inode
220 This relatively esoteric option prevents rdiff-backup from flag‐
221 ging a file as changed when its inode changes. This option may
222 be useful if you are backing up two different directories to the
223 same rdiff-backup destination directory. The downside is that
224 hard link information may get messed up, as the metadata file
225 may no longer have the correct inode information.
226 --no-compression
228 Disable the default gzip compression of most of the .snapshot
229 and .diff increment files stored in the rdiff-backup-data direc‐
230 tory. A backup volume can contain compressed and uncompressed
231 increments, so using this option inconsistently is fine.
232 --no-compression-regexp regexp
234 Do not compress increments based on files whose filenames match
235 regexp. The default includes many common audiovisual and ar‐
236 chive files, and may be found in Globals.py.
237 --no-file-statistics
239 This will disable writing to the file_statistics file in the
240 rdiff-backup-data directory. rdiff-backup will run slightly
241 quicker and take up a bit less space.
242 --no-hard-links
244 Don't replicate hard links on destination side. Note that
245 because metadata is written to a separate file, hard link infor‐
246 mation will not be lost even if the --no-hard-links option is
247 given (however, mirror files will not be linked). If many hard-
248 linked files are present, this option can drastically decrease
249 memory usage.
250 --null-separator
252 Use nulls (\0) instead of newlines (\n) as line separators,
253 which may help when dealing with filenames containing newlines.
254 This affects the expected format of the files specified by the
255 --{include|exclude}-filelist[-stdin] switches as well as the
256 format of the directory statistics file.
257 --parsable-output
259 If set, rdiff-backup's output will be tailored for easy parsing
260 by computers, instead of convenience for humans. Currently this
261 only applies when listing increments using the -l or --list-
262 increments switches, where the time will be given in seconds
263 since the epoch.
264 --print-statistics
266 If set, summary statistics will be printed after a successful
267 backup If not set, this information will still be available from
268 the session statistics file. See the STATISTICS section for
269 more information.
270 -r, --restore-as-of restore_time
272 Restore the specified directory as it was as of restore_time.
273 See the TIME FORMATS section for more information on the format
274 of restore_time, and see the RESTORING section for more informa‐
275 tion on restoring.
276 --remote-schema schema
278 Specify an alternate method of connecting to a remote computer.
279 This is necessary to get rdiff-backup not to use ssh for remote
280 backups, or if, for instance, rdiff-backup is not in the PATH on
281 the remote side. See the REMOTE OPERATION section for more
282 information.
283 --remove-older-than time_spec
285 Remove the incremental backup information in the destination
286 directory that has been around longer than the given time.
287 time_spec can be either an absolute time, like "2002-01-04", or
288 a time interval. The time interval is an integer followed by
289 the character s, m, h, D, W, M, or Y, indicating seconds, min‐
290 utes, hours, days, weeks, months, or years respectively, or a
291 number of these concatenated. For example, 32m means 32 min‐
292 utes, and 3W2D10h7s means 3 weeks, 2 days, 10 hours, and 7 sec‐
293 onds. In this context, a month means 30 days, a year is 365
294 days, and a day is always 86400 seconds.
295 rdiff-backup cannot remove-older-than and back up or restore in
297 a single session. In order to both backup a directory and
298 remove old files in it, you must run rdiff-backup twice.
299 By default, rdiff-backup will only delete information from one
301 session at a time. To remove two or more sessions at the same
302 time, supply the --force option (rdiff-backup will tell you if
303 --force is required).
304 Note that snapshots of deleted files are covered by this opera‐
306 tion. Thus if you deleted a file two weeks ago, backed up imme‐
307 diately afterwards, and then ran rdiff-backup with --remove-
308 older-than 10D today, no trace of that file would remain.
309 Finally, file selection options such as --include and --exclude
310 don't affect --remove-older-than.
311 --restrict path
313 Require that all file access be inside the given path. This
314 switch, and the following two, are intended to be used with the
315 --server switch to provide a bit more protection when doing
316 automated remote backups. They are not intended as your only
317 line of defense so please don't do something silly like allow
318 public access to an rdiff-backup server run with --restrict-
319 read-only.
320 --restrict-read-only path
322 Like --restrict, but also reject all write requests.
323 --restrict-update-only path
325 Like --restrict, but only allow writes as part of an incremental
326 backup. Requests for other types of writes (for instance,
327 deleting path) will be rejected.
328 --server
330 Enter server mode (not to be invoked directly, but instead used
331 by another rdiff-backup process on a remote computer).
332 --ssh-no-compression
334 When running ssh, do not use the -C option to enable compres‐
335 sion. --ssh-no-compression is ignored if you specify a new
336 schema using --remote-schema.
337 --terminal-verbosity [0-9]
339 Select which messages will be displayed to the terminal. If
340 missing the level defaults to the verbosity level.
341 --test-server
343 Test for the presence of a compatible rdiff-backup server as
344 specified in the following host::filename argument(s). The
345 filename section will be ignored.
346 --user-mapping-file filename
348 Map user names and ids according to the user mapping file file‐
349 name. See the USERS and GROUPS section for more information.
350 -v[0-9], --verbosity [0-9]
352 Specify verbosity level (0 is totally silent, 3 is the default,
353 and 9 is noisiest). This determines how much is written to the
354 log file.
355 -V, --version
357 Print the current version and exit
358
361 There are two ways to tell rdiff-backup to restore a file or directory.
362 Firstly, you can run rdiff-backup on a mirror file and use the -r or
363 --restore-as-of options. Secondly, you can run it on an increment
364 file.
365 For example, suppose in the past you have run:
367 rdiff-backup /usr /usr.backup
369 to back up the /usr directory into the /usr.backup directory, and now
371 want a copy of the /usr/local directory the way it was 3 days ago
372 placed at /usr/local.old.
373 One way to do this is to run:
375 rdiff-backup -r 3D /usr.backup/local /usr/local.old
377 where above the "3D" means 3 days (for other ways to specify the time,
379 see the TIME FORMATS section). The /usr.backup/local directory was
380 selected, because that is the directory containing the current version
381 of /usr/local.
382 Note that the option to --restore-as-of always specifies an exact time.
384 (So "3D" refers to the instant 72 hours before the present.) If there
385 was no backup made at that time, rdiff-backup restores the state
386 recorded for the previous backup. For instance, in the above case, if
387 "3D" is used, and there are only backups from 2 days and 4 days ago,
388 /usr/local as it was 4 days ago will be restored.
389 The second way to restore files involves finding the corresponding
391 increment file. It would be in the /backup/rdiff-backup-data/incre‐
392 ments/usr directory, and its name would be something like
393 "local.2002-11-09T12:43:53-04:00.dir" where the time indicates it is
394 from 3 days ago. Note that the increment files all end in ".diff",
395 ".snapshot", ".dir", or ".missing", where ".missing" just means that
396 the file didn't exist at that time (finally, some of these may be gzip-
397 compressed, and have an extra ".gz" to indicate this). Then running:
398 rdiff-backup /backup/rdiff-backup-data/incre‐
400 ments/usr/local.<time>.dir /usr/local.old
401 would also restore the file as desired.
403 If you are not sure exactly which version of a file you need, it is
405 probably easiest to either restore from the increments files as
406 described immediately above, or to see which increments are available
407 with -l/--list-increments, and then specify exact times into
408 -r/--restore-as-of.
409
412 rdiff-backup uses time strings in two places. Firstly, all of the
413 increment files rdiff-backup creates will have the time in their file‐
414 names in the w3 datetime format as described in a w3 note at
415 http://www.w3.org/TR/NOTE-datetime. Basically they look like
416 "2001-07-15T04:09:38-07:00", which means what it looks like. The
417 "-07:00" section means the time zone is 7 hours behind UTC.
418 Secondly, the -r, --restore-as-of, and --remove-older-than options take
420 a time string, which can be given in any of several formats:
421 1. the string "now" (refers to the current time)
423 2. a sequences of digits, like "123456890" (indicating the time in
425 seconds after the epoch)
426 3. A string like "2002-01-25T07:00:00+02:00" in datetime format
428 4. An interval, which is a number followed by one of the characters
430 s, m, h, D, W, M, or Y (indicating seconds, minutes, hourse,
431 days, weeks, months, or years respectively), or a series of such
432 pairs. In this case the string refers to the time that preceded
433 the current time by the length of the interval. For instance,
434 "1h78m" indicates the time that was one hour and 78 minutes ago.
435 The calendar here is unsophisticated: a month is always 30 days,
436 a year is always 365 days, and a day is always 86400 seconds.
437 5. A date format of the form YYYY/MM/DD, YYYY-MM-DD, MM/DD/YYYY, or
439 MM/DD/YYYY, which indicates midnight on the day in question,
440 relative to the current timezone settings. For instance,
441 "2002/3/5", "03-05-2002", and "2002-3-05" all mean March 5th,
442 2002.
443 6. A backup session specification which is a non-negative integer
445 followed by 'B'. For instance, '0B' specifies the time of the
446 current mirror, and '3B' specifies the time of the 3rd newest
447 increment.
448
451 In order to access remote files, rdiff-backup opens up a pipe to a copy
452 of rdiff-backup running on the remote machine. Thus rdiff-backup must
453 be installed on both ends. To open this pipe, rdiff-backup first
454 splits the filename into host_info::pathname. It then substitutes
455 host_info into the remote schema, and runs the resulting command, read‐
456 ing its input and output.
457 The default remote schema is 'ssh -C %s rdiff-backup --server' where
459 host_info is substituted for '%s'. So if the host_info is
460 user@host.net, then rdiff-backup runs 'ssh user@host.net rdiff-backup
461 --server'. Using --remote-schema, rdiff-backup can invoke an arbitrary
462 command in order to open up a remote pipe. For instance,
463 rdiff-backup --remote-schema 'cd /usr; %s' foo 'rdiff-backup
464 --server'::bar
465 is basically equivalent to (but slower than)
466 rdiff-backup foo /usr/bar
467 Concerning quoting, if for some reason you need to put two consecutive
469 colons in the host_info section of a host_info::pathname argument, or
470 in the pathname of a local file, you can quote one of them by prepend‐
471 ing a backslash. So in 'a\::b::c', host_info is 'a::b' and the path‐
472 name is 'c'. Similarly, if you want to refer to a local file whose
473 filename contains two consecutive colons, like 'strange::file', you'll
474 have to quote one of the colons as in 'strange\::file'. Because the
475 backslash is a quote character in these circumstances, it too must be
476 quoted to get a literal backslash, so 'foo\::\\bar' evaluates to
477 'foo::\bar'. To make things more complicated, because the backslash is
478 also a common shell quoting character, you may need to type in '\\\\'
479 at the shell prompt to get a literal backslash (if it makes you feel
480 better, I had to type in 8 backslashes to get that in this man
481 page...). And finally, to include a literal % in the string specified
482 by --remote-schema, quote it with another %, as in %%.
483 Although ssh itself may be secure, using rdiff-backup in the default
485 way presents some security risks. For instance if the server is run as
486 root, then an attacker who compromised the client could then use rdiff-
487 backup to overwrite arbitary server files by "backing up" over them.
488 Such a setup can be made more secure by using the sshd configuration
489 option command="rdiff-backup --server" possibly along with the
490 --restrict* options to rdiff-backup. For more information, see the web
491 page, the wiki, and the entries for the --restrict* options on this man
492 page.
493
496 rdiff-backup has a number of file selection options. When rdiff-backup
497 is run, it searches through the given source directory and backs up all
498 the files matching the specified options. This selection system may
499 appear complicated, but it is supposed to be flexible and easy-to-use.
500 If you just want to learn the basics, first look at the selection exam‐
501 ples in the examples.html file included in the package, or on the web
502 at http://rdiff-backup.nongnu.org/examples.html
503 rdiff-backup's selection system was originally inspired by rsync(1),
505 but there are many differences. (For instance, trailing backslashes
506 have no special significance.)
507 The file selection system comprises a number of file selection condi‐
509 tions, which are set using one of the following command line options:
510 --exclude, --exclude-filelist, --exclude-device-files, --exclude-fifos,
511 --exclude-sockets, --exclude-symbolic-links, --exclude-globbing-
512 filelist, --exclude-globbing-filelist-stdin, --exclude-filelist-stdin,
513 --exclude-regexp, --exclude-special-files, --include, --include-
514 filelist, --include-globbing-filelist, --include-globbing-filelist-
515 stdin, --include-filelist-stdin, and --include-regexp. Each file
516 selection condition either matches or doesn't match a given file. A
517 given file is excluded by the file selection system exactly when the
518 first matching file selection condition specifies that the file be
519 excluded; otherwise the file is included. When backing up, if a file
520 is excluded, rdiff-backup acts as if that file does not exist in the
521 source directory. When restoring, an excluded file is considered not
522 to exist in either the source or target directories.
523 For instance,
525 rdiff-backup --include /usr --exclude /usr /usr /backup
527 is exactly the same as
529 rdiff-backup /usr /backup
531 because the include and exclude directives match exactly the same
533 files, and the --include comes first, giving it precedence. Similarly,
534 rdiff-backup --include /usr/local/bin --exclude /usr/local /usr
536 /backup
537 would backup the /usr/local/bin directory (and its contents), but not
539 /usr/local/doc.
540 The include, exclude, include-globbing-filelist, and exclude-globbing-
542 filelist options accept extended shell globbing patterns. These pat‐
543 terns can contain the special patterns *, **, ?, and [...]. As in a
544 normal shell, * can be expanded to any string of characters not con‐
545 taining "/", ? expands to any character except "/", and [...] expands
546 to a single character of those characters specified (ranges are accept‐
547 able). The new special pattern, **, expands to any string of charac‐
548 ters whether or not it contains "/". Furthermore, if the pattern
549 starts with "ignorecase:" (case insensitive), then this prefix will be
550 removed and any character in the string can be replaced with an upper-
551 or lowercase version of itself.
552 Remember that you may need to quote these characters when typing them
554 into a shell, so the shell does not interpret the globbing patterns
555 before rdiff-backup sees them.
556 The --exclude pattern option matches a file iff:
558 1. pattern can be expanded into the file's filename, or
560 2. the file is inside a directory matched by the option.
562 Conversely, --include pattern matches a file iff:
564 1. pattern can be expanded into the file's filename,
566 2. the file is inside a directory matched by the option, or
568 3. the file is a directory which contains a file matched by the
570 option.
571 For example,
573 --exclude /usr/local
575 matches /usr/local, /usr/local/lib, and /usr/local/lib/netscape. It is
577 the same as --exclude /usr/local --exclude '/usr/local/**'.
578 --include /usr/local
580 specifies that /usr, /usr/local, /usr/local/lib, and
582 /usr/local/lib/netscape (but not /usr/doc) all be backed up. Thus you
583 don't have to worry about including parent directories to make sure
584 that included subdirectories have somewhere to go. Finally,
585 --include ignorecase:'/usr/[a-z0-9]foo/*/**.py'
587 would match a file like /usR/5fOO/hello/there/world.py. If it did
589 match anything, it would also match /usr. If there is no existing file
590 that the given pattern can be expanded into, the option will not match
591 /usr.
592 The --include-filelist, --exclude-filelist, --include-filelist-stdin,
594 and --exclude-filelist-stdin options also introduce file selection con‐
595 ditions. They direct rdiff-backup to read in a file, each line of
596 which is a file specification, and to include or exclude the matching
597 files. Lines are separated by newlines or nulls, depending on whether
598 the --null-separator switch was given. Each line in a filelist is
599 interpreted similarly to the way extended shell patterns are, with a
600 few exceptions:
601 1. Globbing patterns like *, **, ?, and [...] are not expanded.
603 2. Include patterns do not match files in a directory that is
605 included. So /usr/local in an include file will not match
606 /usr/local/doc.
607 3. Lines starting with "+ " are interpreted as include directives,
609 even if found in a filelist referenced by --exclude-filelist.
610 Similarly, lines starting with "- " exclude files even if they
611 are found within an include filelist.
612 For example, if the file "list.txt" contains the lines:
614 /usr/local
616 - /usr/local/doc
617 /usr/local/bin
618 + /var
619 - /var
620 then "--include-filelist list.txt" would include /usr, /usr/local, and
622 /usr/local/bin. It would exclude /usr/local/doc,
623 /usr/local/doc/python, etc. It neither excludes nor includes
624 /usr/local/man, leaving the fate of this directory to the next specifi‐
625 cation condition. Finally, it is undefined what happens with /var. A
626 single file list should not contain conflicting file specifications.
627 The --include-globbing-filelist and --exclude-globbing-filelist options
629 also specify filelists, but each line in the filelist will be inter‐
630 preted as a globbing pattern the way --include and --exclude options
631 are interpreted (although "+ " and "- " prefixing is still allowed).
632 For instance, if the file "globbing-list.txt" contains the lines:
633 dir/foo
635 + dir/bar
636 - **
637 Then "--include-globbing-filelist globbing-list.txt" would be exactly
639 the same as specifying "--include dir/foo --include dir/bar --exclude
640 **" on the command line.
641 Finally, the --include-regexp and --exclude-regexp allow files to be
643 included and excluded if their filenames match a python regular expres‐
644 sion. Regular expression syntax is too complicated to explain here,
645 but is covered in Python's library reference. Unlike the --include and
646 --exclude options, the regular expression options don't match files
647 containing or contained in matched files. So for instance
648 --include '[0-9]{7}(?!foo)'
650 matches any files whose full pathnames contain 7 consecutive digits
652 which aren't followed by 'foo'. However, it wouldn't match /home even
653 if /home/ben/1234567 existed.
654
657 There can be complications preserving ownership across systems. For
658 instance the username that owns a file on the source system may not
659 exist on the destination. Here is how rdiff-backup maps ownership on
660 the source to the destination:
661 1. Attempt to preserve the user and group names for ownership and
664 in ACLs. This may result in files having different uids and
665 gids across systems.
666 2. If this fails (e.g. because the username does not exist), pre‐
668 serve the original id, but only in cases of user and group own‐
669 ership. For ACLs, omit any entry that has a bad user or group
670 name.
671 3. However, the --user-mapping-file and --group-mapping-file
673 options can override this behavior. If either of these options
674 is given, the policy descriped in 1 and 2 above will be fol‐
675 lowed, but with the mapped user and group instead of the origi‐
676 nal.
677 The user and group mapping files both have the same form:
679 old_name_or_id1:new_name_or_id1
681 old_name_or_id2:new_name_or_id2
682 <etc>
683 Each line should contain a name or id, followed by a colon ":", fol‐
685 lowed by another name or id. If a name or id is not listed, they are
686 treated in the default way described above.
687
690 Every session rdiff-backup saves various statistics into two files, the
691 session statistics file at rdiff-backup-data/session_statis‐
692 tics.<time>.data and the directory statistics file at rdiff-backup-
693 data/directory_statistics.<time>.data. They are both text files and
694 contain similar information: how many files changed, how many were
695 deleted, the total size of increment files created, etc. However, the
696 session statistics file is intended to be very readable and only
697 describes the session as a whole. The directory statistics file is
698 more compact (and slightly less readable) but describes every directory
699 backed up. It also may be compressed to save space.
700 Statistics related options include --print-statistics and --null-sepa‐
702 rator.
703 Also, rdiff-backup will save various messages to the log file, which is
705 rdiff-backup-data/backup.log for backup sessions and rdiff-backup-
706 data/restore.log for restore sessions. Generally what is written to
707 this file will coincide with the messages diplayed to stdout or stderr,
708 although this can be changed with the --terminal-verbosity option.
709 The log file is not compressed and can become quite large if rdiff-
711 backup is run with high verbosity.
712
715 If rdiff-backup finishes successfully, the exit status will be 0. If
716 there is an unrecoverable (critical) error, it will be non-zero (usu‐
717 ally 1, but don't depend on this specific value). When setting up
718 rdiff-backup to run automatically (as from cron(8) or similar) it is
719 probably a good idea to check the exit code.
720
723 Files whose names are close to the maximum length (e.g. 235 chars if
724 the maximum is 255) may be skipped because the filenames of related
725 increment files would be too long.
726 The gzip library in versions 2.2 and earlier of python (but fixed in
728 2.3a1) has trouble producing files over 2GB in length. This bug will
729 prevent rdiff-backup from producing large compressed increments (snap‐
730 shots or diffs). A workaround is to disable compression for large
731 uncompressable files.
732
735 Ben Escoto <ben@emerose.org>
736 Feel free to ask me questions or send me bug reports, but you may want
738 to see the web page, mentioned below, first.
739
742 python(1), rdiff(1), rsync(1), ssh(1). The main rdiff-backup web page
743 is at http://www.nongnu.org/rdiff-backup/. It has more information,
744 links to the mailing list and CVS, etc.
745Version 1.0.5 November 2006 RDIFF-BACKUP(1)