1RDIFF-BACKUP(1)                  Manual 2.2.2                  RDIFF-BACKUP(1)
2
3
4

NAME

6       rdiff-backup - local/remote mirror and incremental backup
7

SYNOPSIS

9       rdiff-backup [options...] action [sub-options...] [locations...]
10       rdiff-backup [--new] [-h|--help|-V|--version]
11

DESCRIPTION

13       rdiff-backup is a script, written in python(1) that backs up one
14       directory to another. The target directory ends up a copy (mirror) of
15       the source directory, but extra reverse diffs are stored in a special
16       sub-directory of that target directory, so you can still recover files
17       lost some time ago. The idea is to combine the best features of a
18       mirror and an incremental backup. rdiff-backup also preserves symlinks,
19       special files, hardlinks, permissions, uid/gid ownership, and
20       modification times.
21
22       rdiff-backup can also operate in a bandwidth efficient manner over a
23       pipe, like rsync(1). Thus you can use ssh and rdiff-backup to securely
24       back a hard drive up to a remote location, and only the differences
25       will be transmitted. Using the default settings, rdiff-backup requires
26       that the remote system accept ssh connections, and that rdiff-backup is
27       installed in the user’s PATH on the remote system. See the REMOTE
28       OPERATION section for details.
29
30       Note that you should not write to the mirror directory except with
31       rdiff-backup. Many of the increments are stored as reverse diffs, so if
32       you delete or modify a file, you may lose the ability to restore
33       previous versions of that file.
34
35       Finally, this man page is intended more as a precise description of the
36       behavior and syntax of rdiff-backup. New users may want to check out
37       the examples file included in the rdiff-backup distribution.
38
39       The rdiff-backup commands knows four types of parameters
40
41        1. generic options valid for all actions,
42
43        2. one action out of backup, calculate, complete, compare, info, list,
44           regress, remove, restore, server, test, verify,
45
46        3. sub-options applicable to each action specifically, even though
47           some are common to multiple actions,
48
49        4. zero, one, two or more location paths, either local or remote.
50
51       Note that this documents the new command line interface of rdiff-backup
52       since 2.1+; for the traditional one, check rdiff-backup-old(1) but
53       consider that it is deprecated and will disappear.
54
55   Options
56       -h, --help
57           Prints brief usage information and exits. Add --new to be sure to
58           get this CLI description, and not the old one. Placed after the
59           action, outputs the action’s specific help message.
60
61       -V, --version
62           Prints the current version number and exits.
63
64       --api-version apiversion
65           Sets the API version to the given integer between minimum and
66           maximum versions as given by the info action. It is the
67           responsibility of the user to make sure that this version is also
68           supported by any server started by this client.
69
70       --chars-to-quote, --override-chars-to-quote chars
71           If the filesystem to which we are backing up is not case-sensitive,
72           automatic "quoting" of characters occurs. For example, a file
73           'Developer.doc' will be converted into ';068eveloper.doc'. To quote
74           other characters or force quoting, e.g. in case rdiff-backup
75           doesn’t recognize a case-insensitive file system, you need to
76           specify this option. chars is a string of characters fit to be used
77           in regexp square brackets (e.g. 'A-Z' as in '[A-Z]').
78
79               Caution
80               do NOT change the chars to quote within the same repository!
81               Actually, you only need to set this parameter when creating a
82               new backup repository. Do also NOT quote any character used by
83               rdiff-backup in rdiff-backup-data (any of 'a-z0-9._-')!
84
85       --current-time currenttime
86           This option is useful mainly for testing. If set, rdiff-backup will
87           use it for the current time instead of consulting the clock. The
88           argument is the number of seconds since the epoch.
89
90       --force
91           Authorize a more drastic modification of a directory than usual
92           (for instance, when overwriting of a destination path, or when
93           removing multiple sessions with remove). rdiff-backup will
94           generally tell you if it needs this.
95
96               Caution
97               You can cause data loss if you mis-use this option.
98               Furthermore, do NOT use this option when doing a restore, as it
99               will DELETE files, unless you absolutely know what you are
100               doing.
101
102       --fsync, --no-fsync
103           This will enable/disable issuing fsync from rdiff-backup
104           altogether. This option is designed to optimize performance on busy
105           backup systems.
106
107               Caution
108               This may render your backup unusable in case of filesystem
109               failure. Default is hence for fsync to be enabled.
110
111       --new, --no-new
112           enforce (or not) the usage of the new parameters. The default
113           currently is to show the old usage, but this will change in the
114           near future.
115
116       --null-separator
117           Use nulls (\0) instead of newlines (\n) as line separators, which
118           may help when dealing with filenames containing newlines. This
119           affects the expected format of the files specified by the
120           --{include|exclude}-filelist[-stdin] switches as well as the format
121           of the files statistics.
122
123       --parsable-output
124           If set, rdiff-backup’s output will be tailored for easy parsing by
125           computers, instead of convenience for humans. Currently this only
126           applies when listing increments using the list increments action,
127           where the time will be given in seconds since the epoch.
128
129       --remote-schema remoteschema
130           Specify an alternate method of connecting to a remote computer.
131           This is necessary to get rdiff-backup not to use ssh for remote
132           backups, or if, for instance, rdiff-backup is not in the PATH on
133           the remote side. See the REMOTE OPERATION section for details.
134
135       --remote-tempdir dirpath
136           use path as temporary directory on the remote side of the
137           connection. If set explicitly, remember that "no space left" error
138           messages might apply to this directory.
139
140       --ssh-compression, --no-ssh-compression
141           use SSH with or without compression with default remote-schema.
142           This option is ignored when using --remote-schema. Compression is
143           on by default.
144
145       --tempdir dirpath
146           Sets the directory that rdiff-backup uses for temporary files to
147           the given path. The environment variables TMPDIR, TEMP, and TMP can
148           also be used to set the temporary files directory. See the
149           documentation of the Python tempfile module for more information.
150           If set explicitly, remember that "no space left" error messages
151           might apply to this directory.
152
153       --terminal-verbosity {0,1,2,3,4,5,6,7,8,9}
154           select which verbosity to use for messages on the terminal, the
155           default is given by --verbosity.
156
157       --use-compatible-timestamps
158           Create timestamps in which the hour/minute/second separator is a -
159           (hyphen) instead of a : (colon). It is safe to use this option on
160           one backup, and then not use it on another; rdiff-backup supports
161           the intermingling of different timestamp formats. This option is
162           enabled by default on platforms which require that the colon be
163           escaped.
164
165       -v, --verbosity {0,1,2,3,4,5,6,7,8,9}
166           Specify verbosity level (0 is totally silent, 3 is the default, and
167           9 is noisiest). This determines how much is written to the log
168           file, and without using --terminal-verbosity to the terminal..
169
170   Actions
171       backup [CREATION OPTIONS] [COMPRESSION OPTIONS] [SELECTION OPTIONS]
172       [FILESYSTEM OPTIONS] [USER GROUP OPTIONS] [STATISTICS OPTIONS]
173       sourcedir targetdir
174           back-up a source directory to a target backup repository.
175
176       calculate [--method average] statfile1 statfile2 [...]
177           calculate average across multiple statistics files
178
179           --method average
180               there is currently only one method and it is the default, but
181               it might change in the future.
182
183       complete [--cword index] [--unique|--no-unique] -- words [...]
184           outputs a list of fitting options given already entered parameters.
185           This option is of no relevance to backup tasks, it is only to be
186           used to support programmatic completion like in bash. See the
187           documentation for more details if you plan to write your own
188           completion code, e.g. for an alternative shell.
189
190           --cword index
191               index where the cursor currently is within the list of words.
192
193           --unique,--no-unique
194               should parameters already entered by the user be offered again,
195               or not?
196
197       compare [SELECTION OPTIONS] [--method method] [--at time] sourcedir
198       targetdir
199           Compare a directory with the backup set at the given time. This can
200           be useful to see how archived data differs from current data, or to
201           check that a backup is current.
202
203           --method method
204               method used to compare can be either meta, full or hash, where
205               the default is meta, which is also how rdiff-backup decides
206               which file needs to be backed-up. Note that with full, the
207               repository data will be copied in its entirety to the source
208               side and compared byte by byte. This is the slowest but most
209               complete compare method. With hash only the SHA1 checksum of
210               regular files will be compared. With meta only the metadata of
211               files will be compared (name, size, date, type, etc).
212
213           --at time
214               at which time of the back-up directory should the comparaison
215               take place. The default is now, meaning the latest version. See
216               TIME FORMATS for details.
217
218       info
219           outputs information about the current system in YAML format, so
220           that it can be used in a bug report, and exits.
221
222       list files [--changed-since time|--at time] repository
223           list modified or existing files in a given back-up repository.
224
225           --changed-since time
226               List the files that have changed in the destination directory
227               since the given time. See TIME FORMATS for the format of time.
228               If a directory in the archive is specified, list only the files
229               under that directory. This option does not read the source
230               directory; it is used to compare the contents of two different
231               rdiff-backup sessions. See TIME FORMATS for details.
232
233           --at time
234               List the files in the archive that were present at the given
235               time. If a directory in the archive is specified, list only the
236               files under that directory. See TIME FORMATS for details.
237
238       list increments [--no-size|--size] repository
239           list increments with date in a given back-up repository.
240
241           --no-size,--size
242               Show or not the size of each increment in the repository. The
243               default is to not show sizes. When showing sizes, it becomes
244               allowable to specify a directory within a repository, then only
245               the cumulated sizes of that directory will be shown.
246
247       regress [COMPRESSION OPTIONS] [USER GROUP OPTIONS] [TIMESTAMP OPTIONS]
248       repository
249           If an rdiff-backup session fails, this action will undo the failed
250           directory. This happens automatically if you attempt to back-up to
251           a directory and the last backup failed. You can use the --force
252           option to undo the last backup even if it wasn’t failed.
253
254       remove increments --older-than time [--size] repository
255           Remove the incremental backup information in the destination
256           directory that has been around longer than the given time, or the
257           oldest one if no time is provided.
258
259           By default, rdiff-backup will only delete information from one
260           session at a time. To remove two or more sessions at the same time,
261           supply the --force option (rdiff-backup will tell you if it is
262           required).
263
264           Note that snapshots of deleted files are covered by this operation.
265           Thus if you deleted a file two weeks ago, backed up immediately
266           afterwards, and then ran rdiff-backup with 'remove increments
267           --older-than 10D' today, no trace of that file would remain.
268
269           --older-than time
270               all the increments older than the given time will be deleted.
271               See TIME FORMATS for details.
272
273           --size
274               Show the size of each increment being removed. The default is
275               to not show sizes.
276
277       restore [CREATION OPTIONS] [COMPRESSION OPTIONS] [SELECTION OPTIONS]
278       [FILESYSTEM OPTIONS] [USER GROUP OPTIONS] [--at time|--increment]
279       source targetdir
280           restore a source backup repository at a specific time or a specific
281           source increment to a target directory. See RESTORING for details.
282
283           --at time
284               the source parameter is interpreted as a back-up directory, and
285               the content is restored from the given time. See TIME FORMATS
286               for details.
287
288           --increment
289               the source parameter is expected to be an increment within a
290               back-up repository, to be restored into the given target
291               directory.
292
293       server [RESTRICT OPTIONS] [--debug]
294           Enter server mode (not to be invoked directly, but instead used by
295           another rdiff-backup process on a remote computer).
296
297           --debug
298               Start the server in debug mode so that it stops on an early
299               breakpoint and can be remotely debugged using rpdb
300               <https://github.com/tamentis/rpdb>. See the developer’s
301               documentation
302               <https://github.com/rdiff-backup/rdiff-backup/blob/master/docs/DEVELOP.adoc#debug-client-server-mode>
303               for details.
304
305       test remote_location_1 [remote_location_2 ...]
306           Test for the presence of a compatible rdiff-backup server as
307           specified in the remote location argument(s) (of which the filename
308           section will be checked for existence). See the REMOTE OPERATION
309           section for details.
310
311       verify [--at time] location
312           Check all the data in the repository at the given time by computing
313           the SHA1 hash of all the regular files and comparing them with the
314           hashes stored in the metadata file.
315
316           --at time
317               the time of the data which needs to be verified. See TIME
318               FORMATS for details.
319

COMPRESSION OPTIONS

321       --compression, --no-compression
322           Enable or disable the default gzip compression of most of the
323           .snapshot and .diff increment files stored in the rdiff-backup-data
324           directory. A backup volume can contain compressed and uncompressed
325           increments, so using this option inconsistently is fine. Default is
326           to compress all files, except those excluded as noted below.
327
328       --not-compressed-regexp regexp
329           Do not compress increments based on files whose filenames match
330           regexp. The default includes many common audiovisual and archive
331           files, and may be found from the help.
332

CREATION OPTIONS

334       --create-full-path
335           Normally only the final directory of the destination path will be
336           created if it does not exist. With this option, all missing
337           directories on the destination path will be created. Use this
338           option with care: if there is a typo in the remote path, the remote
339           filesystem could fill up very quickly (by creating a duplicate
340           backup tree). For this reason this option is primarily aimed at
341           scripts which automate backups.
342

FILESYSTEM OPTIONS

344       --acls, --no-acls
345           enable/disable back-up of Access Control Lists.
346
347       --carbonfile, --no-carbonfile
348           enable/disable back-up of carbon files (MacOS X).
349
350       --eas, --no-eas
351           enable/disable back-up of Extended Attributes.
352
353       --resource-forks, --no-resource-forks
354           enable/disable back-up of resource forks (MacOS X).
355
356       --hard-links, --no-hard-links
357           do (or not) keep hard-link relationships between files. Disabling
358           hard-links generally increases the disk space usage but decreases
359           memory usage. Hard-links are disabled by default if the backup
360           source or restore destination is running on native Windows.
361
362       --compare-inode, --no-compare-inode
363           This option prevents rdiff-backup from flagging a hardlinked file
364           as changed when its device number and/or inode changes. This option
365           is useful in situations where the source filesystem lacks
366           persistent device and/or inode numbering. For example, network
367           filesystems may have mount-to-mount differences in their device
368           number (but possibly stable inode numbers); USB/1394 devices may
369           come up at different device numbers each remount (but would
370           generally have same inode number); and there are filesystems which
371           don’t even have the same inode numbers from use to use. Without the
372           option rdiff-backup may generate unnecessary numbers of tiny diff
373           files.
374
375       --never-drop-acls
376           Exit with error instead of dropping ACLs or ACL entries. Normally
377           this may happen (with a warning) because the destination does not
378           support them or because the relevant user/group names do not exist
379           on the destination side.
380

RESTRICT OPTIONS

382       --restrict-path dirpath
383           Require that all file access be inside the given path. This switch,
384           and --restrict-mode, are intended to be used with the server action
385           to provide a bit more protection when doing automated remote
386           backups.
387
388               Caution
389               Those options are not intended as your only line of defense so
390               please don’t do something silly like allow public access to an
391               rdiff-backup server run with --restrict-mode read-only.
392
393       --restrict-mode {read-write,read-only,update-only}
394           restriction mode for the directory given by --restrict-path, either
395           full access (aka read-write), read-only, or only to update
396           incrementally an already existing back-up (default is read-write).
397

SELECTION OPTIONS

399       This section only quickly lists the existing options, the section FILE
400       SELECTION explains those more in details.
401
402   Globs, Regex, File lists selection
403       --include,--exclude glob
404           Include/exclude the file or files matched by glob (also known as
405           shell pattern). If a directory is excluded, then files under that
406           directory will also be excluded.
407
408       --include-globbing-filelist,--exclude-globbing-filelist globsfile
409           Include/exclude according to the listed globs, similar to --include
410           or --exclude.
411
412       --include-globbing-filelist-stdin,--exclude-globbing-filelist-stdin
413           Like the previous option but the list of globs is coming from
414           standard input.
415
416       --include-regexp,--exclude-regexp regexp
417           Include/exclude files matching the given regexp (according to
418           Python rules).
419
420       --include-filelist,--exclude-filelist listfile
421           Include/exclude the files listed in filelist. This is a best fit
422           for an automatically generated list of files, else use globbing.
423
424       --include-filelist-stdin,--exclude-filelist-stdin
425           Like the previous but the filelist is coming from standard input.
426
427   Special files selection
428           Note
429           All special files are included by default, so that including them
430           explicitly isn’t generally required. Exceptions are described.
431
432       --include-device-files,--exclude-device-files
433           Include/exclude all device files. This can be useful for
434           security/permissions reasons or if rdiff-backup is not handling
435           device files correctly.
436
437       --include-fifos,--exclude-fifos
438           Include/exclude all fifo files.
439
440       --include-sockets,--exclude-sockets
441           Include/exclude all socket files.
442
443       --include-symbolic-links,--exclude-symbolic-links
444           Include/exclude all symbolic links. Contrary to the general rule,
445           symlinks are excluded by default under Windows so that NTFS reparse
446           points aren’t backed-up.
447
448       --include-special-files,--exclude-special-files
449           Include/exclude all the special files listed above.
450
451   Other selections
452       --include-other-filesystems,--exclude-other-filesystems
453           Include/exclude files on file systems (identified by device number)
454           other than the file system the root of the source directory is on.
455           The default is to include other filesystems.
456
457       --include-if-present,--exclude-if-present filename
458           Include/exclude directories if they contain the given filename.
459           Files directly in an included directory are also considered
460           included. This doesn’t apply recursively though so that the
461           filename must be present in all directories of a hierarchy for it
462           to be fully included.
463
464       --max-file-size sizeinbytes
465           Exclude files that are larger than the given size in bytes.
466
467       --min-file-size sizeinbytes
468           Exclude files that are smaller than the given size in bytes.
469

STATISTICS OPTIONS

471       --file-statistics, --no-file-statistics
472           Enable/disable writing to the 'file_statistics' file in the
473           rdiff-backup-data directory. rdiff-backup will run slightly quicker
474           and take up a bit less space. Default is to write the statistics
475           file(s).
476
477           See the FILES section for more information about statistics files.
478
479       --no-print-statistics, --print-statistics
480           Summary statistics will be printed (or not) after a successful
481           backup. Even if disabled (the default), this information will still
482           be available from the session statistics file.
483

TIMESTAMP OPTIONS

485       --allow-duplicate-timestamps
486           This option is only to be used if you encounter the issue of
487           metadata mirrors with the same timestamp. In such cases, you may
488           use this flag to first recover from the failed backup with
489           something like
490
491               rdiff-backup --allow-duplicate-timestamps \
492                            --check-destination-dir {targetdir}
493
494           after which you will need to remove those old duplicate entries
495           using the remove increments action.
496

USER GROUP OPTIONS

498       See the USERS AND GROUPS section for more information.
499
500       --group-mapping-file mapfile
501           Map group names and IDs according to the group mapping file
502           mapfile.
503
504       --user-mapping-file mapfile
505           Map user names and IDs according to the user mapping file mapfile.
506
507       --preserve-numerical-ids
508           If set, rdiff-backup will preserve uids/gids instead of trying to
509           preserve unames and gnames.
510

RESTORING

512       There are two ways to tell rdiff-backup to restore a file or directory:
513
514        1. you can run rdiff-backup restore on a mirror file and define a time
515           from which to restore (by default the latest one).
516
517        2. you can run the restore action on an increment file with the
518           sub-option --increment.
519
520       For example, suppose in the past you have run:
521
522           rdiff-backup backup /usr /usr.backup
523
524       to back up the '/usr' directory into the '/usr.backup' directory, and
525       now want a copy of the '/usr/local' directory the way it was 3 days ago
526       placed at '/usr/local.old'.
527
528       One way to do this is to run:
529
530           rdiff-backup restore --at 3D /usr.backup/local /usr/local.old
531
532       here above the '3D' means 3 days (for other ways to specify the time,
533       see the TIME FORMATS section). The '/usr.backup/local' directory was
534       selected, because that is the directory containing the current version
535       of 'usr/local'.
536
537       Note that the parameter of --at always specifies an exact time. (So
538       '3D' refers to the moment 72 hours before the present). If there was no
539       backup made at that time, rdiff-backup restores the state recorded for
540       the previous backup. For instance, in the above case, if '3D' is used,
541       and there are only backups from 2 days and 4 days ago, '/usr/local' as
542       it was 4 days ago will be restored.
543
544       The second way to restore files involves finding the corresponding
545       increment file. It would be in the
546       '/backup/rdiff-backup-data/increments/usr' directory, and its name
547       would be something like 'local.2002-11-09T12:43:53-04:00.dir' where the
548       time indicates it is from 3 days ago. Note that the increment files all
549       end in '.diff', '.snapshot', '.dir', or '.missing', where '.missing'
550       just means that the file didn’t exist at that time (finally, some of
551       these may be gzip-compressed, and have an extra '.gz' to indicate
552       this). Then running:
553
554           rdiff-backup restore --increment \
555               /backup/rdiff-backup-data/increments/usr/local.{time}.dir \
556               /usr/local.old
557
558       would also restore the file as desired.
559
560       If you are not sure exactly which version of a file you need, it is
561       probably easiest to either restore from the increments files as
562       described immediately above, or to see which increments are available
563       with 'list increments', and then specify an exact time with --at.
564

TIME FORMATS

566       rdiff-backup uses time strings in two places.
567
568       Firstly, all of the increment files rdiff-backup creates will have the
569       time in their filenames in the w3 datetime format as described in a w3
570       note at https://www.w3.org/TR/NOTE-datetime. Basically they look like
571       '2001-07-15T04:09:38-07:00', which is basically
572       "{Year}-{Month}-{Day}T{Hours}:{Minutes}:{Seconds}{Timezone}", the time
573       zone being 7 hours behind UTC in this example (hence the minus).
574
575       Secondly, the --at, --changed-since, --older-than options take a time
576       string, which can be given in any of several formats:
577
578        1. the string 'now' (refers to the current time)
579
580        2. a sequences of digits, like '123456890' (indicating the time in
581           seconds after the epoch)
582
583        3. A string like '2002-01-25T07:00:00+02:00' in datetime format
584
585        4. An interval, which is a number followed by one of the characters s,
586           m, h, D, W, M, or Y (indicating seconds, minutes, hours, days,
587           weeks, months, or years respectively), or a series of such pairs.
588           In this case the string refers to the time that preceded the
589           current time by the length of the interval. For instance, '1h78m"'
590           indicates the time that was one hour and 78 minutes ago. The
591           calendar here is unsophisticated: a month is always 30 days, a year
592           is always 365 days, and a day is always 86400 seconds.
593
594        5. A date format of the form "YYYY/MM/DD", "YYYY-MM-DD", "MM/DD/YYYY",
595           or "MM-DD-YYYY", which indicates midnight on the day in question,
596           relative to the current timezone settings. For instance,
597           '2002/3/5', '03-05-2002', and '2002-3-05' all mean March 5th, 2002
598           (needless to say that starting with the year is less confusing for
599           non-Americans).
600
601        6. A backup session specification which is a non-negative integer
602           followed by 'B'. For instance, '0B' specifies the time of the
603           current mirror, and '3B' specifies the time of the 3rd newest
604           increment.
605

REMOTE OPERATION

607       In order to access remote files, rdiff-backup opens up a pipe to a copy
608       of rdiff-backup running on the remote machine. Thus rdiff-backup must
609       be installed on both ends. To open this pipe, rdiff-backup first splits
610       the location into 'host_info::pathname'. It then substitutes
611       'host_info' into the remote schema, and runs the resulting command,
612       reading its input and output.
613
614       The 'host_info' can be anything understood as a destination by your
615       version of SSH. Assuming it is the standard OpenSSH, it can be:
616
617       •   either '[user@]hostname'
618
619       •   or a URI of the form 'ssh://[user@]hostname[:port]'.
620
621       The default remote schema is 'ssh -C {h} rdiff-backup --server' where
622       'host_info' is substituted for '{h}'. So if the 'host_info' is
623       'user@host.net', then rdiff-backup runs 'ssh user@host.net rdiff-backup
624       --server'. Using --remote-schema, rdiff-backup can invoke an arbitrary
625       command in order to open up a remote pipe. For instance,
626
627           rdiff-backup backup --remote-schema 'cd /usr; {h}' \
628                               foo 'rdiff-backup server'::bar
629
630       is basically equivalent to (but slower than)
631
632           rdiff-backup backup foo /usr/bar
633
634       Concerning quoting, if for some reason you need to put two consecutive
635       colons in the 'host_info' section of a 'host_info::pathname' argument,
636       or in the pathname of a local file, you can quote one of them by
637       prepending a backslash. So in 'a\::b::c', 'host_info' is 'a::b' and the
638       pathname is 'c'. Similarly, if you want to refer to a local file whose
639       filename contains two consecutive colons, like 'strange::file', you’ll
640       have to quote one of the colons as in 'strange\::file'. Because the
641       backslash is a quote character in these circumstances, it too must be
642       quoted to get a literal backslash, so 'foo\::\\bar' evaluates to
643       'foo::\bar'. To make things more complicated, because the backslash is
644       also a common shell quoting character, you may need to type in '\\\\'
645       at the shell prompt to get a literal backslash.
646
647       You may also use the placehoders '{Vx}', '{Vy}' and '{Vz}' for the
648       'x.y.z' version of rdiff-backup, so that you can have multiple versions
649       of rdiff-backup installed on the server, and automatically targeted
650       from the client.
651
652       For example, if you have rdiff-backup 2.1.5 and 2.2.1 installed in
653       virtual environments on the server, respectively under
654       '/usr/local/lib/rdiff-backup-2.0' and '/usr/local/lib/rdiff-backup-2.1'
655       (we assume that the z-Version isn’t relevant to any kind of
656       compatibility), then the client may be called with the following remote
657       schema:
658
659           ssh -C {h} /usr/local/lib/rdiff-backup-{Vx}.{Vy} --server
660
661       The client will then use the correct version of rdiff-backup based on
662       its own version 'x.y.z'. You’ll find more explanations in the migration
663       file in the documentation.
664
665       And finally, to include a literal '%' in the string specified by
666       --remote-schema, quote it with another '%', as in '%%' (this is due to
667       the compatibility with the deprecated host placeholder '%s', which you
668       shouldn’t use anymore).
669
670       Although ssh itself may be secure, using rdiff-backup in the default
671       way presents some security risks. For instance if the server is run as
672       root, then an attacker who compromised the client could then use
673       rdiff-backup to overwrite arbitrary server files by "backing up" over
674       them. Such a setup can be made more secure by using the sshd
675       configuration option 'command="rdiff-backup server"' possibly along
676       with the --restrict-path and --restrict-mode options to rdiff-backup.
677       For more information, see the web page, the wiki, and the entries for
678       those options on this man page.
679

FILE SELECTION

681       rdiff-backup has a number of file selection options. When rdiff-backup
682       is run, it searches through the given source directory and backs up all
683       the files matching the specified options. This selection system may
684       appear complicated, but it is supposed to be flexible and easy-to-use.
685       If you just want to learn the basics, first look at the selection
686       examples in the examples file included in the package, or on the web at
687       https://rdiff-backup.net/docs/examples.html.
688
689       rdiff-backup’s selection system was originally inspired by rsync(1),
690       but there are many differences. For instance, trailing backslashes have
691       no special significance.
692
693           Important
694           include and exclude patterns under Windows solely support slashes
695           '/' as file separators, given that backslashes '\' have a special
696           meaning in regex/glob patterns.
697
698       All the available file selection conditions are listed under SELECTION
699       OPTIONS.
700
701       Two principles need to be understood before really starting:
702
703        1. pattern matching is stupid about paths, it just does pattern
704           matching and can’t interpret patterns like path, especially it
705           can’t resolve absolute into relative paths and vice-versa (compare
706           with the '-path' option of find).
707
708        2. pattern matching is done on the complete path of each found file
709           (no partial matching and no file name matching). Beware that
710           complete path does not mean full path, it can be a complete
711           relative path.
712
713       For example, the pattern 'bar' matches the path 'bar', but doesn’t
714       match the path 'foo/bar' and neither the path './bar'. Both are matched
715       by the pattern '*/bar', as well as by '**/bar'. This last pattern would
716       match any path containing the file 'bar', e.g. 'foo/boz/bar'.
717
718       Each file selection condition either matches or doesn’t match a given
719       file. A given file is excluded by the file selection system exactly
720       when the first matching file selection condition specifies that the
721       file be excluded; otherwise the file is included. When backing up, if a
722       file is excluded, rdiff-backup acts as if that file does not exist in
723       the source directory. When restoring, an excluded file is considered
724       not to exist in either the source or target directories.
725
726       For instance,
727
728           rdiff-backup backup --include /usr \
729                               --exclude /usr /usr /backup
730
731       is exactly the same as
732
733           rdiff-backup backup /usr /backup
734
735       because the include and exclude directives match exactly the same
736       files, and the --include comes first, giving it precedence. Similarly,
737
738           rdiff-backup backup --include /usr/local/bin \
739                               --exclude /usr/local /usr /backup
740
741       would backup the '/usr/local/bin' directory (and its contents), but not
742       '/usr/local/doc'.
743
744       The include, exclude, include-globbing-filelist, and
745       exclude-globbing-filelist options accept extended shell globbing
746       patterns. These patterns can contain the special patterns '*', '**',
747       '?', and '[...]'. As in a normal shell, '*' can be expanded to any
748       string of characters not containing '/', '?' expands to any character
749       except '/', and '[...]' expands to a single character of those
750       characters specified (ranges are acceptable). The new special pattern,
751       '**', expands to any string of characters whether or not it contains
752       '/'. Furthermore, if the pattern starts with 'ignorecase:' (case
753       insensitive), then this prefix will be removed and any character in the
754       string can be replaced with an upper or lowercase version of itself.
755
756       If you need to match filenames which contain the above globbing
757       characters, they may be escaped using a backslash '\'. The backslash
758       will only escape the character following it so for '**' you will need
759       to use '\*\*' to avoid escaping it to the '*' globbing character.
760
761       Remember that you may need to quote these characters when typing them
762       into a shell, so the shell does not interpret the globbing patterns
763       before rdiff-backup sees them.
764
765       The --exclude pattern option matches a file if and only if:
766
767        1. pattern can be expanded into the file’s filename, or
768
769        2. the file is inside a directory matched by the option.
770
771       Conversely, --include pattern matches a file if and only if:
772
773        1. pattern can be expanded into the file’s filename,
774
775        2. the file is inside a directory matched by the option, or
776
777        3. the file is a directory which contains a file matched by  the
778           option.
779
780       For example,
781
782           --exclude /usr/local
783
784       matches '/usr/local', '/usr/local/lib', and '/usr/local/lib/netscape'.
785       It is the same as
786
787           --exclude /usr/local --exclude '/usr/local/**'
788
789       And similarly:
790
791           --include /usr/local
792
793       specifies that '/usr', '/usr/local', '/usr/local/lib', and
794       '/usr/local/lib/netscape' (but not '/usr/doc') all be backed up. Thus
795       you don’t have to worry about including parent directories to make sure
796       that included subdirectories have somewhere to go. Finally,
797
798           --include ignorecase:'/usr/[a-z0-9]foo/*/**.py'
799
800       would match a file like '/usr/5fOO/hello/there/world.py'. If it did
801       match anything, it would also match '/usr'. If there is no existing
802       file that the given pattern can be expanded into, the option will not
803       match '/usr'.
804
805       The --include-filelist, --exclude-filelist, --include-filelist-stdin,
806       and --exclude-filelist-stdin options also introduce file selection
807       conditions. They direct rdiff-backup to read in a file, each line of
808       which is a file specification, and to include or exclude the matching
809       files. Lines are separated by newlines or nulls, depending on whether
810       the --null-separator switch was given. Each line in a filelist is
811       interpreted similarly to the way extended shell patterns are, with a
812       few exceptions:
813
814        1. Globbing patterns like '*', '**', '?', and '[...]' are not
815           expanded.
816
817        2. Include patterns do not match files in a directory that is
818           included. So '/usr/local' in an include file will not match
819           '/usr/local/doc'.
820
821        3. Lines starting with '+ [...]' (plus followed by a space) are
822           interpreted as include directives, even if found in a filelist
823           referenced by --exclude-filelist. Similarly, lines starting with '-
824           [...]' (minus followed by a space) exclude files even if they are
825           found within an include filelist.
826
827       For example, if the file 'list.txt' contains the lines:
828
829           /usr/local
830           - /usr/local/doc
831           /usr/local/bin
832           + /var
833           - /var
834
835       then '--include-filelist list.txt' would include '/usr', '/usr/local',
836       and '/usr/local/bin'. It would exclude '/usr/local/doc',
837       '/usr/local/doc/python', etc. It neither excludes nor includes
838       '/usr/local/man', leaving the fate of this directory to the next
839       specification condition. Finally, it is undefined what happens with
840       '/var'. A single file list should not contain conflicting file
841       specifications.
842
843       The --include-globbing-filelist and --exclude-globbing-filelist options
844       also specify filelists, but each line in the filelist will be
845       interpreted as a globbing pattern the way --include and --exclude
846       options are interpreted (although '+ ' and '- ' prefixing is still
847       allowed). For instance, if the file 'globbing-list.txt' contains the
848       lines:
849
850           dir/foo
851
852       Then '--include-globbing-filelist globbing-list.txt' would be exactly
853       the same as specifying on the command line:
854
855           --include dir/foo --include dir/bar --exclude **
856
857       Finally, the --include-regexp and --exclude-regexp allow files to be
858       included and excluded if their filenames match a python regular
859       expression. Regular expression syntax is too complicated to explain
860       here, but is covered in Python’s library reference. Unlike the
861       --include and --exclude options, the regular expression options don’t
862       match files containing or contained in matched files. So for instance
863
864           --include '[0-9]{7}(?!foo)'
865
866       matches any files whose full pathnames contain 7 consecutive digits
867       which aren’t followed by 'foo'. However, it wouldn’t match '/home' even
868       if '/home/ben/1234567' existed.
869

USERS AND GROUPS

871       There can be complications preserving ownership across systems. For
872       instance the username that owns a file on the source system may not
873       exist on the destination. Here is how rdiff-backup maps ownership on
874       the source to the destination (or vice-versa, in the case of
875       restoring):
876
877        1. If the --preserve-numerical-ids option is given, the remote files
878           will always have the same uid and gid, both for ownership and ACL
879           entries. This may cause unames and gnames to change.
880
881        2. Otherwise, attempt to preserve the user and group names for
882           ownership and in ACLs. This may result in files having different
883           uids and gids across systems.
884
885        3. If a name cannot be preserved (e.g. because the username does not
886           exist), preserve the original id, but only in cases of user and
887           group ownership. For ACLs, omit any entry that has a bad user or
888           group name.
889
890        4. The --user-mapping-file and --group-mapping-file options override
891           this behavior. If either of these options is given, the policy
892           described in 2 and 3 above will be followed, but with the mapped
893           user and group instead of the original. If you specify both
894           --preserve-numerical-ids and one of the mapping options, the
895           behavior is undefined.
896
897       The user and group mapping files both have the same format:
898
899           old_name_or_id1:new_name_or_id1
900           old_name_or_id2:new_name_or_id2
901           [...etc...]
902
903       Each line should contain a name or id, followed by a colon ':',
904       followed by another name or id. If a name or id is not listed, they are
905       treated in the default way described above.
906
907       When restoring, the above behavior is also followed, but note that the
908       original source user/group information will be the input, not the
909       already mapped user/group information present in the backup repository.
910       For instance, suppose you have mapped all the files owned by alice in
911       the source so that they are owned by ben in the repository, and now you
912       want to restore, making sure the files owned originally by alice are
913       still owned by alice. In this case there is no need to use any of the
914       mapping options. However, if you wanted to restore the files so that
915       the files originally owned by alice on the source are now owned by ben,
916       you would have to use the mapping options, even though you just want
917       the unames of the repository’s files preserved in the restored files.
918
919       See USER GROUP OPTIONS for a list and description of related options.
920

FILES

922       any-config-file
923           you can create a file with one option/action/sub-option per line
924           and use it on the command line with an at sign prefix like
925           @any-config-file and its content will be interpreted as if given on
926           the command line.
927
928           For example, creating a file 'mybackup' with following content:
929
930               --verbosity
931               5
932               backup
933               source_dir
934               target_dir
935
936           and calling 'rdiff-backup @mybackup' will be the same as calling
937           'rdiff-backup --verbosity 5 backup source_dir target_dir'.
938
939       session_statistics, file_statistics
940           Every session rdiff-backup saves various statistics into two files,
941           the session statistics file at
942           'rdiff-backup-data/session_statistics.{datetime}.data' and the
943           files statistics at
944           'rdiff-backup-data/directory_statistics.{datetime}.data'. They are
945           both text files and contain similar information: how many files
946           changed, how many were deleted, the total size of increment files
947           created, etc. However, the session statistics file is intended to
948           be very readable and only describes the session as a whole. The
949           files statistics file is more compact (and slightly less readable)
950           but describes every directory backed up. It also may be compressed
951           to save space.
952
953           See also STATISTICS OPTIONS and the --null-separator option.
954
955       backup.log, restore.log, error_log
956           rdiff-backup will save various messages to the log file, which is
957           'rdiff-backup-data/backup.log' for backup sessions and
958           'rdiff-backup-data/restore.log' for restore sessions. Generally
959           what is written to this file will coincide with the messages
960           displayed to stdout or stderr, although this can be changed with
961           the --terminal-verbosity option.
962
963           Errors during backup are also written to a file
964           'rdiff-backup-data/error_log.{datetime}.data'.
965
966           The log files are not compressed and can become quite large if
967           rdiff-backup is run with high verbosity.
968

ENVIRONMENT

970       RDIFF_BACKUP_VERBOSITY=[0-9]
971           the default verbosity for log file and terminal, can be overwritten
972           by the corresponding options -v/--verbosity and
973           --terminal-verbosity.
974
975       RDIFF_BACKUP_DEBUG=[address][:port]
976           set a non-default listening address and/or port (default is
977           127.0.0.1:4444) for  rpdb. Valid values are address, address:port
978           or :port.
979

RETURN CODES

981       The following return codes have not been fully implemented so test
982       before you rely on them. Also note that they can be combined, so that
983       for example a return code 3 might be returned if a warning was found,
984       then an error.
985
986       0 - OK
987           the action was completely successful
988
989       1 - ERROR
990           something fatal happened, the whole action failed
991
992       2 - WARNING
993           any kind of unexpected behavior without complete failure
994
995       4 - FILE ERROR
996           the action failed on a single file (or more), but it wasn’t the
997           reason for a complete failure
998
999       8 - FILE WARNING
1000           the action stumbled on a single file (or more), or detected
1001           differences in a comparaison
1002
1003           Tip
1004           any other error code can and should be reported as a bug.
1005

BUGS

1007       See GitHub issues
1008           https://github.com/rdiff-backup/rdiff-backup/issues
1009
1010       In doubt subscribe to and ask the mailing list
1011           https://lists.nongnu.org/mailman/listinfo/rdiff-backup-users
1012

AUTHORS

1014       •   Ben Escoto ben@emerose.org (retired)
1015
1016       •   Eric Lavarde ewl+rdiffbackup@lavar.de (active)
1017

SEE ALSO

1019       python(1), rdiff(1), rsync(1), ssh(1).
1020
1021       The main rdiff-backup web page is at https://rdiff-backup.net/. It has
1022       more documentation, links to the mailing list and source code.
1023
1024
1025
1026rdiff-backup                     December 2022                 RDIFF-BACKUP(1)
Impressum