1RDIFF-BACKUP(1)                  User Manuals                  RDIFF-BACKUP(1)
2
3
4

NAME

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

SYNOPSIS

9       rdiff-backup      [options]      [[[user@]host1.foo]::source_directory]
10       [[[user@]host2.foo]::destination_directory]
11
12       rdiff-backup  {{  -l  |  --list-increments  }   |   --remove-older-than
13       time_interval  |  --list-at-time  time  |  --list-changed-since  time |
14       --list-increment-sizes   |   --verify    |    --verify-at-time    time}
15       [[[user@]host2.foo]::destination_directory]
16
17       rdiff-backup --calculate-average statfile1 statfile2 ...
18
19       rdiff-backup           --test-server           [user1]@host1.net1::path
20       [[user2]@host2.net2::path] ...
21
22

DESCRIPTION

24       rdiff-backup is a script, written in python(1) that backs up one direc‐
25       tory  to  another.  The target directory ends up a copy (mirror) of the
26       source directory, but extra reverse diffs are stored in a special  sub‐
27       directory of that target directory, so you can still recover files lost
28       some time ago.  The idea is to combine the best features  of  a  mirror
29       and  an incremental backup.  rdiff-backup also preserves symlinks, spe‐
30       cial files, hardlinks, permissions, uid/gid ownership, and modification
31       times.
32
33       rdiff-backup  can  also  operate in a bandwidth efficient manner over a
34       pipe, like rsync(1).  Thus you can use ssh and rdiff-backup to securely
35       back  a  hard  drive  up to a remote location, and only the differences
36       will be transmitted.  Using the default settings, rdiff-backup requires
37       that the remote system accept ssh connections, and that rdiff-backup is
38       installed in the user's PATH on the remote system.  For information  on
39       other options, see the section on REMOTE OPERATION.
40
41       Note  that  you  should  not  write to the mirror directory except with
42       rdiff-backup.  Many of the increments are stored as reverse  diffs,  so
43       if  you  delete  or  modify a file, you may lose the ability to restore
44       previous versions of that file.
45
46       Finally, this man page is intended more as a precise description of the
47       behavior  and  syntax of rdiff-backup.  New users may want to check out
48       the examples.html file included in the rdiff-backup distribution.
49
50

OPTIONS

52       -b, --backup-mode
53              Force backup mode even if first argument appears to be an incre‐
54              ment or mirror file.
55
56       --calculate-average
57              Enter  calculate average mode.  The arguments should be a number
58              of statistics files.  rdiff-backup will print the average of the
59              listed statistics files and exit.
60
61       --carbonfile
62              Enable backup of MacOS X carbonfile information.
63
64       --check-destination-dir
65              If an rdiff-backup session fails, running rdiff-backup with this
66              option on the destination dir will undo  the  failed  directory.
67              This happens automatically if you attempt to back up to a direc‐
68              tory and the last backup failed.
69
70       --compare
71              This is equivalent to '--compare-at-time now'
72
73       --compare-at-time time
74              Compare a directory with the backup set at the given time.  This
75              can  be  useful  to  see  how archived data differs from current
76              data, or to check that a backup is current.  This only  compares
77              metadata,  in  the  same way rdiff-backup decides whether a file
78              has changed.
79
80       --compare-full
81              This is equivalent to '--compare-full-at-time now'
82
83       --compare-full-at-time time
84              Compare a directory with the backup set at the given  time.   To
85              compare regular files, the repository data will be copied in its
86              entirety to the source side and compared byte by byte.  This  is
87              the slowest but most complete compare option.
88
89       --compare-hash
90              This is equivalent to '--compare-hash-at-time now'
91
92       --compare-hash-at-time time
93              Compare a directory with the backup set at the given time.  Reg‐
94              ular files will be compared by computing their  SHA1  digest  on
95              the  source  side and comparing it to the digest recorded in the
96              metadata.
97
98       --create-full-path
99              Normally only the final directory of the destination  path  will
100              be  created  if it does not exist. With this option, all missing
101              directories on the destination path will be  created.  Use  this
102              option  with  care:  if  there is a typo in the remote path, the
103              remote filesystem could fill up  very  quickly  (by  creating  a
104              duplicate backup tree). For this reason this option is primarily
105              aimed at scripts which automate backups.
106
107       --current-time seconds
108              This option is useful mainly for testing.  If set,  rdiff-backup
109              will  use  it  for  the  current  time instead of consulting the
110              clock.  The argument is the number of seconds since the epoch.
111
112       --exclude shell_pattern
113              Exclude the file or files matched by shell_pattern.  If a direc‐
114              tory  is  matched,  then files under that directory will also be
115              matched.  See the FILE SELECTION section for more information.
116
117       --exclude-device-files
118              Exclude all device files.  This can be useful for  security/per‐
119              missions reasons or if rdiff-backup is not handling device files
120              correctly.
121
122       --exclude-fifos
123              Exclude all fifo files.
124
125       --exclude-filelist filename
126              Excludes the files listed in filename.  If filename is handwrit‐
127              ten  you probably want --exclude-globbing-filelist instead.  See
128              the FILE SELECTION section for more information.
129
130       --exclude-filelist-stdin
131              Like --exclude-filelist, but the list of files will be read from
132              standard  input.  See the FILE SELECTION section for more infor‐
133              mation.
134
135       --exclude-globbing-filelist filename
136              Like --exclude-filelist but each line of the  filelist  will  be
137              interpreted  according  to  the  same  rules  as  --include  and
138              --exclude.
139
140       --exclude-globbing-filelist-stdin
141              Like --exclude-globbing-filelist, but the list of files will  be
142              read from standard input.
143
144       --exclude-other-filesystems
145              Exclude  files  on  file  systems  (identified by device number)
146              other than the file system the root of the source  directory  is
147              on.
148
149       --exclude-regexp regexp
150              Exclude  files  matching the given regexp.  Unlike the --exclude
151              option, this option does not  match  files  in  a  directory  it
152              matches.  See the FILE SELECTION section for more information.
153
154       --exclude-special-files
155              Exclude all device files, fifo files, socket files, and symbolic
156              links.
157
158       --exclude-sockets
159              Exclude all socket files.
160
161       --exclude-symbolic-links
162              Exclude all symbolic links. This option is automatically enabled
163              if the backup source is running on native Windows to avoid back‐
164              ing-up NTFS reparse points.
165
166       --exclude-if-present filename
167              Exclude directories if filename is present. This option needs to
168              come before any other include or exclude options.
169
170       --force
171              Authorize  a more drastic modification of a directory than usual
172              (for instance, when overwriting of a destination path,  or  when
173              removing  multiple  sessions  with --remove-older-than).  rdiff-
174              backup will generally tell you if it needs this.   WARNING:  You
175              can cause data loss if you mis-use this option.  Furthermore, do
176              NOT use this option when doing a  restore,  as  it  will  DELETE
177              FILES, unless you absolutely know what you are doing.
178
179       --group-mapping-file filename
180              Map  group  names  and  ids according the the group mapping file
181              filename.  See the USERS AND GROUPS section  for  more  informa‐
182              tion.
183
184       --include shell_pattern
185              Similar  to --exclude but include matched files instead.  Unlike
186              --exclude, this option will also  match  parent  directories  of
187              matched  files  (although  not necessarily their contents).  See
188              the FILE SELECTION section for more information.
189
190       --include-filelist filename
191              Like --exclude-filelist, but include the listed  files  instead.
192              If filename is handwritten you probably want --include-globbing-
193              filelist instead.  See  the  FILE  SELECTION  section  for  more
194              information.
195
196       --include-filelist-stdin
197              Like  --include-filelist,  but  read  the list of included files
198              from standard input.
199
200       --include-globbing-filelist filename
201              Like --include-filelist but each line of the  filelist  will  be
202              interpreted  according  to  the  same  rules  as  --include  and
203              --exclude.
204
205       --include-globbing-filelist-stdin
206              Like --include-globbing-filelist, but the list of files will  be
207              read from standard input.
208
209       --include-regexp regexp
210              Include  files  matching  the  regular  expression regexp.  Only
211              files explicitly matched by regexp  will  be  included  by  this
212              option.  See the FILE SELECTION section for more information.
213
214       --include-special-files
215              Include all device files, fifo files, socket files, and symbolic
216              links.
217
218       --include-symbolic-links
219              Include all symbolic links.
220
221       --list-at-time time
222              List the files in the archive that were  present  at  the  given
223              time.  If a directory in the archive is specified, list only the
224              files under that directory.
225
226       --list-changed-since time
227              List the files that have changed in  the  destination  directory
228              since  the given time.  See TIME FORMATS for the format of time.
229              If a directory in the archive is specified, list only the  files
230              under  that  directory.   This  option  does not read the source
231              directory; it is used to compare the contents of  two  different
232              rdiff-backup sessions.
233
234       -l, --list-increments
235              List  the  number  and  date of partial incremental backups con‐
236              tained in the specified destination  directory.   No  backup  or
237              restore will take place if this option is given.
238
239       --list-increment-sizes
240              List  the  total  size  of all the increment and mirror files by
241              time.  This may be helpful in deciding how  many  increments  to
242              keep,  and  when to --remove-older-than.  Specifying a subdirec‐
243              tory is allowable; then only the sizes of the mirror and  incre‐
244              ments pertaining to that subdirectory will be listed.
245
246       --max-file-size size
247              Exclude files that are larger than the given size in bytes
248
249       --min-file-size size
250              Exclude files that are smaller than the given size in bytes
251
252       --never-drop-acls
253              Exit  with  error instead of dropping acls or acl entries.  Nor‐
254              mally this may happen (with a warning) because  the  destination
255              does  not  support them or because the relevant user/group names
256              do not exist on the destination side.
257
258       --no-acls
259              No Access Control Lists - disable backup of ACLs
260
261       --no-carbonfile
262              Disable backup of MacOS X carbonfile information
263
264       --no-compare-inode
265              This option prevents rdiff-backup  from  flagging  a  hardlinked
266              file  as  changed  when  its device number and/or inode changes.
267              This option is useful in situations where the source  filesystem
268              lacks  persistent  device  and/or inode numbering.  For example,
269              network filesystems may have mount-to-mount differences in their
270              device  number  (but  possibly  stable  inode numbers); USB/1394
271              devices may come up at different  device  numbers  each  remount
272              (but  would  generally  have  same  inode number); and there are
273              filesystems which don't even have the same  inode  numbers  from
274              use to use.  Without the option rdiff-backup may generate unnec‐
275              essary numbers of tiny diff files.
276
277       --no-compression
278              Disable the default gzip compression of most  of  the  .snapshot
279              and .diff increment files stored in the rdiff-backup-data direc‐
280              tory.  A backup volume can contain compressed  and  uncompressed
281              increments, so using this option inconsistently is fine.
282
283       --no-compression-regexp  regexp
284              Do  not compress increments based on files whose filenames match
285              regexp.  The default includes many common  audiovisual  and  ar‐
286              chive files, and may be found in Globals.py.
287
288       --no-eas
289              No Extended Attributes support - disable backup of EAs.
290
291       --no-file-statistics
292              This  will  disable  writing  to the file_statistics file in the
293              rdiff-backup-data directory.   rdiff-backup  will  run  slightly
294              quicker and take up a bit less space.
295
296       --no-fsync
297              This  will  disable  issuing fsync from rdiff-backup altogether.
298              This option is designed to optimize performance on  busy  backup
299              systems.  Use with caution. This may render your backup unusable
300              in case of filesystem failure.
301
302       --no-hard-links
303              Don't replicate hard links on destination side.  If  many  hard-
304              linked  files  are present, this option can drastically decrease
305              memory usage.  This option is enabled by default if  the  backup
306              source or restore destination is running on native Windows.
307
308       --null-separator
309              Use  nulls  (\0)  instead  of  newlines (\n) as line separators,
310              which may help when dealing with filenames containing  newlines.
311              This  affects  the expected format of the files specified by the
312              --{include|exclude}-filelist[-stdin] switches  as  well  as  the
313              format of the directory statistics file.
314
315       --parsable-output
316              If  set, rdiff-backup's output will be tailored for easy parsing
317              by computers, instead of convenience for humans.  Currently this
318              only  applies  when  listing  increments using the -l or --list-
319              increments switches, where the time will  be  given  in  seconds
320              since the epoch.
321
322       --override-chars-to-quote
323              If  the filesystem to which we are backing up is not case-sensi‐
324              tive, automatic 'quoting' of characters occurs. For  example,  a
325              file  'Developer.doc' will be converted into ';068eveloper.doc'.
326              To override this behavior, you need to specify this option.
327
328       --preserve-numerical-ids
329              If set, rdiff-backup will preserve uids/gids instead  of  trying
330              to preserve unames and gnames.  See the USERS AND GROUPS section
331              for more information.
332
333       --print-statistics
334              If set, summary statistics will be printed  after  a  successful
335              backup.   If  not  set, this information will still be available
336              from the session statistics file.  See  the  STATISTICS  section
337              for more information.
338
339       -r, --restore-as-of restore_time
340              Restore  the  specified  directory as it was as of restore_time.
341              See the TIME FORMATS section for more information on the  format
342              of restore_time, and see the RESTORING section for more informa‐
343              tion on restoring.
344
345       --remote-cmd cmd
346              Deprecated. Please use --remote-schema instead
347
348       --remote-schema schema
349              Specify an alternate method of connecting to a remote  computer.
350              This  is necessary to get rdiff-backup not to use ssh for remote
351              backups, or if, for instance, rdiff-backup is not in the PATH on
352              the  remote  side.   See  the  REMOTE OPERATION section for more
353              information.
354
355       --remote-tempdir path
356              Adds the --tempdir  option  with  argument  path  when  invoking
357              remote instances of rdiff-backup.
358
359       --remove-older-than time_spec
360              Remove  the  incremental  backup  information in the destination
361              directory that has been  around  longer  than  the  given  time.
362              time_spec  can be either an absolute time, like "2002-01-04", or
363              a time interval.  The time interval is an  integer  followed  by
364              the  character  s, m, h, D, W, M, or Y, indicating seconds, min‐
365              utes, hours, days, weeks, months, or years  respectively,  or  a
366              number  of  these  concatenated.  For example, 32m means 32 min‐
367              utes, and 3W2D10h7s means 3 weeks, 2 days, 10 hours, and 7  sec‐
368              onds.   In  this  context,  a month means 30 days, a year is 365
369              days, and a day is always 86400 seconds.
370
371              rdiff-backup cannot remove-older-than and back up or restore  in
372              a  single  session.   In  order  to  both backup a directory and
373              remove old files in it, you must run rdiff-backup twice.
374
375              By default, rdiff-backup will only delete information  from  one
376              session  at  a time.  To remove two or more sessions at the same
377              time, supply the --force option (rdiff-backup will tell  you  if
378              --force is required).
379
380              Note  that snapshots of deleted files are covered by this opera‐
381              tion.  Thus if you deleted a file two weeks ago, backed up imme‐
382              diately  afterwards,  and  then  ran rdiff-backup with --remove-
383              older-than 10D today,  no  trace  of  that  file  would  remain.
384              Finally,  file selection options such as --include and --exclude
385              don't affect --remove-older-than.
386
387       --restrict path
388              Require that all file access be inside  the  given  path.   This
389              switch,  and the following two, are intended to be used with the
390              --server switch to provide a  bit  more  protection  when  doing
391              automated  remote  backups.   They are not intended as your only
392              line of defense so please don't do something  silly  like  allow
393              public  access  to  an  rdiff-backup server run with --restrict-
394              read-only.
395
396       --restrict-read-only path
397              Like --restrict, but also reject all write requests.
398
399       --restrict-update-only path
400              Like --restrict, but only allow writes as part of an incremental
401              backup.   Requests  for  other  types  of  writes (for instance,
402              deleting path) will be rejected.
403
404       --server
405              Enter server mode (not to be invoked directly, but instead  used
406              by another rdiff-backup process on a remote computer).
407
408       --ssh-no-compression
409              When  running  ssh,  do not use the -C option to enable compres‐
410              sion.  --ssh-no-compression is ignored  if  you  specify  a  new
411              schema using --remote-schema.
412
413       --tempdir path
414              Sets the directory that rdiff-backup uses for temporary files to
415              the given path. The environment variables TMPDIR, TEMP, and  TMP
416              can  also  be used to set the temporary files directory. See the
417              documentation of the Python tempfile module  for  more  informa‐
418              tion.
419
420       --terminal-verbosity [0-9]
421              Select  which  messages  will  be displayed to the terminal.  If
422              missing the level defaults to the verbosity level.
423
424       --test-server
425              Test for the presence of a  compatible  rdiff-backup  server  as
426              specified  in  the  following  host::filename  argument(s).  The
427              filename section will be ignored.
428
429       --use-compatible-timestamps
430              Create timestamps in which the hour/minute/second separator is a
431              - (hyphen) instead of a : (colon). It is safe to use this option
432              on one backup, and then not use it on another; rdiff-backup sup‐
433              ports  the  intermingling  of  different timestamp formats. This
434              option is enabled by default on platforms which require that the
435              colon be escaped.
436
437       --user-mapping-file filename
438              Map  user names and ids according to the user mapping file file‐
439              name.  See the USERS AND GROUPS section for more information.
440
441       -v[0-9], --verbosity [0-9]
442              Specify verbosity level (0 is totally silent, 3 is the  default,
443              and  9 is noisiest).  This determines how much is written to the
444              log file.
445
446       --verify
447              This is short for --verify-at-time now
448
449       --verify-at-time now
450              Check all the data in the repository at the given time  by  com‐
451              puting the SHA1 hash of all the regular files and comparing them
452              with the hashes stored in the metadata file.
453
454       -V, --version
455              Print the current version and exit
456
457

ENVIRONMENT

459       RDIFF_BACKUP_VERBOSITY=[0-9]
460              Sets the default verbosity for log file  and  terminal,  can  be
461              overwritten  by  the  corresponding options "-v/--verbosity" and
462              "--terminal-verbosity".
463
464

RESTORING

466       There are two ways to tell rdiff-backup to restore a file or directory.
467       Firstly,  you  can  run rdiff-backup on a mirror file and use the -r or
468       --restore-as-of options.  Secondly, you can  run  it  on  an  increment
469       file.
470
471       For example, suppose in the past you have run:
472
473              rdiff-backup /usr /usr.backup
474
475       to  back  up the /usr directory into the /usr.backup directory, and now
476       want a copy of the /usr/local directory the  way  it  was  3  days  ago
477       placed at /usr/local.old.
478
479       One way to do this is to run:
480
481              rdiff-backup -r 3D /usr.backup/local /usr/local.old
482
483       where  above the "3D" means 3 days (for other ways to specify the time,
484       see the TIME FORMATS section).   The  /usr.backup/local  directory  was
485       selected,  because that is the directory containing the current version
486       of /usr/local.
487
488       Note that the option to --restore-as-of always specifies an exact time.
489       (So  "3D" refers to the instant 72 hours before the present.)  If there
490       was no backup made  at  that  time,  rdiff-backup  restores  the  state
491       recorded  for the previous backup.  For instance, in the above case, if
492       "3D" is used, and there are only backups from 2 days and  4  days  ago,
493       /usr/local as it was 4 days ago will be restored.
494
495       The  second  way  to  restore  files involves finding the corresponding
496       increment file.  It would be  in  the  /backup/rdiff-backup-data/incre‐
497       ments/usr   directory,   and   its   name   would   be  something  like
498       "local.2002-11-09T12:43:53-04:00.dir" where the time  indicates  it  is
499       from  3  days  ago.   Note that the increment files all end in ".diff",
500       ".snapshot", ".dir", or ".missing", where ".missing"  just  means  that
501       the file didn't exist at that time (finally, some of these may be gzip-
502       compressed, and have an extra ".gz" to indicate this).  Then running:
503
504              rdiff-backup                    /backup/rdiff-backup-data/incre‐
505              ments/usr/local.<time>.dir /usr/local.old
506
507       would also restore the file as desired.
508
509       If  you  are  not  sure exactly which version of a file you need, it is
510       probably easiest  to  either  restore  from  the  increments  files  as
511       described  immediately  above, or to see which increments are available
512       with  -l/--list-increments,  and  then   specify   exact   times   into
513       -r/--restore-as-of.
514
515

TIME FORMATS

517       rdiff-backup  uses  time  strings  in  two places.  Firstly, all of the
518       increment files rdiff-backup creates will have the time in their  file‐
519       names  in  the  w3  datetime  format  as  described  in  a  w3  note at
520       https://www.w3.org/TR/NOTE-datetime.    Basically   they   look    like
521       "2001-07-15T04:09:38-07:00",  which  means  what  it  looks  like.  The
522       "-07:00" section means the time zone is 7 hours behind UTC.
523
524       Secondly, the -r, --restore-as-of, and --remove-older-than options take
525       a time string, which can be given in any of several formats:
526
527       1.     the string "now" (refers to the current time)
528
529       2.     a  sequences of digits, like "123456890" (indicating the time in
530              seconds after the epoch)
531
532       3.     A string like "2002-01-25T07:00:00+02:00" in datetime format
533
534       4.     An interval, which is a number followed by one of the characters
535              s,  m,  h,  D,  W,  M, or Y (indicating seconds, minutes, hours,
536              days, weeks, months, or years respectively), or a series of such
537              pairs.  In this case the string refers to the time that preceded
538              the current time by the length of the interval.   For  instance,
539              "1h78m" indicates the time that was one hour and 78 minutes ago.
540              The calendar here is unsophisticated: a month is always 30 days,
541              a year is always 365 days, and a day is always 86400 seconds.
542
543       5.     A date format of the form YYYY/MM/DD, YYYY-MM-DD, MM/DD/YYYY, or
544              MM-DD-YYYY, which indicates midnight on  the  day  in  question,
545              relative  to  the  current  timezone  settings.   For  instance,
546              "2002/3/5", "03-05-2002", and "2002-3-05" all  mean  March  5th,
547              2002.
548
549       6.     A  backup  session specification which is a non-negative integer
550              followed by 'B'.  For instance, '0B' specifies the time  of  the
551              current  mirror,  and  '3B' specifies the time of the 3rd newest
552              increment.
553
554

REMOTE OPERATION

556       In order to access remote files, rdiff-backup opens up a pipe to a copy
557       of  rdiff-backup running on the remote machine.  Thus rdiff-backup must
558       be installed on both ends.   To  open  this  pipe,  rdiff-backup  first
559       splits  the  filename  into  host_info::pathname.   It then substitutes
560       host_info into the remote schema, and runs the resulting command, read‐
561       ing its input and output.
562
563       The  default  remote  schema is 'ssh -C %s rdiff-backup --server' where
564       host_info  is  substituted  for  '%s'.   So   if   the   host_info   is
565       user@host.net,  then  rdiff-backup runs 'ssh user@host.net rdiff-backup
566       --server'.  Using --remote-schema, rdiff-backup can invoke an arbitrary
567       command in order to open up a remote pipe.  For instance,
568              rdiff-backup  --remote-schema  'cd  /usr;  %s' foo 'rdiff-backup
569              --server'::bar
570       is basically equivalent to (but slower than)
571              rdiff-backup foo /usr/bar
572
573       Concerning quoting, if for some reason you need to put two  consecutive
574       colons  in  the host_info section of a host_info::pathname argument, or
575       in the pathname of a local file, you can quote one of them by  prepend‐
576       ing  a  backslash.  So in 'a\::b::c', host_info is 'a::b' and the path‐
577       name is 'c'.  Similarly, if you want to refer to  a  local  file  whose
578       filename  contains two consecutive colons, like 'strange::file', you'll
579       have to quote one of the colons as in  'strange\::file'.   Because  the
580       backslash  is  a quote character in these circumstances, it too must be
581       quoted to get  a  literal  backslash,  so  'foo\::\\bar'  evaluates  to
582       'foo::\bar'.  To make things more complicated, because the backslash is
583       also a common shell quoting character, you may need to type  in  '\\\\'
584       at  the  shell  prompt to get a literal backslash (if it makes you feel
585       better, I had to type  in  8  backslashes  to  get  that  in  this  man
586       page...).   And finally, to include a literal % in the string specified
587       by --remote-schema, quote it with another %, as in %%.
588
589       Although ssh itself may be secure, using rdiff-backup  in  the  default
590       way presents some security risks.  For instance if the server is run as
591       root, then an attacker who compromised the client could then use rdiff-
592       backup  to  overwrite arbitrary server files by "backing up" over them.
593       Such a setup can be made more secure by using  the  sshd  configuration
594       option   command="rdiff-backup   --server"   possibly  along  with  the
595       --restrict* options to rdiff-backup.  For more information, see the web
596       page, the wiki, and the entries for the --restrict* options on this man
597       page.
598
599

FILE SELECTION

601       rdiff-backup has a number of file selection options.  When rdiff-backup
602       is run, it searches through the given source directory and backs up all
603       the files matching the specified options.  This  selection  system  may
604       appear  complicated, but it is supposed to be flexible and easy-to-use.
605       If you just want to learn the basics, first look at the selection exam‐
606       ples  in  the examples.html file included in the package, or on the web
607       at https://www.nongnu.org/rdiff-backup/examples.html
608
609       rdiff-backup's selection system was originally  inspired  by  rsync(1),
610       but  there  are  many differences.  (For instance, trailing backslashes
611       have no special significance.)
612
613       The file selection system comprises a number of file  selection  condi‐
614       tions,  which  are set using one of the following command line options:
615       --exclude, --exclude-filelist, --exclude-device-files, --exclude-fifos,
616       --exclude-sockets,     --exclude-symbolic-links,    --exclude-globbing-
617       filelist, --exclude-globbing-filelist-stdin,  --exclude-filelist-stdin,
618       --exclude-regexp,    --exclude-special-files,   --include,   --include-
619       filelist,   --include-globbing-filelist,   --include-globbing-filelist-
620       stdin,   --include-filelist-stdin,  and  --include-regexp.   Each  file
621       selection condition either matches or doesn't match a  given  file.   A
622       given  file  is  excluded by the file selection system exactly when the
623       first matching file selection condition  specifies  that  the  file  be
624       excluded;  otherwise  the file is included.  When backing up, if a file
625       is excluded, rdiff-backup acts as if that file does not  exist  in  the
626       source  directory.   When restoring, an excluded file is considered not
627       to exist in either the source or target directories.
628
629       For instance,
630
631              rdiff-backup --include /usr --exclude /usr /usr /backup
632
633       is exactly the same as
634
635              rdiff-backup /usr /backup
636
637       because the include and  exclude  directives  match  exactly  the  same
638       files, and the --include comes first, giving it precedence.  Similarly,
639
640              rdiff-backup  --include /usr/local/bin --exclude /usr/local /usr
641              /backup
642
643       would backup the /usr/local/bin directory (and its contents),  but  not
644       /usr/local/doc.
645
646       The  include, exclude, include-globbing-filelist, and exclude-globbing-
647       filelist options accept extended shell globbing patterns.   These  pat‐
648       terns  can  contain  the special patterns *, **, ?, and [...].  As in a
649       normal shell, * can be expanded to any string of  characters  not  con‐
650       taining "/", ?  expands to any character except "/", and [...]  expands
651       to a single character of those characters specified (ranges are accept‐
652       able).   The  new special pattern, **, expands to any string of charac‐
653       ters whether or not it  contains  "/".   Furthermore,  if  the  pattern
654       starts  with "ignorecase:" (case insensitive), then this prefix will be
655       removed and any character in the string can be replaced with an  upper-
656       or lowercase version of itself.
657
658       If you need to match filenames which contain the above globbing charac‐
659       ters, they may be escaped using a backslash  "\".  The  backslash  will
660       only  escape  the character following it so for ** you will need to use
661       "\*\*" to avoid escaping it to the * globbing character.
662
663       Remember that you may need to quote these characters when  typing  them
664       into  a  shell,  so  the shell does not interpret the globbing patterns
665       before rdiff-backup sees them.
666
667       The --exclude pattern option matches a file iff:
668
669       1.     pattern can be expanded into the file's filename, or
670
671       2.     the file is inside a directory matched by the option.
672
673       Conversely, --include pattern matches a file iff:
674
675       1.     pattern can be expanded into the file's filename,
676
677       2.     the file is inside a directory matched by the option, or
678
679       3.     the file is a directory which contains a  file  matched  by  the
680              option.
681
682       For example,
683
684              --exclude /usr/local
685
686       matches /usr/local, /usr/local/lib, and /usr/local/lib/netscape.  It is
687       the same as --exclude /usr/local --exclude '/usr/local/**'.
688
689              --include /usr/local
690
691       specifies    that     /usr,     /usr/local,     /usr/local/lib,     and
692       /usr/local/lib/netscape  (but not /usr/doc) all be backed up.  Thus you
693       don't have to worry about including parent  directories  to  make  sure
694       that included subdirectories have somewhere to go.  Finally,
695
696              --include ignorecase:'/usr/[a-z0-9]foo/*/**.py'
697
698       would  match  a  file  like  /usR/5fOO/hello/there/world.py.  If it did
699       match anything, it would also match /usr.  If there is no existing file
700       that  the given pattern can be expanded into, the option will not match
701       /usr.
702
703       The --include-filelist,  --exclude-filelist,  --include-filelist-stdin,
704       and --exclude-filelist-stdin options also introduce file selection con‐
705       ditions.  They direct rdiff-backup to read in  a  file,  each  line  of
706       which  is  a file specification, and to include or exclude the matching
707       files.  Lines are separated by newlines or nulls, depending on  whether
708       the  --null-separator  switch  was  given.   Each line in a filelist is
709       interpreted similarly to the way extended shell patterns  are,  with  a
710       few exceptions:
711
712       1.     Globbing patterns like *, **, ?, and [...]  are not expanded.
713
714       2.     Include  patterns  do  not  match  files  in a directory that is
715              included.  So /usr/local in  an  include  file  will  not  match
716              /usr/local/doc.
717
718       3.     Lines  starting with "+ " are interpreted as include directives,
719              even if found in a filelist  referenced  by  --exclude-filelist.
720              Similarly,  lines  starting with "- " exclude files even if they
721              are found within an include filelist.
722
723       For example, if the file "list.txt" contains the lines:
724
725              /usr/local
726              - /usr/local/doc
727              /usr/local/bin
728              + /var
729              - /var
730
731       then "--include-filelist list.txt" would include /usr, /usr/local,  and
732       /usr/local/bin.        It       would      exclude      /usr/local/doc,
733       /usr/local/doc/python,  etc.   It   neither   excludes   nor   includes
734       /usr/local/man, leaving the fate of this directory to the next specifi‐
735       cation condition.  Finally, it is undefined what happens with /var.   A
736       single file list should not contain conflicting file specifications.
737
738       The --include-globbing-filelist and --exclude-globbing-filelist options
739       also specify filelists, but each line in the filelist  will  be  inter‐
740       preted  as  a  globbing pattern the way --include and --exclude options
741       are interpreted (although "+ " and "- " prefixing  is  still  allowed).
742       For instance, if the file "globbing-list.txt" contains the lines:
743
744              dir/foo
745              + dir/bar
746              - **
747
748       Then  "--include-globbing-filelist  globbing-list.txt" would be exactly
749       the same as specifying "--include dir/foo --include  dir/bar  --exclude
750       **" on the command line.
751
752       Finally,  the  --include-regexp  and --exclude-regexp allow files to be
753       included and excluded if their filenames match a python regular expres‐
754       sion.   Regular  expression  syntax is too complicated to explain here,
755       but is covered in Python's library reference.  Unlike the --include and
756       --exclude  options,  the  regular  expression options don't match files
757       containing or contained in matched files.  So for instance
758
759              --include '[0-9]{7}(?!foo)'
760
761       matches any files whose full pathnames  contain  7  consecutive  digits
762       which  aren't followed by 'foo'.  However, it wouldn't match /home even
763       if /home/ben/1234567 existed.
764
765

USERS AND GROUPS

767       There can be complications preserving ownership  across  systems.   For
768       instance  the  username  that  owns a file on the source system may not
769       exist on the destination.  Here is how rdiff-backup maps  ownership  on
770       the  source  to  the destination (or vice-versa, in the case of restor‐
771       ing):
772
773
774       1.     If the --preserve-numerical-ids  option  is  given,  the  remote
775              files  will always have the same uid and gid, both for ownership
776              and ACL entries.  This may cause unames and gnames to change.
777
778       2.     Otherwise, attempt to preserve the user and group names for own‐
779              ership  and  in ACLs.  This may result in files having different
780              uids and gids across systems.
781
782       3.     If a name cannot be preserved (e.g. because  the  username  does
783              not  exist), preserve the original id, but only in cases of user
784              and group ownership.  For ACLs, omit any entry that  has  a  bad
785              user or group name.
786
787       4.     The  --user-mapping-file  and --group-mapping-file options over‐
788              ride this behavior.  If either of these options  is  given,  the
789              policy described in 2 and 3 above will be followed, but with the
790              mapped user and group instead of the original.  If  you  specify
791              both  --preserve-numerical-ids  and  one of the mapping options,
792              the behavior is undefined.
793
794       The user and group mapping files both have the same form:
795
796              old_name_or_id1:new_name_or_id1
797              old_name_or_id2:new_name_or_id2
798              <etc>
799
800       Each line should contain a name or id, followed by a  colon  ":",  fol‐
801       lowed  by  another name or id.  If a name or id is not listed, they are
802       treated in the default way described above.
803
804       When restoring, the above behavior is also followed, but note that  the
805       original  source  user/group  information  will  be  the input, not the
806       already mapped user/group information present in the backup repository.
807       For  instance,  suppose you have mapped all the files owned by alice in
808       the source so that they are owned by ben in the repository, and now you
809       want  to  restore,  making sure the files owned originally by alice are
810       still owned by alice.  In this case there is no need to use any of  the
811       mapping  options.   However, if you wanted to restore the files so that
812       the files originally owned by alice on the source are now owned by ben,
813       you  would  have  to use the mapping options, even though you just want
814       the unames of the repository's files preserved in the restored files.
815
816
817

STATISTICS

819       Every session rdiff-backup saves various statistics into two files, the
820       session    statistics    file    at   rdiff-backup-data/session_statis‐
821       tics.<time>.data and the directory  statistics  file  at  rdiff-backup-
822       data/directory_statistics.<time>.data.   They  are  both text files and
823       contain similar information: how many  files  changed,  how  many  were
824       deleted,  the total size of increment files created, etc.  However, the
825       session statistics file is  intended  to  be  very  readable  and  only
826       describes  the  session  as  a whole.  The directory statistics file is
827       more compact (and slightly less readable) but describes every directory
828       backed up.  It also may be compressed to save space.
829
830       Statistics-related  options include --print-statistics and --null-sepa‐
831       rator.
832
833       Also, rdiff-backup will save various messages to the log file, which is
834       rdiff-backup-data/backup.log  for  backup  sessions  and  rdiff-backup-
835       data/restore.log for restore sessions.  Generally what  is  written  to
836       this  file  will  coincide  with  the  messages  displayed to stdout or
837       stderr, although this can  be  changed  with  the  --terminal-verbosity
838       option.
839
840       The  log  file  is  not compressed and can become quite large if rdiff-
841       backup is run with high verbosity.
842
843

EXIT STATUS

845       If rdiff-backup finishes successfully, the exit status will be  0.   If
846       there  is  an unrecoverable (critical) error, it will be non-zero (usu‐
847       ally 1, but don't depend on this  specific  value).   When  setting  up
848       rdiff-backup  to  run  automatically (as from cron(8) or similar) it is
849       probably a good idea to check the exit code.
850
851

BUGS

853       The gzip library in versions 2.2 and earlier of python  (but  fixed  in
854       2.3a1)  has  trouble producing files over 2GB in length.  This bug will
855       prevent rdiff-backup from producing large compressed increments  (snap‐
856       shots  or  diffs).   A  workaround  is to disable compression for large
857       incompressible files.
858
859

AUTHOR

861       Ben Escoto <ben@emerose.org>
862
863       Feel free to ask me questions or send me bug reports, but you may  want
864       to see the web page, mentioned below, first.
865
866

SEE ALSO

868       python(1),  rdiff(1), rsync(1), ssh(1).  The main rdiff-backup web page
869       is at https://rdiff-backup.net/.  It has more information, links to the
870       mailing list and CVS, etc.
871
872
873
874Version 2.0.0                     March 2020                   RDIFF-BACKUP(1)
Impressum