1DAR(1)                      General Commands Manual                     DAR(1)
2
3
4

NAME

6       dar  - creates, tests, lists, extracts, compares, merges, isolates, re‐
7       pairs dar archives
8

SYNOPSIS

10       dar [-c | -t | -l | -x | -d | -+ | -C | -y]  [[<URL>]<path>/]<basename>
11       [<options>] [<user targets>]
12
13       dar -h
14
15       dar -V
16

DESCRIPTION

18       dar  is  a  full featured backup tool, aimed for local and remote disks
19       (floppy, CD-R(W), DVD-R(W), zip,  jazz,  hard-disks,  usb  keys,  etc.)
20       cloud  storage  (by  mean of ftp or sftp protocols) and also adapted to
21       tapes.
22
23
24       dar can store a backup in several files (called "slices" in the follow‐
25       ing)  of  a  given  size,  eventually  pausing  or  running a user com‐
26       mand/script before starting the next slice. This can allow for example,
27       the  burning  of the last generated slice on a DVD-R(W), Blue-ray Disk,
28       or changing of usb key before continuing on the  next  one.   Like  its
29       grand-brother,  the  great "tar" command, dar may also use compression,
30       at the difference that compression is used inside  the  archive  to  be
31       able to have compressed slices of the defined size.
32
33       But  the most important feature of dar is its ability to make differen‐
34       tial, incremental and decremental backups. In other words, backups that
35       contain only new files or files that have changed from a backup of ref‐
36       erence. Binary delta is available but not activated by default: in com‐
37       bination  with  differential and incremental backups, it leads not only
38       to not save a file that has not changed (thing dar does without  binary
39       delta),  but  also  to  only  save an rsync patch of any modified file,
40       which lead to even smaller backups.
41
42       Moreover with differential backup, dar also stores files that have been
43       deleted  since  the  backup of reference. Thus, when restoring, first a
44       full backup, then additional differential backups, at each  restoration
45       you  get the exact state of the filesystem at the time the differential
46       backup was made.  dar is the first backup program I know that can  also
47       remove  files  during  restoration!  By the way, in this document, "ar‐
48       chive" and "backup" are used interchangeably,  the  difference  is  the
49       purpose you build them for.
50
51       Unlike  the  tar  command,  dar  has not to read a whole archive nor to
52       stick together the different parts (the slices) to access its contents:
53       dar  archives  contain a table of contents (aka "catalogue") located at
54       the end, so dar can seek into the archive to  read  only  the  required
55       data to restore files, thing which is much faster than what tar is used
56       to do. The "catalogue" can be copied  out  of  the  archive  (operation
57       called  isolation)  to  be  used as reference for further backup and as
58       backup of the internal catalogue in case of archive corruption.
59
60       Dar can also use a sequential reading mode, in which dar acts like tar,
61       just  reading  byte  by byte the whole archive to know its contents and
62       eventually extracting file at each step. In other  words,  the  archive
63       contents  is  located at both locations, a first time all along the ar‐
64       chive used for tar-like behavior suitable for sequential  access  media
65       (tapes)  and  a  second time at the end for faster access, suitable for
66       random access media (disks).  However note that tar archive and dar ar‐
67       chive  are  not  compatible. Note also that the sequential reading mode
68       let you extract data from  a  partially  written  archive  (those  that
69       failed  to  complete due to a lack of disk space for example) and since
70       release 2.6.0 such truncated archive can be repaired to become a normal
71       archive (the "catalogue" is rebuilt from inlined information).
72
73       Dar  is  able  to save and restore to a cloud storage by mean of ftp or
74       sftp network  protocols.  It  can  also  leverage  ssh  protocol  using
75       dar_slave and dar_xform two auxiliary programs provided beside dar.
76
77       Dar  format is quite robust against corruption: Only the file where the
78       corruption took place in the archive will not be possible  to  restore.
79       To have the possibility to repair a corrupted archive dar can work with
80       par2  seamlessly  just   specifying   "par2"   on   command-line   (see
81       /etc/darrc).  Last a "relax" reading mode is available which let dar to
82       either ignore some incoherence in archive structure, use  internal  re‐
83       dundant  information to overcome data corruption or in last resort ask‐
84       ing the user on what to do when some archive structure  information  is
85       missing  (-al option). This relax mode can be used with both sequential
86       and direct access read modes. Note that you should rather use  Parchive
87       to  protect  your  data  rather  than just relying on the "relax" mode,
88       which has to be seen as a the last chance solution.
89
90       dar takes care of POSIX Extended Attributes (EA in short) that are used
91       in  particular  under Linux to carry File Access Control List (FACL) as
92       well as security attributes for SELinux, and also under MacOS X EA they
93       are used to store file forks. EA also have room for user to add any key
94       / value pair to any file, this is known as user  EA.  These  attributes
95       are  not specific to any particular filesystem, they exist the same way
96       under ext3/4, HFS+ and any other filesystem.
97
98       dar also takes care of Filesystem Specific Attributes  (FSA  in  short)
99       which  are, as you can guess, specific to one or several filesystem(s).
100       For example the Birth date of a file exists for HFS+ and NTFS  but  not
101       for  ext2/3/4  filesystem.  The immutable attribute exists for ext2/3/4
102       but not for NTFS while the nodump files does not exists  for  NTFS  but
103       exists for HFS+, ext2/3/4 and many other Unix filesystems.
104
105       Sparse  files  (files with holes that system reports using several hun‐
106       dred gigabytes while they effectively use a few kilobytes on disk)  are
107       also  well  managed  by  dar: they are detected, stored and restored to
108       filesystem properly.
109
110       Last, dar is also able to properly save and restore hard-links
111

WARNING

113       This document is to be considered as a  full  reference  of  dar/libdar
114       features.  It  is however not adapted to discover dar, for that purpose
115       some tutorials are provided in dar documentation. Once you have  appre‐
116       hended  the basic dar usages you are welcome to read further this docu‐
117       ment to see all other features you may find useful for your needs.
118

DOCUMENT STRUCTURE

120       The rest of this document is organized that way:
121
122              COMMANDS
123                   The eight actions you can performs with dar
124
125              GENERAL OPTIONS
126                   A set of options common to all actions
127
128              SAVING, ISOLATING, MERGING AND REPAIRING SPECIFIC OPTIONS
129                   A set of options that are  specific  to  the  operation  of
130                   backup, catalogue isolation and archive merging
131
132              RESTORATION SPECIFIC OPTIONS
133                   A set of options that are specific to the restoration oper‐
134                   ation
135
136              TESTING AND DIFFERENCE SPECIFIC OPTIONS
137                   A set of options that are specific to the operation of  ar‐
138                   chive testing and archive comparison with a filesystem
139
140              LISTING OPTIONS
141                   A set of options that are specific to archive listing oper‐
142                   ation
143
144              EXPLICIT OPTIONAL ARGUMENTS
145                   Some system do not allow  optional  arguments  to  options,
146                   this chapter explain how to overcome this restriction
147
148              EXIT CODES
149                   List  of values dar returns at end of execution. This chap‐
150                   ter should be read if you intend to create scripts  relying
151                   on dar
152
153              SIGNALS
154                   details  the  signal  and  their  action  on  a running dar
155                   process
156
157              FILES
158                   List configuration files that dar checks for
159
160              CONDITIONAL SYNTAX
161                   Over command line, command and options can be passed to dar
162                   thanks to a plain file (known as DCF file). This plain file
163                   can also contain a specific syntax that will let  you  pass
164                   an  option  to  dar only under certain situation/condition.
165                   This chapter describes this simple syntax and the different
166                   available conditions.
167
168              USER TARGETS
169                   User  can  add  their own conditions known as user targets.
170                   This chapter describes what they are and how to use them
171
172              ENVIRONMENT
173                   Dar may rely on environment variables to look for DCF files
174                   and DUC files, SFTP private and public key and so on.
175
176

COMMANDS AND OPTIONS

178       COMMANDS:
179
180       Only  eight  commands  define  what action will be done by dar: Archive
181       creation, archive extraction, archive listing, archive testing, archive
182       comparison  with  filesystem,  catalogue isolation, archive merging and
183       archive repairing. These commands are described here below.
184
185       Once defined, a large set of options can be used to modify the way  the
186       command  is  performed. These options are described just after the com‐
187       mands chapter.
188
189       Important note: Not all systems actually support long options (Solaris,
190       FreeBSD, ...). For example --create will not be available on these sys‐
191       tems, and you will have to use -c instead. In the  same  way,  not  all
192       systems  do  support optional arguments (FreeBSD without GNU getopt for
193       example), you then need to explicitly give the argument, for example in
194       place  of "-z" you will need to give "-z 9", see "EXPLICIT OPTIONAL AR‐
195       GUMENTS" paragraph near the end of this document for  details  on  that
196       point.
197
198       A  slice  is  just a simple file which name is composed of a "basename"
199       followed by a dot, then a number, again a dot and the  extension  (dar)
200       to  form the filename of that slice. On the command line you will never
201       have to give the full file name of a slice, just the basename. The num‐
202       ber  between  the dots is the slice number, which starts from 1 and may
203       be arbitrary large (as large as your system can support the correspond‐
204       ing  filename). For example "my_first_archive.42.dar" is the 42th slice
205       of the archive which basename is "my_first_archive".
206
207       -c, --create [[<URL>]<path>/]<basename>
208                           creates a backup with the name based on <basename>.
209                           All  the  slices  will  be created in the directory
210                           <path> if specified, details about the <URL> syntax
211                           is  explained  below  at  Remote  repository syntax
212                           paragraph.  Without <path> nor  <URL>  the  current
213                           directory is used. If the destination filesystem is
214                           too small to contain all the slices of the  backup,
215                           the  -p option (pausing before starting new slices)
216                           might  be  of  interest.  Else,  in  the  case  the
217                           filesystem is full, dar will suspend the operation,
218                           asking for the user to make free space,  then  con‐
219                           tinue  its  operation. To make free space, the only
220                           thing you cannot do is to  touch  the  slice  being
221                           written. If the filename is "-" *and* no slicing is
222                           asked for (no -s option) the archive is produced on
223                           the  standard  output allowing the user to send the
224                           resulting archive through a pipe (or  into  a  tape
225                           device directly or using the dar_split command).
226
227       -x, --extract [[<URL>]<path>/]<basename>
228                           extracts  files  from  the given backup. Slices are
229                           expected to be in the current directory or  in  the
230                           directory  given by <path> (see also Remote reposi‐
231                           tory syntax below). It is also possible to use sym‐
232                           bolic  links  to  gather slices that are not in the
233                           same directory. Path may also point to a  removable
234                           device  (floppy,  CD, USB key, etc.), in this case,
235                           to be able to mount/unmount the  device,  you  must
236                           not launch dar from that directory. In other words,
237                           the current directory must not on the removable me‐
238                           dia you plan to unmount (see tutorial for details).
239                           The basename may be set to "-",  in  direct  access
240                           mode  (the  default historical mode), you will then
241                           need dar_slave to work with dar (see -i and -o  op‐
242                           tions,  as  well as dar_slave man page). However in
243                           sequential read mode (--sequential-read is used  on
244                           command-line), dar will read the archive from stan‐
245                           dard input (see also -i option), this  can  eventu‐
246                           ally be used in combination with dar_split.
247
248       -l, --list [[<URL>]<path>/]<basename>
249                           lists  the  contents  of the given backup (see also
250                           Remote repository syntax below) dar will  only  re‐
251                           quire  the  last slice of the archive in direct ac‐
252                           cess mode. If however sequential mode is used,  dar
253                           will read the overall archive, from the first slice
254                           to the last one. "-" can be used as  basename,  the
255                           behavior  is  the same as with -x option (read just
256                           above).
257
258       -t, --test [[<URL>]<path>/]<basename>
259                           checks the backup integrity. Even without  compres‐
260                           sion,  dar is able to detect at least one error per
261                           file in the archive, thanks to  a  variable  length
262                           CRC recorded per file data, file EA and file FSA in
263                           the catalogue. Archive structure (slice header, ar‐
264                           chive  header,  catalogue) is also protected by CRC
265                           to be able to detect any kind  of  archive  corrup‐
266                           tion. Same remark here, "-" may be used as basename
267                           (see -x option above for details).
268
269       -d, --diff [[<URL>]<path>/]<basename>
270                           compares saved files in the backup  with  those  on
271                           the  filesystem. <basename> may also be "-" (see -x
272                           option above for details). Note that the target for
273                           this operation is to be seen as a step further than
274                           archive testing, where in addition to  archive  co‐
275                           herence, the archive contents is verified to be the
276                           same as what is found on the filesystem. But if new
277                           files  are  present  on the filesystem, dar ignores
278                           them. If you want to check for changes since a  ar‐
279                           chive  has  been made, better use dry-run differen‐
280                           tial backup.
281
282       -C, --isolate [[<URL>]<path>/]<basename>
283                           isolate a catalogue from its archive (that's to say
284                           make  a  copy  of the internal catalogue to its own
285                           archive container). The argument is the basename of
286                           the  file  to  create  which will contain the cata‐
287                           logue's copy. The -A option is  mandatory  here  to
288                           give  the name of the archive to copy the catalogue
289                           from, this archive is not modified at all.  Slicing
290                           is available (-s -S -p -b etc.). If the filename is
291                           "-" *and* no slice is asked (no -s option) the iso‐
292                           lated catalogue is produced on the standard output,
293                           allowing the user to  send  the  resulting  archive
294                           through a pipe. Note that there is quite no differ‐
295                           ence in concept between an isolated  catalogue  and
296                           an  archive.  Thus  you can do all operations on an
297                           isolated catalogue, in particular take it in  place
298                           of the original backup as reference for a differen‐
299                           tial archive, archive testing, archive  comparison.
300                           Note  however  that  for  comparison (-d option) as
301                           data is not present in the isolated catalogue,  dar
302                           relies  on  embedded CRC rather than comparing data
303                           byte by byte  (what is done with a plain  archive),
304                           and no comparison can be performed concerning EA or
305                           FSA even if each of them have their own CRC in  the
306                           catalogue because different ordering as provided by
307                           the OS of the items composing EA and FSA  may  lead
308                           the CRC to be different while the EA or FSA are ex‐
309                           actly the same, so CRC here is used only to  detect
310                           archive corruption. Since release 2.4.0 you can use
311                           an isolated catalogue to rescue a corrupted  inter‐
312                           nal  catalogue  of the archive it has been based on
313                           (see -A option).
314
315       -+, --merge [[<URL>]<path>/]<basename>
316                           create a subset archive from one  or  two  existing
317                           archives  (the  resulting archive name is the argu‐
318                           ment to this command). The dar file selection mech‐
319                           anism  (see  GENERAL  OPTIONS)  let the user decide
320                           which files will be present in  the  resulting  ar‐
321                           chive  and  which  one will be ignored. This option
322                           thus let the user merge two archives  in  a  single
323                           one  (with  a  filtering mechanism that accepts all
324                           files), as well as this option let the user  create
325                           a  smaller  archive which data is taken from one or
326                           two archives of reference. Note that at no time the
327                           contents  of the archives of reference is extracted
328                           to real files and directories: this is  an  archive
329                           to  archive transfer, thus you may lack support for
330                           Extended Attribute while you will be able to  fully
331                           manipulate  files  with  their  Extended Attributes
332                           from one archive to the resulting one. If the base‐
333                           name is "-" *and* no slice is asked (no -s option),
334                           the archive is produced on standard output allowing
335                           the  user  to  send the resulting archive through a
336                           pipe. The first mandatory archive of  reference  is
337                           provided  thanks to the -A option, while the second
338                           "auxiliary" (and optional) archive of reference  is
339                           provided  thanks  to the -@ option. When a tie con‐
340                           tention occurs (same file names from  both  archive
341                           have  to be merged), the overwriting policy (-/ op‐
342                           tion) is used to define the one to keep in the  re‐
343                           sulting  archive. By default, archive data selected
344                           for merging  is  uncompressed,  and  re-compressed.
345                           Thus  the  merging  operation can be used to change
346                           compression algorithm of given archive as  well  as
347                           change  its encryption. But, for better performance
348                           it is also possible thanks to the -ak  option  (see
349                           below  the  -ak  option  for usage restrictions) to
350                           merge files keeping them compressed, thus no decom‐
351                           pression/re-compression  is performed at all, which
352                           make the operation faster. Last it is not  possible
353                           to merge two isolated catalogues.
354
355       -y, --add-missing-catalogue [[<URL>]<path>/]<basename>
356                           create  a  "repaired"  archive based on the archive
357                           given with -A option. The repairing  only  concerns
358                           the  case where an archive has been interrupted and
359                           dar could not  cleanly  end  the  archive  creation
360                           process  (lack  of disk space, power outage, and so
361                           on). This operation consists in  reading  the  tape
362                           marks in sequential reading mode to gather the con‐
363                           tent of the archive and once its end is reached, to
364                           recreate  the  missing  table of content (aka cata‐
365                           logue) located at the end of the archive. Note that
366                           the  damaged archive is not modified but a repaired
367                           copy is built beside it. Why not just appending the
368                           catalogue to the archive? Because first it was sim‐
369                           pler to implement allowing to reuse routines of the
370                           merging  operation, second by precaution for dar to
371                           not mess an existing archive due to a bug and last,
372                           it would not be compatible with archive signing and
373                           gpg encryption under  certain  conditions  (several
374                           recipients or the archive is signed and you are not
375                           the one who signed it).
376
377              During the repairing operation, the repaired archive may have  a
378              different  slicing  (-s  and -S options), a different encryption
379              (-K and associated options, including gpg encryption  and  sign‐
380              ing),  a  different  repository slices permissions and ownership
381              (--slice-mode option), user comment (--user-comment),  generated
382              hash (--hash) and min digits in slice number (--min-digits), but
383              compression cannot be changed and tape marks cannot  be  removed
384              (you  can  do it once reparation has completed using the merging
385              operation). Last, file filtering is not allowed  during  archive
386              repairing.
387
388       -h, --help          displays help usage.
389
390       -V, --version       displays version information.
391
392       Remote repository syntax for [<URL>]<path>
393
394              for  all  commands  described  above as well as some options de‐
395              tailed below (-A and -@ options), the <path>  optional  argument
396              can  be a Unix path like /var/tmp when the archive is located on
397              the host dar runs on. But it can also make use of <URL>  to  de‐
398              fine  the  remote  host the archive is to be read or written to.
399              "<URL><path>" follows the usual syntax:
400
401                     proto://[login[:password]@]hostname[:port]/path
402
403              proto
404                 is either ftp or sftp
405
406              login
407                 is optional, if not provided it defaults  to  anonymous.   If
408                 the login string comports an @ it need to be escaped by \\ (a
409                 pair of backshashes) to avoid libdar considering it the host‐
410                 name  starting  part.  Example:  login is me@here.com host is
411                 www.example.org     gives:     sftp://me\\@here.com@www.exam‐
412                 ple.org/some/file.  You  may also need to escape the same way
413                 any other special characters like for example colon (:) slash
414                 (/) if they are part of the login string.
415
416              password
417                 if  login  is  provided, the associated password may be given
418                 after a colon (:) but this exposes  the  secret  password  to
419                 other  users of the current system having access the table of
420                 process (using top, ps, /proc or other ways). If the login is
421                 given  without  password, the password will be asked interac‐
422                 tively by dar at run time, which is much more secure.  Alter‐
423                 natives  are either to rely on ~/.netrc for FTP and also SFTP
424                 (!) transfers for that you need to use  the  --alter=file-au‐
425                 thentication  option  (see below), or for SFTP only on public
426                 key authentication (you can also use --alter=file-authentica‐
427                 tion  in  that  case to avoid a password being asked interac‐
428                 tively). Note that passphrase support for  sftp  key  is  not
429                 (yet) supported.
430
431              hostname
432                 is the name or IP address of the host to connect to. For sftp
433                 the   server's   public   key   is   checked   against    the
434                 ~/.ssh/known_hosts file (or the file pointed to by then envi‐
435                 ronment variable DAR_SFTP_KNOWNHOST_FILE,  see  more  details
436                 about that variable at the bottom of this man page), the host
437                 must be known and the public key received  from  the  network
438                 must match the one in that file, else dar aborts. If thus you
439                 want to operate with a new sftp server, first use ssh of sftp
440                 commands  to do the usual fingerprint verifications which up‐
441                 dates the known_hosts file accordingly, then  run  dar/libdar
442                 toward this sftp server.
443
444              port
445                 if  not  provided,  dar will use the default/standard port in
446                 regard to the protocol specified in the "proto" field
447
448              path
449                 a unix path where resides the archive to read from the remote
450                 repository  or  where  to write the archive to in that remote
451                 repository. The given path is absolute, in regard to the  re‐
452                 mote  root  filesystem available for the given account though
453                 the requested protocol. See also --network-retry-delay option
454                 below.
455
456       GENERAL OPTIONS:
457
458       -v, --verbose       For  backward  compatibility,  this  is an alias to
459                           "-vt -vm" (both options set).
460
461       -vs, --verbose=skipped
462                           Display files skipped because of file filtering ex‐
463                           clusion specified by the user
464
465       -vt, --verbose=treated
466                           Display treated files because of file filtering in‐
467                           clusion specified by the user or no file  filtering
468                           specified  at  all. For each file a message is dis‐
469                           played *before* the file is treated. This option is
470                           not  available for archive isolation and is useless
471                           for archive listing as it is always set, unless  -q
472                           is used.
473
474       -vd, --verbose=dir  Display  the  directory under process. The messages
475                           shows *before* entering a directory. You can have a
476                           less  verbose  output than -vt while are still able
477                           to follow what's dar is doing. Note  that  -vt  and
478                           -vd are mutually exclusive.
479
480       -vm, --verbose=messages
481                           Display  detailed  messages  about what dar is cur‐
482                           rently performing  but  not  related  to  currently
483                           treated or skipped files and directories
484
485       -vf, --verbose=finished
486                           Issues  a  summary  *after*  each treated directory
487                           containing the amount of data backed up in that di‐
488                           rectory  as  well as the average compression ratio.
489                           This option is only available for archive creation.
490
491       -va, --verbose=all  is equivalent to -vm -vs -vt, see also  -Q  and  -q
492                           options  below.  Note: When using dar from a script
493                           better use dar's exit status to know which way  the
494                           operation  has ended (seen EXIT CODES at the end of
495                           this document).
496
497       -vmasks, --verbose=masks
498                           Display raw information about the masks set by  dar
499                           and passed to libdar
500
501
502       -q, --quiet         Suppress the final statistics report. If no verbose
503                           output is asked beside this option, nothing is dis‐
504                           played  if  the  operation succeeds. When using dar
505                           from a script better use dar's exit status to  know
506                           which  way the operation has ended (seen EXIT CODES
507                           at the end of this document)
508
509
510       -b, --beep          makes the terminal ring when  user  action  is  re‐
511                           quired  (like  for  example  the  creation of a new
512                           slice using the -p option)
513
514       -B, --batch <filename>
515                           In the file which name is given in argument to this
516                           option,  You can put any option or argument as used
517                           on command line, that will be  parsed  as  if  they
518                           were  in  place of the "-B <filename>" option. This
519                           way you can overcome the command line size  limita‐
520                           tion.  Commands in the file may be disposed on sev‐
521                           eral lines, and -B option can also be  used  inside
522                           files,  leading  a file to include other files. But
523                           an error occurs in case of loop (a  file  that  in‐
524                           cludes itself directly or not) and DAR aborts imme‐
525                           diately. Comments are allowed, and must start by  a
526                           hash  `#'  character  on each line. Note that for a
527                           line to be considered as a comment the hash charac‐
528                           ter  must be the first character of the line (space
529                           or tab can still precede the hash). See Conditional
530                           Syntax  below  for  a richer syntax in this type of
531                           configuration files known as DCF file (Dar Configu‐
532                           ration  File).  See  also  the environment variable
533                           DAR_DCF_PATH in the ENVIRONMENT section at the  end
534                           of this document.
535
536                           Note  that you can use quotes simple (´arg´) double
537                           ("arg") and back-quotes (`arg`) inside  such  file,
538                           but  they need to be balanced (have an ending one).
539                           To use such character  without  the  meaning  of  a
540                           quote,  for  example  as an apostrophe, you need to
541                           escape it using a  back-slack  ("That\'s  an  exam‐
542                           ple").  Of  course  to add a single back-slash as a
543                           normal character in the file you will have to  dou‐
544                           ble it ("c:\\windows" for example)
545
546       -N, --noconf        Do  not try to read neither ~/.darrc nor /etc/darrc
547                           configuration files. See files section below.
548
549       -Q                  Do not display an initial warning  on  stderr  when
550                           not  launched from a terminal (when launched from a
551                           cronjob for example). This means that all questions
552                           to the user will be answered by 'no', which most of
553                           the time will abort the program. Please  note  that
554                           this  option cannot be used in a configuration file
555                           (-B option). Since version 2.2.2, giving  this  op‐
556                           tion  also forces the non-interactive mode, even if
557                           dar is launched from a terminal. This makes it pos‐
558                           sible  for  dar  to run in the background. When you
559                           do, it's recommended to also redirect stdout and/or
560                           stderr to files: dar -Q ... &> /dev/null &
561
562       -n, --no-overwrite  do not allow overwriting
563
564                           If  an  overwriting policy is specified (see -/ op‐
565                           tion) -n option do only apply to  slices  overwrit‐
566                           ing, the overwriting of files during restoration or
567                           merging is handled by the overwriting policy. With‐
568                           out  overwriting  policy,  -n  applies  to restored
569                           files as well as generated slices.
570
571       -w, --no-warn       Do not warn before overwriting (applied  for  slice
572                           overwriting  and  for  overwriting decision make by
573                           the overwriting policy). By default overwriting  is
574                           allowed  but a warning is issued before proceeding.
575                           This option may receive 'a' as argument  (see  just
576                           below):
577
578       -wa, --no-warn=all  This  implies  the  -w  option, and means that over
579                           avoiding warning for  file  overwriting,  DAR  also
580                           avoids  signaling  a  file about to be removed when
581                           its type is not the expected one. File are  removed
582                           when  they  have been recorded as deleted since the
583                           archive of reference. At restoration of the differ‐
584                           ential archive, if a file of the given name exists,
585                           it is remove, but if the type does  not  match  the
586                           file that was present at the time of the archive of
587                           reference (directory,  plain  file,  fifo,  socket,
588                           char  or block device, etc.), a warning is normally
589                           issued to prevent the accidental  removal  of  data
590                           that was not saved in the backup of reference. (See
591                           also -k option)
592
593       -A, --ref [[<URL>]<path>]/<basename>
594                           Depending on the context, it specifies the  archive
595                           to use as reference, which is mandatory for archive
596                           isolation (-C option) and merging operation (-+ op‐
597                           tion).  Else  it  specifies the rescue catalogue to
598                           use when restoring (-x command), testing  (-t  com‐
599                           mand)  or  comparing  (-d  command) an archive. All
600                           slices of the reference backup are expected  to  be
601                           on  the  same directory given by <path> or the cur‐
602                           rent directory by default. Usually  only  the  last
603                           slice  is required to extract the catalogue of ref‐
604                           erence. If necessary the use of symbolic  links  is
605                           also possible here to gather slices that do not re‐
606                           side in the same  directory.  You  can  also  point
607                           <path>  to a USB key, DVD-R(W) or any other mounted
608                           directory, because dar will pause and ask the  user
609                           for  required  slices  if they are not present. The
610                           argument to -A may be of four types:
611
612                                  - An existing archive basename,  which  will
613                                  be taken as reference
614
615                                  -  a  dash  ("-") in direct access mode (de‐
616                                  fault mode, when  --sequential-read  is  not
617                                  used)  it may imply the use of -o and -i op‐
618                                  tions, this allows the archive of  reference
619                                  to  be  read  from  a  pair  of  pipes  with
620                                  dar_slave at the other ends.  Dar_slave  can
621                                  be  run through ssh on a remote host for ex‐
622                                  ample. Note that this type of argument ("-")
623                                  is only available when -A is used for isola‐
624                                  tion (-C option) and merging  (-+  options).
625                                  In  sequential  mode  (--sequential-read  is
626                                  used), the archive of reference is read from
627                                  standard input or from the named pipe speci‐
628                                  fied by -i option. -o option has no  use  in
629                                  sequential mode. Note that merging operation
630                                  (-+ option) cannot read archive of reference
631                                  in sequential mode.
632
633                                  -  a  plus sign ("+") which makes the refer‐
634                                  ence be the current directory  status.  This
635                                  argument  is only available for archive cre‐
636                                  ation (-c option). In other word, no  file's
637                                  data  will be saved, just the current status
638                                  of the inodes will be recorded in the  cata‐
639                                  logue.  This  feature is known as the "snap‐
640                                  shot" backup. A snapshot backup can be  used
641                                  as reference later on to detect or save only
642                                  the files that have changed since the  snap‐
643                                  shot was made.
644
645                                  -  a  <date>,  if -af option has been placed
646                                  before -A on the command-line or  in  a  in‐
647                                  cluded  file (see -B option). For more about
648                                  that feature see -af option below. This form
649                                  is  only  available for archive creation (-c
650                                  option).
651
652                           During backup operation (-c option) the archive  of
653                           reference,  given  thanks to the -A option, is used
654                           for comparison with existing files on the  filesys‐
655                           tem.  Dar  will  then  backup  only files that have
656                           changed since the archive of reference was done. If
657                           no  -A  option  is given, the backup operation is a
658                           full backup. With -A option if the archive of  ref‐
659                           erence is a full backup some call it a differential
660                           backup, while if the archive of reference  is  dif‐
661                           ferential  backup, some call this type of backup an
662                           incremental backup. For dar there is no  difference
663                           in  structure  between incremental and differential
664                           backup, both are usually designed globally as "dif‐
665                           ferential" backup in the documentation.
666
667                           During  merging operation (-+ option), the contents
668                           of the -A given archive will been taken  eventually
669                           with  the  contents  of the -@ auxiliary archive if
670                           specified (see below), to form a new  archive  from
671                           files  of this or these archives. Note that you can
672                           filter out files from the operation and setup  sub‐
673                           set of the original archive(s).
674
675                           During  Catalogue  isolation  (-C option), dar will
676                           create the isolated catalogue from  the  one  given
677                           with -A option.
678
679                           During  testing,  diff or extraction, (-t, -d or -x
680                           options respectively), the table of  contents  (the
681                           catalogue) will be read from the archive given with
682                           -A instead of using the internal catalogue  of  the
683                           archive. The archive given for rescue must has been
684                           previously isolated from this  same  archive  (else
685                           the  contents will not match and dar will refuse to
686                           proceed to this operation). This acts as  a  backup
687                           solution  to  the  case of corruption inside an ar‐
688                           chive's catalogue, while the best way is  still  to
689                           use Parchive to protect your data against media er‐
690                           ror.
691
692       -af, --alter=fixed-date
693                           Modify the -A option behavior, making it  receiving
694                           a    <date>   as   argument   in   place   of   the
695                           [<path>]/<basename> default argument. The <date> is
696                           used to define which file to save: file which modi‐
697                           fication is newer or equal to <date>, and which  to
698                           consider  unchanged:  those older than <date>. This
699                           option has only a meaning when creating an  archive
700                           (-c  option) and must be placed before -A option to
701                           have an effect.
702
703                           <date> must be a date in the two following possible
704                           formats:
705                                  - a number of second since Jan 1st, 1970
706                                  -    a    date   in   the   following   form
707                                  [[[year/]month/]day-]hour:minute[:second]
708
709                           Here are some examples of date:
710                                  91836383927108078
711                                  1 2005/11/19-19:38:48 Which is 38 past 7  PM
712                                  and 48 seconds, the 19th of November 2005
713                                  20:20 Which is 8 PM of the current day
714                                  2-00:08 Which is 8 past noon, the second day
715                                  of the current month
716                                  2/2-14:59 Which is 1 to 3  PM,  the  2nd  of
717                                  February in the current year
718
719                           Note that the provided date is relative to the sys‐
720                           tem timezone which is overridden if the TZ environ‐
721                           ment  variable is set (see tzselect(1) for more de‐
722                           tails)
723
724       -@, --aux [[<URL>]<path>]/<basename>, --on-fly-isolate  [<path>]/<base‐
725       name>
726                           specifies  an auxiliary archive of reference (merg‐
727                           ing context) or the name  of  the  on-fly  isolated
728                           catalogue  (creation  context). This option is thus
729                           only available with -+ option (merging) and -c  op‐
730                           tion  (archive creation). Note that --aux and --on-
731                           fly-isolate are really aliases to the same  option,
732                           this  is  the  context  of use (archive creation or
733                           merging) which lead it to behave a way or another.
734
735                           In a merging  context,  over  -A  option  which  is
736                           mandatory,  you may give a second archive of refer‐
737                           ence thanks to the -@ option. This  allows  you  to
738                           merge  two  archives into a single one. See also -$
739                           option (encryption) -~ option  (command  execution)
740                           and  -%  (crypto block size) for other options con‐
741                           cerning auxiliary archive of  reference.  They  are
742                           the  respective equivalent of -J, -F and -* options
743                           relative to archive given thanks to -A option.
744
745                           In a backup context -@ option let the user  specify
746                           the  archive name for an on-fly isolation. With on-
747                           fly isolation, you can also use -$ option  (to  de‐
748                           fine  encryption  algorithm and passphrase), -~ op‐
749                           tion (to execute a command once the on-fly isolated
750                           catalogue is completed) and -% option (crypto block
751                           size). On-fly isolated catalogue is always bzip2 if
752                           possible  else gzip else lzo compressed (using com‐
753                           pression level 9) else not compressed,  and  it  is
754                           also  always  a  single sliced archive. Due to com‐
755                           mand-line exiguity, it is not  possible  to  change
756                           compression algo nor slice size for the on-fly iso‐
757                           lation. If you need a more  complicated  isolation,
758                           either  look  for a GUI over libdar, or do a normal
759                           (= not an on-fly) isolation operation (By  the  way
760                           it is possible to isolate an already isolated cata‐
761                           logue, this is equivalent to doing a copy, but  you
762                           can  change encryption, compression or slicing, for
763                           example), you can also use dar_xform on an isolated
764                           catalogue  if  you  only want to change slices size
765                           (this is faster as no  decompression/re-compression
766                           nor  encryption/decryption is necessary). Using the
767                           merging operation on an isolated catalogue  instead
768                           of  isolating the isolated catalogue, leads the re‐
769                           sulting archive to not be able to be used as a res‐
770                           cue for internal catalogue of the original archive.
771                           --aux-ref is a synonym to --aux.
772
773       -R, --fs-root <path>
774                           The path points to the  directory  tree  containing
775                           all  the  files that will be enrolled in the opera‐
776                           tion (backup, restoration or  comparison).  By  de‐
777                           fault  the  current  directory  is  used. All other
778                           paths used in -P or -g options on the command  line
779                           are  and  must be relative to this path (or to cur‐
780                           rent directory if -R is not present). Note that  -R
781                           is  useless  for  testing (-t option) isolation (-C
782                           option) and merging (-+ option)
783
784       -X, --exclude <mask>
785                           The mask is a string with wildcards (like *  and  ?
786                           see  glob(7) for details) which is applied to file‐
787                           names which are not directories. If  a  given  file
788                           matches  the  mask,  it is excluded from the opera‐
789                           tion. By default (no -X on the  command  line),  no
790                           file  is  excluded  from  the  operation. -X may be
791                           present several times on the command line, in  that
792                           case  a  file  will not be considered for the given
793                           operation if it matches at least one -X  mask.  See
794                           also -ar and -am options.
795
796       -I, --include <mask>
797                           The  mask is applied to filenames which are not di‐
798                           rectories (see  glob(7)  for  details  on  wildcard
799                           characters).  If  a given file matches the mask and
800                           does not match any mask given with -X, the file  is
801                           selected  for  the operation. By default (no -I and
802                           no -X on the command line), all files are  included
803                           for  the operation. -I may be present several times
804                           on the command line, in that case  all  files  that
805                           match one of the -I mask will be considered for the
806                           given operation, if they do not also match  one  of
807                           the -X mask. See also -ar and -am options.
808
809       -P, --prune <path>  Do not consider file or directory sub-tree given by
810                           the path. -P may be present  several  time  on  the
811                           command  line.  The  difference with -X is that the
812                           mask is not applied only to the filename, but  also
813                           include  the  path. Moreover it applies also to di‐
814                           rectories (-X does not). By default (no -P  on  the
815                           command-line), no sub-tree or file is excluded from
816                           the operation, and the whole directory tree (as in‐
817                           dicated  by  -R  option)  is  considered. Note that
818                           <path> may contains  wildcards  like  *  or  ?  see
819                           glob(7) man page for more information.
820
821       -g, --go-into <path>
822                           Files  or directory to only take in account, as op‐
823                           posed to -P. -g may be present several time on com‐
824                           mand-line.  Same thing here, the difference with -I
825                           is that the mask is applied  to  the  path+filename
826                           and also concerns directories. By default all files
827                           under the -R directory are considered. Else, if one
828                           or more -g option is given, just those are selected
829                           (if they do not match any  -P  option).  All  paths
830                           given  this  way  must be relative to the -R direc‐
831                           tory, which defaults to current  directory.   Warn‐
832                           ing,  -g  option  cannot  receive  wildcards, these
833                           would not be interpreted.
834
835       -[, --include-from-file <listing_file>
836                           Files listed in the listing file are  included  for
837                           the  operation.  No  wildcard  expression is inter‐
838                           preted in the listing file, the null  character  is
839                           not allowed and the carriage return is used to sep‐
840                           arate file names (one file name per line) each line
841                           must  not exceed 20479 bytes. Note that this option
842                           applies to any files and directory  exactly  as  -g
843                           does,  with an important difference however: -g op‐
844                           tion only uses relative paths to the root directory
845                           (the  directory given with the -R option), while -[
846                           can use absolute path as well.  Another  difference
847                           is when the argument is a directory -g will include
848                           all the subdirectories under that directory,  while
849                           when  the  same  entry  is  found in a listing file
850                           given to -[ only that directory will  be  included,
851                           no subdirectory or subfile would be enrolled in the
852                           backup, with -[ you need to list the exact  set  of
853                           file  you  want  to backup. You can thus generate a
854                           listing file with the 'find /  -print  >  somefile'
855                           command  and  give 'somefile' as argument to -[ op‐
856                           tion. Note that however, dar will never save  files
857                           out  of  the  -R given root directory tree, even if
858                           some are listed in the 'somefile' file.
859
860       -], --exclude-from-file <listing_file>
861                           Files listed in the listing file are excluded  from
862                           the  operation.  If  a  directory  is listed in the
863                           file, all its contents is excluded. This option  is
864                           the  opposite of -[ and acts the same was as -P op‐
865                           tion does (in particular  it  is  compared  to  the
866                           whole path+filename and applies to files and direc‐
867                           tories). As for -[ option, -] listing file can con‐
868                           tain  absolute  paths,  but  wildcards  are not ex‐
869                           panded, neither.
870
871       File selection in brief:
872
873       As seen above, -I -X -P, -g, -[ and -] options are used to  select  the
874       files  to  operate  on. -I and -X only use the name of files and do not
875       apply to directories, while -P, -g -[ and -] use the filename *and* the
876       path, they *do* apply to directories.
877
878       since version 2.2.0 two modes of interpretation of these options exist.
879       The normal original method and the ordered method:
880
881              the normal method is the default and is the one  that  has  been
882              presented above:
883                   A  directory is elected for operation if no -P or -] option
884                   excludes it. If at least one -g or -[ option is  given  one
885                   command line, one -g or -[ option must cover it, else it is
886                   not elected for operation. If a directory is not  selected,
887                   no  recursion  is done in it (the directory is pruned). For
888                   non directories files, the same is true (P, -g, -[  and  -]
889                   do  apply)  and a second test must also be satisfied: no -X
890                   option must exclude the filename, and if at  least  one  -I
891                   option  is  given, one must match the given filename (using
892                   or not wildcards).
893
894              the ordered method (when -am option is given on command-line):
895                   The ordered method takes care of the order of presence  be‐
896                   tween -X and -I in one hand and of -P, -g, -[ and -] in the
897                   other hand (note that it has also the same action  concern‐
898                   ing  EA  selection when using -u and -U options, but that's
899                   no more file selection). In the ordered method the last ar‐
900                   gument  take  precedence  over all the previous ones, let's
901                   take an example:
902
903                   -X "*.mp?" -I "*.mp3" -I "toto*"
904                        Here dar will include all files except  file  of  name
905                        "*.mp?"  (those ending with "mpX" where X is any char‐
906                        acter), but it will however include those ending  with
907                        ".mp3". It will also include files which name begin by
908                        "toto" whatever they end with.  This  way,  "toto.mp2"
909                        will be saved (while it matches "*.mp?" it also begins
910                        by "toto") as well as "toto.txt" as well as  "joe.mp3"
911                        (while  it matches "*.mp?" it also ends by "mp3"). But
912                        will not be saved "joe.mp2" (because it does not begin
913                        by "toto", nor ends by "mp3", and match "*.mp?" mask).
914                        As we see the last option (-I  or  -X)  overcomes  the
915                        previous  one. -P, -g, -[ and -] act together the same
916                        but as seen above they do not only  act  on  filename,
917                        but on the whole path+filename. Note that (-g, -P, -[,
918                        -]) and (-X , -I)  are  independent  concerning  their
919                        relative  order.  You can mix -X -I -g -P -] -[ in any
920                        order, what will be important is  the  relative  posi‐
921                        tions  of  -X  options compared to -I options, and the
922                        relative positions of -g -[ -] and -P options  between
923                        them.
924
925              In  logical  terms,  if <prev_mask> is the mask generated by all
926              previous mask on the command line, -I <mask> generates  the  new
927              following  mask:  <prev_mask> or <mask> . While -X <mask> gener‐
928              ates the new following mask: <prev_mask> and not <mask>. This is
929              recursive  each  time you add a -I or -X option. Things work the
930              same with -P, -g, -[ and -] options.
931       This ends the file selection explication let's continue with other  op‐
932       tions.
933
934       -u, --exclude-ea <mask>
935                           Do  not  consider the Extended Attributes (EA) that
936                           are matched by the given mask. By  default,  no  EA
937                           are  excluded, if the support for EA has been acti‐
938                           vated at compilation time. This option can be  used
939                           multiple times.
940
941       -U, --include-ea <mask>
942                           Do  only consider the EA that match the given mask.
943                           By default, all EA are included if no -u or -U  op‐
944                           tion  is present and if the support for EA has been
945                           activated at compilation time. This option  can  be
946                           used  multiple  times. See also the -am and -ae op‐
947                           tions, they also apply to -U  and  -u  options  and
948                           read below the Note concerning EA.
949
950       Note concerning Extended Attributes (EA)
951
952              Support  for  EA must be activated at compilation time (the con‐
953              figure script tries to do so if your system has all the required
954              support  for that). Thus you can get two binaries of dar (of the
955              same version), one supporting EA and another which does not (dar
956              -V  to  see  whether EA support is activated). The archives they
957              produce are the same and can be read by  each  other.  The  only
958              difference  is that the binary without EA support is not able to
959              save or restore EAs, but is still able to  test  them  and  list
960              their presence.
961
962              In  the  following  when  we will speak about Extended Attribute
963              (EA) or EA entry, we will only consider  a  particular  Extended
964              Attribute  key  and  its value. By opposition, the set of all EA
965              associated to a file will be designated by "EA set".
966
967              Since version 2.3.x the name of EA entries include the namespace
968              for  dar  be  able to consider any type of EA (not only "system"
969              and "user" as previously). Thus the two previous options -u  and
970              -U have changed and now take an argument which is a mask applied
971              to EA entry names written in the following  form  namespace.name
972              where  "namespace" is for example "user". Note that the mask may
973              or may not include the dot (.) and may match arbitrary  part  of
974              the EA namespace+name, just remind that masks will be applied to
975              the "namespace.name" global string.
976
977              the -am flag here also enables the ordered method, for EA selec‐
978              tion  too.  The ordered versus normal method have been explained
979              above in the file selection note, with some  examples  using  -X
980              and  -I.  Here this is the same with -U and -u, (just replace -X
981              by -u and -I by -U, the corresponding mask  will  apply  to  Ex‐
982              tended Attribute selection in place of file selection).
983
984              Another  point,  independently  of the -am option the -ae option
985              can be used at restoration time only. If set,  when  a  file  is
986              about  to  be  overwritten,  all  EA will be first erased before
987              restoring those selected for restoration in the archive (accord‐
988              ing  to  the -U and -u options given). If not set, the EA of the
989              existing file will be overwritten, those extra EA that  are  not
990              in  the archive or are not selected for restoration in regard to
991              the -u and -U options will be preserved. If you  have  not  used
992              any  -u/-U  option at backup time and want to restore from a set
993              of full/differential backups the EA exactly as  they  were,  you
994              have  to use -ae for dar removes the EA before overwriting their
995              set of EA as stored in the archive. Without -ae option dar  will
996              simply  add  EA to existing ones, thus get a different set of EA
997              for a give file than those recorded at the time of the backup.
998
999              Last point the -acase and -an options alters the case  sensitiv‐
1000              ity  of  the   -U  and -u masks that follow them on the command-
1001              line/included files as they do for -I, -X, -P, -g, -[ and -]  as
1002              well.  Very  last point ;-), if -ac option is used during backup
1003              dar set back the atime after having read each file (see  -aa/-ac
1004              options),  this  has  as side effect to modify the ctime date of
1005              each file. But ctime change is used by dar to detect EA changes.
1006              In  brief,  the  next time you backup a file that had to be read
1007              (thus which contents changed), its EA will be saved even if they
1008              had  not  changed.  To avoid this side effect, don't use the -ac
1009              option if not necessary.
1010       This ends the Extended Attribute selection explication  let's  continue
1011       with other options.
1012
1013       -4 --fsa-scope <family>[,<family>[, ...]
1014                           Reduce  the  scope of Filesystem Specific Attribute
1015                           (FSA) to be considered for the operation.  FSA  are
1016                           grouped by family. Current available families are:
1017
1018                           extX this  family takes care of Linux ext2/3/4 flag
1019                                attributes  set  by  chattr(1)  and  read   by
1020                                lsattr(1).  Dar  only considers flags that are
1021                                possible to set or clear by users  (or  privi‐
1022                                leged  user): append-only, compressed, no_dump
1023                                (Yes, dar can save  files  having  the  nodump
1024                                flag  set and restore then afterward with that
1025                                flag set!),  immutable,  data-journaling,  se‐
1026                                cure-deletion,  no-tail-merging,  undeletable,
1027                                noatime-update,  synchronous-directory,   syn‐
1028                                chronous-update,   top-of-directory-hierarchy.
1029                                Note that "extx" and  "ext"  are  aliases  for
1030                                this  FSA  family.  In spite of its name, this
1031                                family  of  attributes  is  not   limited   to
1032                                ext2/3/4 filesystems.
1033
1034                            HFS+
1035                                this  family takes care of Mac OS X HFS+ birth
1036                                date of files, in addition of  commonly  found
1037                                dates  like  atime  (last  access time), ctime
1038                                (last meta data change) and mtime  (last  data
1039                                change).
1040
1041                           none "none"  is  not  a  FSA family but can be used
1042                                alone to ignore all FSA families.
1043
1044                           By default no restriction is done and  FSA  of  all
1045                           families are considered at restoration time, but if
1046                           a family has not been activated at compilation time
1047                           a  warning is issued for each file that cannot have
1048                           its FSA restored completely (unless this family  is
1049                           excluded  from  the scope thanks to the -4 option).
1050                           At backup time, if an FSA family has not been acti‐
1051                           vated at compilation time, no warning is issued and
1052                           FSA of that family are  ignored.  Still  at  backup
1053                           time, you can also ignore FSA that have compilation
1054                           time support by excluding them from  the  operation
1055                           thanks to this -4 option.
1056
1057                           Example of use: --fsa-scope extX,HFS+
1058
1059       -am, --alter=mask   set the ordered mode for mask. This affects the way
1060                           -I and -X options are interpreted, as well  as  -g,
1061                           -P, -[ and -] options, -Z and -Y options and -U and
1062                           -u options. It can take any place on  the  command-
1063                           line  and can be placed only once. See the file se‐
1064                           lection in brief paragraph above for a detailed ex‐
1065                           planation  of this option. It has also an incidence
1066                           on the --backup-hook-exclude and  --backup-hook-in‐
1067                           clude options.
1068
1069       -an, --alter=no-case
1070                           set the filters in case insensitive mode. This con‐
1071                           cerns only masks specified after this  option  (see
1072                           also  -acase option below). This changes the behav‐
1073                           ior of -I, -X, -g, -P, -Z, -Y, -u and -U options.
1074
1075                           Warning: case insensitivity  requires  interpreting
1076                           filenames  which  depends  on the locale with which
1077                           dar is run (defined by the LANG  environment  vari‐
1078                           able).  For  example  if you create files with LANG
1079                           set to fr_FR.UTF-8 and use non plain ASCII  charac‐
1080                           ters  in  filename, there is chances that these non
1081                           ASCII characters will be stored over several  bytes
1082                           in  that  filename: so called "wide characters". If
1083                           then you run dar with LANG  set  to  another  value
1084                           like  ru_RU.koi8r, there is much chances that these
1085                           wide characters do not correspond to the same  let‐
1086                           ter or worse, that they do not match any valid wide
1087                           character for that locale. A filename is  always  a
1088                           sequence of bytes and always saved as such, but us‐
1089                           ing --alter=no-case implies interpreting  that  se‐
1090                           quence  in  a  way that depends on the given locale
1091                           (as defined by the LANG environment  variable).  As
1092                           such,  dar  cannot  know  if a given file has to be
1093                           read with fr_FR.UTF-8 locale or with it_IT.iso88591
1094                           or  ru_RU.koi8r and so on, because this information
1095                           is not stored in filenames. In consequence, if dif‐
1096                           ferent  locales are used on your system and you are
1097                           doing a system wide backup,  using  --alter=no-case
1098                           option  may lead dar to detect invalid wide charac‐
1099                           ter, in that case it falls back to a byte  by  byte
1100                           case  sensitivity  comparison  (ASCII  characters),
1101                           which may not be what you  would  expect  at  first
1102                           sight: Most of the time, an upper case wide charac‐
1103                           ter (stored on several bytes) does  not  match  the
1104                           equivalent lower case wide character (several bytes
1105                           too), when case sensitivity comparison is performed
1106                           byte by byte.
1107
1108       -acase, --alter=case
1109                           set  back  to  case sensitive mode for filters. All
1110                           following masks are case sensitive, up  to  end  of
1111                           parsing  or up to the next -an option. This changes
1112                           the behavior of -I, -X, -g, -P, -Z, -Y, -u  and  -U
1113                           options.
1114
1115       -ar, --alter=regex  set  the  filters  to be interpreted as regular ex‐
1116                           pressions (man regex(7) ) instead  of  the  default
1117                           glob  expression  (man  glob(7) ) This modifies the
1118                           -I, -X, -g, -P, -Z, -Y, -u and -U options that fol‐
1119                           lows up to an eventual -ag option (see just below).
1120                           Note that for -P option, the given mask matches the
1121                           relative path part of the files path: Let's take an
1122                           example, assuming you have provided  /usr/local  to
1123                           the  -R  option, the mask "^foo$" will replaced in‐
1124                           ternally  by  "^/usr/local/foo$"  while  the   mask
1125                           "foo$"  will  be  replaced internally by "^/usr/lo‐
1126                           cal/.*foo$".
1127
1128       -ag, --alter=glob   This option returns to glob expressions mode (which
1129                           is  the default) after an -ar option has been used,
1130                           this applies to any -I, -X, -g, -P, -Z, -Y, -u  and
1131                           -U  options  that  follow up to an eventual new -ar
1132                           option (see just above).
1133
1134       -i, --input <path>  is available when reading from  pipe  (basename  is
1135                           "-"  for -x, -l, -t, -d or for -A when -c, -C or -+
1136                           is used). When reading from pipe, standard input is
1137                           used,  but  with this option, the file <path> (usu‐
1138                           ally a named pipe) is used instead.  This option is
1139                           to  receive  output  from  dar_slave  program  (see
1140                           doc/usage_notes.html for  examples  of  use).  Note
1141                           that  when  --sequential-read  is  used, dar uses a
1142                           single pipe and does no more rely on dar_slave,  -i
1143                           option  can be used to tell dar which named pipe to
1144                           read the archive from, instead of the standard  in‐
1145                           put.
1146
1147       -o, --output <path> is  available  when  reading from pipe (basename is
1148                           "-" for -x, -l, -t, -d or for -A when -c, -C or  -+
1149                           is  used).  When reading from pipe, standard output
1150                           is used to send request to dar_slave, but with this
1151                           option,  the  file <path> (usually a named pipe) is
1152                           used instead. When standard  output  is  used,  all
1153                           messages  goes to standard error (not only interac‐
1154                           tive messages). See doc/usage_notes.html for  exam‐
1155                           ples of use. This option is not to be used in --se‐
1156                           quential-read mode.
1157
1158       -O, --comparison-field[=<flag>]
1159                           When comparing with the archive  of  reference  (-c
1160                           -A)  during  a differential backup, when extracting
1161                           (-x) or when comparing (-d) do only considers  cer‐
1162                           tain fields. The available flags are:
1163
1164                           ignore-owner   all  fields  are  considered  except
1165                                          ownership.
1166                                          This is useful when dar is used by a
1167                                          non-privileged  user.  It  will  not
1168                                          consider a file has changed just be‐
1169                                          cause  of  a uid or gid mismatch and
1170                                          at restoration dar will not even try
1171                                          to set the file ownership.
1172
1173                           mtime          only  inode  type and last modifica‐
1174                                          tion date is considered as  well  as
1175                                          inode  specific attributes like file
1176                                          size for plain files.  Ownership  is
1177                                          ignored, permission is ignored. Dur‐
1178                                          ing comparison, difference on owner‐
1179                                          ship or permission is ignored and at
1180                                          restoration time dar will not try to
1181                                          set  the inode permission and owner‐
1182                                          ship.
1183
1184                           inode-type     Only the inode type  is  considered.
1185                                          Ownership,  permission and dates are
1186                                          ignored. Inode  specific  attributes
1187                                          are still considered (like file size
1188                                          for plain  files).  Thus  comparison
1189                                          will  ignore  differences for owner‐
1190                                          ship, permission, and dates  and  at
1191                                          restoration  dar will not try to set
1192                                          the ownership, permission and dates.
1193
1194                           When no flag is provided to this option, -O  option
1195                           acts  as  if the "ignore-owner" flag was set, which
1196                           is the behavior in older releases (<  2.3.0).  Note
1197                           also  that  for  backward  compatibility, --ignore-
1198                           owner option still exists and since  version  2.3.0
1199                           is  just an alias to the --comparison-field=ignore-
1200                           owner option. Of course if this option is not used,
1201                           all fields are used for comparison or restoration.
1202
1203       -H[num], --hour[=num]
1204                           if  -H  is  used, two dates are considered equal if
1205                           they differ from a integer  number  of  hours,  and
1206                           that  number is less than or equal to [num]. If not
1207                           specified, num defaults to 1.  This  is  used  when
1208                           making a differential backup, to compare last_modi‐
1209                           fication date of inodes, at restoration or  merging
1210                           time  if overwriting policy is based on file's data
1211                           or EA being more recent and last, when comparing an
1212                           archive  with  a filesystem (-d option). This is to
1213                           workaround some filesystems (like Samba filesystem)
1214                           that  seems to change the dates of files after hav‐
1215                           ing gone from or  to  daylight  saving  time  (win‐
1216                           ter/summer time). Note that -H option has influence
1217                           on the overwriting policy (see -/ option)  only  if
1218                           it  is  found  before  on command-line or in an in‐
1219                           cluded file (using -B option).
1220
1221       -E, --execute <string>
1222                           the string is a user command-line  to  be  launched
1223                           between  slices. For reading an archive (thus using
1224                           -t, -d, -l or -x commands), the given string is ex‐
1225                           ecuted  before the slice is read or even asked, for
1226                           writing an archive instead (thus using -c, -C or -+
1227                           commands),  the  given  string is executed once the
1228                           slice has been completed. Some substitution  macros
1229                           can be used in the string:
1230
1231                           %%        will be replaced by %
1232
1233                           %p        will be replaced by the slice path
1234
1235                           %b        will be replaced by the slice basename
1236
1237                           %n        will  be replaced by the slice number (to
1238                                     be read or just  written).  For  reading,
1239                                     dar  often needs the last slice, but ini‐
1240                                     tially it does not know its number. If it
1241                                     cannot be found in the current directory,
1242                                     the user command-line is then called with
1243                                     %n  equal  to 0. This is a convenient way
1244                                     to inform the user command to provide the
1245                                     last slice. If after executing the string
1246                                     the requested slice is still not present,
1247                                     dar  asks  the  user  (as usually) with a
1248                                     message on the terminal.  Once  the  last
1249                                     slice  is found, the user command-line is
1250                                     called a second time, with  %n  equal  to
1251                                     the value of the last slice number.
1252
1253                           %N        is the slice number with the leading zero
1254                                     as defined  by  --min-digits  option.  If
1255                                     this option is not used, %N is equivalent
1256                                     to %n.
1257
1258                           %e        will be replaced by the  slice  extension
1259                                     (always substituted by "dar")
1260
1261                           %c        will be replaced by the context. Actually
1262                                     three possible values exist: "init", "op‐
1263                                     eration"  and  "last_slice". When reading
1264                                     an  archive  for  (testing,   extraction,
1265                                     diff,  listing,  or while reading the ar‐
1266                                     chive of reference, see below the -F  op‐
1267                                     tion),  the  "init"  context  takes place
1268                                     from the beginning up  to  the  time  the
1269                                     catalogue  is  retrieved.  On  a multiple
1270                                     slice archive this correspond to the last
1271                                     slice  request.  After,  that point comes
1272                                     the "operation" context.  While  creating
1273                                     an archive, the context is always "opera‐
1274                                     tion" except when the last slice has been
1275                                     created, in which case the context is set
1276                                     to "last_slice".
1277
1278                           %u        will be replaced by the full URL of  path
1279                                     where the slice is stored
1280
1281                           Several -E option can be given, given commands will
1282                           then be called in the order they appear on the com‐
1283                           mand  line  and -B included files. Note that having
1284                           '-E script1 -E script2' is  totally  equivalent  to
1285                           '-E "script1 ; script2"'. In other words if script1
1286                           fails, script2 fill still be executed and dar  will
1287                           only  be notified of the exit status of the last -E
1288                           option. Exit status of previous -E  given  commands
1289                           will  be ignored. If this does not match your need,
1290                           consider using a single -aduc option  (see  below).
1291                           More  generally  you can use any shell construction
1292                           in the argument to -E,  including  parenthesis,  ||
1293                           and  &&. Such files given to -E option are known as
1294                           DUC files (Dar User Command). See also the environ‐
1295                           ment  variable DAR_DUC_PATH in the ENVIRONMENT sec‐
1296                           tion at the end of this document.
1297
1298       -aduc, --alter=duc  As described above for -E option, several  -E/-F/-~
1299                           options  (aka  DUC commands) are combined using the
1300                           shell ";" operator, which ignores the  exit  status
1301                           of  the  first commands and only reports to dar the
1302                           exit status of the last command, leading  all  com‐
1303                           mands  to always being executed. --aduc option com‐
1304                           bines the different DUC commands  using  the  shell
1305                           "&&"  operator,  which  execute the next command if
1306                           and only if  the  previous  command  succeeded.  In
1307                           other  words,  dar  get notified of an error in any
1308                           given DUC command but due to an error not  all  DUC
1309                           commands may be executed.
1310
1311       --aduc  modifies  the  way the next DUC file is sticked to the previous
1312       command, in other words:
1313
1314              dar --aduc -E script1 -E script2 ...
1315                   leads libdar to  call  a  shell  with  the  following  line
1316                   "script1 && script2"
1317
1318              dar -E script1 -script2 --aduc -E script3 ...
1319                   leads  libdar  to  call  a  shell  with  the following line
1320                   "script1 ; script2 && script3". In other words if you  want
1321                   to avoid the ";" use --aduc before any -E/-F/-~ option.
1322
1323       -F, --ref-execute <string>
1324                           same  as  -E  but  is applied between slices of the
1325                           reference archive (-A option). --execute-ref  is  a
1326                           synonym.
1327
1328       -~, --aux-execute <string>
1329                           same  as -E and -F but is applied between slices of
1330                           the auxiliary archive (-@ option).
1331
1332       -K, --key [[<algo>]:]<string>
1333
1334       -K, --key gnupg:[<algo>]:keyid/email[,keyid/email[...]]
1335                           In the first syntax,  encrypt/decrypt  the  archive
1336                           using  the  <algo> cipher with the <string> as pass
1337                           phrase. An encrypted archive can only  be  read  if
1338                           the  same  pass  phrase is given (symmetric encryp‐
1339                           tion).  Available  ciphers  are  "blowfish"  (alias
1340                           "bf"),  "aes",  "twofish", "serpent" and "camellia"
1341                           for  strong  encryption  and  "scrambling"   (alias
1342                           "scram")  for a very weak encryption. By default if
1343                           no <algo> or no ':' is given, the aes256 cipher  is
1344                           assumed (default was blowfish up to 2.5.x). If your
1345                           password contains a colon ':' you need  to  specify
1346                           the  cipher to use (or at least use the initial ':'
1347                           which is equivalent to 'bf:'). If the  <string>  is
1348                           empty  the  pass  phrase will be asked at execution
1349                           time. Thus, the smallest argument that -K  can  re‐
1350                           ceive  is  ':'  which  means aes256 cipher with the
1351                           pass phrase asked at execution time.
1352
1353                           Note that giving the passphrase as argument  to  -K
1354                           (or -J or '-$' see below) may let other users learn
1355                           pass phrase (thanks to the ps, or top  program  for
1356                           examples).  It  is thus wise to either use an empty
1357                           pass which will make dar ask the pass  phrase  when
1358                           needed, or use -K (or -J option) from a Dar Command
1359                           File (see -B option), assuming it has the appropri‐
1360                           ated  permission  to  avoid other users reading it.
1361                           For those paranoids that are really concerned about
1362                           security of their passwords, having a password read
1363                           from a DCF is not that secure,  because  while  the
1364                           file gets parsed, dar makes use of "unsecured" mem‐
1365                           ory (memory than can be swapped to disk under heavy
1366                           memory  load  conditions).  It  is  only  when  the
1367                           passphrase has been identified that  locked  memory
1368                           (aka  secure  memory)  is  used to store the parsed
1369                           passphrase. So, the most secure way to  transmit  a
1370                           passphrase   to   dar,  then  to  libdar,  then  to
1371                           libgcrypt, is having dar asking passphrase at  exe‐
1372                           cution time, dar then makes use of secured (locked)
1373                           memory from the beginning.
1374
1375                           since archive format 9 (archive  generated  by  re‐
1376                           lease  2.5.0  and following) at reading time, it is
1377                           not necessary to provide the  encryption  algorithm
1378                           used,  just  the  passphrase  is required, dar will
1379                           figure out which encryption algorithm had been used
1380                           at archive creation time. You can either omit -K in
1381                           which case dar will ask for the passphrase at  exe‐
1382                           cution  time,  or  you can use -K <string> in a DCF
1383                           file as explained above (avoid using -K directly on
1384                           command-line).
1385
1386                           The second syntax starts with the word "gnupg" fol‐
1387                           lowed by a colon ':' . In that situation, the  same
1388                           set or symmetric encryption algorithms as described
1389                           above  is  available  after  the  colon,  but   the
1390                           passphrase  is  not  given by the user but randomly
1391                           chosen by libdar and encrypted using the public key
1392                           of  the  target  users  which  email okkeyid (since
1393                           2.7.0) is given in a  comma  separated  list.  This
1394                           random  key (see also --key-length below), once en‐
1395                           crypted is placed at the beginning and at  the  end
1396                           of  the generated archive. At reading time only the
1397                           listed user will  be  able  to  read  that  archive
1398                           thanks  to  their respective private key. This fea‐
1399                           ture implies that each user (the archive creator as
1400                           well  as the target users) have their GnuPG keyring
1401                           set properly. In particular,  the  archive  creator
1402                           must  have  validated the public keys of the target
1403                           users, and the target users  must  own  the  corre‐
1404                           sponding private key in their keyring. Example: us‐
1405                           ing     "--key     gnupg::bob@nowhere.org,joe@some‐
1406                           where.com"  will  generate  an aes256 encrypted ar‐
1407                           chive which passprhase randomly  chosen  by  libdar
1408                           will   be   encrypted   with  the  public  keys  of
1409                           bob@nowhere.org and joe@somewhere.com. To use blow‐
1410                           fish  in  place  of  ars256  one  could  use "--key
1411                           gnupg:bf:bob@nowhere.org,joe@somewhere.com".   Note
1412                           that  no check is done about the trust you have set
1413                           in GPG keyring that  a  particular  public  key  is
1414                           owned  by  the  phyical person you expect. See also
1415                           --sign option below.
1416
1417                           Note that if you have set a passphrase on your pri‐
1418                           vate  key,  dar  will ask it dynamically, which re‐
1419                           quires dar to be run from a terminal. No other  way
1420                           has  been  provided  to  transmit  a  private key's
1421                           passphrase to libdar. In consequence if you want to
1422                           use  dar/libdar  in  scripts and make use of public
1423                           key algorithm you should avoid setting a passphrase
1424                           to  the  private  key  you  want  to  use. See also
1425                           GNUPGHOME in the ENVIRONMENT section at the end  of
1426                           this document.
1427
1428                           Obvious  but  important!  To read a gnupg encrypted
1429                           archive, you need your private key  (not  only  the
1430                           passphrase  to  activate  it,  if set). Thus if you
1431                           plan to make backup of your system and encrypt  the
1432                           backup  using gnupg, you should have a copy of this
1433                           private key available out of the archive (usb  key,
1434                           floppy, CD/DVD, ...) in order to be able to restore
1435                           your backup!
1436
1437       -J, --ref-key [[<algo>]:]<string>
1438                           same meaning/use as -K option's first  syntax,  but
1439                           the  given  key  is  used to decrypt the archive of
1440                           reference (given with -A option).  --key-ref  is  a
1441                           synonym. Note that for archives generated using dar
1442                           release 2.5.0 and above this option is no more nec‐
1443                           essary,  unless  you want to give the passphrase on
1444                           command-line  (not  recommended)  or  in  DCF  file
1445                           (which  file  would  be  set with restricted access
1446                           permissions and/or ACL).
1447
1448       -$, --aux-key [[<algo>]:]<string>
1449                           same as -J but for the auxiliary archive of  refer‐
1450                           ence  (given with -@ option). Here too, this option
1451                           is no more necessary to read archives generated  by
1452                           dar release 2.5.0 and above.
1453
1454       -#, --crypto-block <size>
1455                           to  be  able to randomly access data in an archive,
1456                           it is not encrypted globally but  block  by  block.
1457                           You  can define the encryption block size thanks to
1458                           this argument which default to  10240  bytes.  Note
1459                           that  the  syntax used for -s option is also avail‐
1460                           able here (k, M, G, etc.). Note also  that  crypto-
1461                           block  is  stored  as  a 32 bits integer thus value
1462                           larger than 4GB will cause  an  error.  Note  last,
1463                           that  the  block  size  given here must be provided
1464                           when reading this resulting archive, using  the  -*
1465                           option  if  the archive is the archive of reference
1466                           (given to -A option) using -% options  if  the  ar‐
1467                           chive  is the auxiliary archive of reference (given
1468                           to -@ option) or using this -# option if it is  the
1469                           subject of the operation (listing, comparing, test‐
1470                           ing that archive). If the value is not the  default
1471                           and the given value is not correct in regard to the
1472                           value given at archive creation time,  the  archive
1473                           will  not  be possible to decrypt, it is thus safer
1474                           to keep the default value (and not using at all the
1475                           -#, -*, -% options).
1476
1477       -*, --ref-crypto-block <size>
1478                           same  as  --crypto-block but to read the archive of
1479                           reference (-A option). --crypto-block-ref is a syn‐
1480                           onym.
1481
1482       -%, --aux-crypto-block <size>
1483                           same  as  --crypto-block  but to read the auxiliary
1484                           archive of reference (-@ option).
1485
1486       -e, --dry-run       Do not perform any action (backup,  restoration  or
1487                           merging),  displays  all  messages as if it was for
1488                           real ("dry run" action). The --empty  option  is  a
1489                           synonym.
1490
1491       -aSI, --alter=SI[-unit[s]]
1492                           when using k M G T E Z Y prefixes to define a size,
1493                           use the SI meaning: multiple of  10^3  (a  Mega  is
1494                           1,000,000).
1495
1496       -abinary, --alter=binary[-unit[s]]
1497                           when using k M G T E Z Y prefixes to define a size,
1498                           use the historical computer science meaning: multi‐
1499                           ple of 2^10  (a Mega is 1,048,576).
1500
1501                           The  --alter=SI  and  --alter=binary options can be
1502                           used several times on the command line. They affect
1503                           all  prefixes  which  follow,  even  those found in
1504                           files included by the -B option,  up  to  the  next
1505                           --alter=binary  or --alter=SI occurrence. Note that
1506                           if in a file included by the -B  option,  an  --al‐
1507                           ter=binary or --alter=SI is encountered, it affects
1508                           all the following prefixes, even those outside  the
1509                           included  files. For example, when running with the
1510                           parameters "-B some.dcf -s 1K", 1K may be equal  to
1511                           1000  or 1024, depending on --alter=binary or --al‐
1512                           ter=SI being present in the some.dcf file.  By  de‐
1513                           fault   (before  any  --alter=SI/binary  option  is
1514                           reached),  binary  interpretation  of  prefixes  is
1515                           done, for compatibility with older versions.
1516
1517       -ac, --alter=ctime  When  reading a filesystem (during a backup or com‐
1518                           parison), restores the atime of all files  to  what
1519                           it  was before the file was read. This makes it ap‐
1520                           pear as if it had not been read  at  all.  However,
1521                           because there is no system call to let applications
1522                           changing the ctime (last inode change) of  a  file,
1523                           setting  back  the atime results in the ctime being
1524                           changed (hence the alter=ctime). Some  recent  unix
1525                           system  allow  an  application to get 'furtive read
1526                           mode' to the filesystem (see below). On older  sys‐
1527                           tems, however, for most users, having the atimes of
1528                           the files changed shouldn't  be  a  problem,  since
1529                           they  can  be changed by any other program (running
1530                           by any user!) as well (like the content-index  pro‐
1531                           gram  Beagle).  Ctimes  on  the other hand, are the
1532                           only way for security software to detect  if  files
1533                           on  your  system  have  been replaced (by so called
1534                           root-kits mostly). This means, that should you  run
1535                           dar  with  -ac, security software which uses ctimes
1536                           to check, will mark every file on  your  system  as
1537                           compromised  after the backup. In short, this means
1538                           this option should only be used by people who  know
1539                           what  they  are  doing.  It's  the  opinion of this
1540                           writer  that  any  software  susceptible  to  atime
1541                           changes  is  flaky  or  even broken (because of the
1542                           afore mentioned reasons  why  atimes  can  change).
1543                           But, that doesn't take away that there are programs
1544                           who rely on atimes remaining the same, like  Leafn‐
1545                           ode  NNTP  caching  software. Therefore this option
1546                           exists.
1547
1548       -aa, --alter=atime  When specifying -aa (by  opposition  to  -ac),  the
1549                           atime  of every read file and directory is updated,
1550                           and the ctime remains the same. In other words, Dar
1551                           itself does nothing with atimes and ctimes, it only
1552                           let the system do its job  to  update  atimes  when
1553                           files  are  accessed for reading. This is in accor‐
1554                           dance with what atimes and  ctimes  were  meant  to
1555                           represent.  This  is  Dar's  default (since version
1556                           2.4.0), unless 'furtive read mode' (see  below)  is
1557                           supported  by your system and dar has been compiled
1558                           with this support activated.
1559
1560       Furtive read mode is a mode in which neither atime nor ctime are  modi‐
1561       fied while dar reads each file and directory. This provides also better
1562       performances as nothing has to be wrote back to disk. A known Unix ker‐
1563       nel  that  supports this feature is Linux 2.6.8 and above (support must
1564       also be present in the standard C library of the system for dar  to  be
1565       able  to activate this feature at compilation time).  When this feature
1566       is activated, it becomes the default behavior of dar for super  user  ;
1567       for other users the default is -aa. If however as root user, you do not
1568       want to use "furtive read mode" (while it has been activated at  compi‐
1569       lation time), you can specify either -aa or -ac option.
1570
1571       -at, --alter=tape-marks
1572                           For  archive  creation and merging, the default be‐
1573                           havior (since release 2.4.0) is to add  escape  se‐
1574                           quences (aka tape marks) followed by inode informa‐
1575                           tion all along the archive. If -at  is  given,  dar
1576                           will  not  add this information to the archive, re‐
1577                           sulting in a slightly smaller  archive  and  faster
1578                           backup. When reading an archive, the default behav‐
1579                           ior is to ignore these escape sequences and  rather
1580                           rely on the catalogue located at the end of the ar‐
1581                           chive. If instead  --sequential-read  is  given  on
1582                           command-line  (see below), dar will avoid using the
1583                           catalogue at the end of the archive and  will  rely
1584                           on  these  escape sequences to know the contents of
1585                           the archive, which will lead to a sequential  read‐
1586                           ing of the archive, operation suitable for tape me‐
1587                           dia. Note that it is not recommended to disable es‐
1588                           cape sequences (aka tape marks) by using -at option
1589                           except if you are more concerned by  the  resulting
1590                           size and execution speed of your backup (in partic‐
1591                           ular if you have a lot of small files) than by  the
1592                           possibility  to  recover  your data in case of cor‐
1593                           rupted or partially written archive.   Without  es‐
1594                           cape  sequences,  dar cannot sequential read an ar‐
1595                           chive, which is the only way beside using  an  iso‐
1596                           lated  catalogue  to use an archive that has a cor‐
1597                           rupted catalogue or has no catalogue at all,  thing
1598                           that  happens if a system crash occurred during the
1599                           archive creation or due to lack of  disk  space  to
1600                           complete the archive.
1601
1602       -0, --sequential-read
1603                           Change  dar's  behavior when reading an archive. By
1604                           default, the traditional way is used, which  relies
1605                           on  the table of contents (aka "the catalogue") lo‐
1606                           cated at the end of the archive. With the --sequen‐
1607                           tial-read  option  instead, dar will rely on escape
1608                           sequences that are inserted all along  the  archive
1609                           with  each file's inode information. This will lead
1610                           to a sequential reading of the  archive,  operation
1611                           suitable  for tape medium. However, this feature is
1612                           only available for archive format starting revision
1613                           "08"  (i.e.: since release 2.4.0) and if -at option
1614                           has no been used during archive creation  or  merg‐
1615                           ing.  This  option is available for archive testing
1616                           (-t), comparison (-d),  restoration  (-x),  listing
1617                           (-l)  and  to read the archive of reference (-A op‐
1618                           tion) for isolation (-C) and archive creation (-c).
1619                           The sequential reading of an archive is always much
1620                           slower than the usual reading method, so you should
1621                           not use this option unless you really need it.
1622
1623       -9, --min-digits <num>[,<num ref>[,<num aux>]]
1624                           By  default  slice  number contained in filename do
1625                           not have any padded zeros, which,  when  sorting  a
1626                           directory contents alphabetically leads to read all
1627                           the slices starting by '1', then by '2'. for  exam‐
1628                           ple,  slice  1,  10, 11, 12, 13, ... 2, 20, 21, 23,
1629                           ... etc. While dar is absolutely not  perturbed  by
1630                           this  display problem, some user shall like to have
1631                           the slices sorted by order. For  that  reason,  the
1632                           --min-digits  option  lets  you  ask dar to prepend
1633                           enough zeros in the slice number for it be as  wide
1634                           as  the  argument passed to --min-digits. For exam‐
1635                           ple, if you provide 3 for  that  number,  dar  will
1636                           store  the  slice number as 001, 002, 003, ... 999.
1637                           Well, next slice will be 1000, thus it  will  break
1638                           again  the alphabetical sorting order. You are thus
1639                           advised to use a number large enough to convert the
1640                           number  of  slice you expect to use. Before release
1641                           2.7.0, when reading an archive, you were  also  re‐
1642                           quested  to provide this same argument else dar was
1643                           unable finding the slice. Since 2.7.0 dar  auto-de‐
1644                           tects the mi-digits value to use, unless there is a
1645                           mix of archive of the same basename with  different
1646                           min-digits.  In  such conflicting context, you must
1647                           bypass the min-digits auto-detection mechanism  and
1648                           specify  which  min-digits value to retain in order
1649                           to read the archive, eventually followed by a comma
1650                           and the number of digits to use to read the archive
1651                           of reference (given to -A option), eventually  fol‐
1652                           lowed  by  a  comma and the number of digits to use
1653                           for the auxiliary archive of reference (given to -@
1654                           option).
1655
1656       --pipe-fd <num>     will  read further arguments from the file-descrip‐
1657                           tor <num>. The arguments read through this file-de‐
1658                           scriptor must follow a TLV (Type/Length/Value) list
1659                           format. This option is not intended for human  use,
1660                           but  for other programs launching dar like dar_man‐
1661                           ager. This feature has been added to  overcome  the
1662                           command line length limit.
1663
1664       -al, --alter=lax    When reading an archive, dar will try to workaround
1665                           data corruption of slice header, archive header and
1666                           catalogue. This option is to be used as last resort
1667                           solution when facing media corruption. It is rather
1668                           and  still  strongly encourage to test archives be‐
1669                           fore relying on them as well as using  Parchive  to
1670                           do  parity data of each slice to be able to recover
1671                           data corruption in a much more effective manner and
1672                           with  much more chance of success. Dar also has the
1673                           possibility to backup a catalogue using an isolated
1674                           catalogue, but this does not face slice header cor‐
1675                           ruption or even saved file's data  corruption  (dar
1676                           will detect but will not correct such event).
1677
1678       -G, --multi-thread { <num> | <crypto>,<compression> }
1679                           When libdar is compiled against libthreadar, it can
1680                           make use of several threads. If the argument is two
1681                           numbers  separated by a comma the first defines the
1682                           number of worker threads  to  cipher/decipher,  the
1683                           second  the  number  of  threads to compress/decom‐
1684                           press. If the argument is a single number (-G  <n>)
1685                           it  is equivalent to giving this number as the num‐
1686                           ber of compression threads and giving 2 for the ci‐
1687                           phering  threads  (-G  2,<n>).  The  use  of multi-
1688                           threading at archive creation time leads to rely on
1689                           per   block  compression  rather  than  the  legacy
1690                           streaming compression and if the block-size is  not
1691                           specified  (see  -z option for details) it defaults
1692                           to 240 KiB. Not providing any -G option, is equiva‐
1693                           lent to providing -G 2,1 when libthreadar is avail‐
1694                           able else -G 1,1. Note that if an archive has  been
1695                           created  with streaming compression, the decompres‐
1696                           sion cannot use multi-threads, the deciphering  can
1697                           always use multiple threads.
1698
1699       -j, --network-retry-delay <seconds>
1700                           When a temporary network error occurs (lack of con‐
1701                           nectivity, server unavailable, and so on), dar does
1702                           not  give  up,  it waits some time then retries the
1703                           failed  operation.  This  option  is  available  to
1704                           change  the  default retry time which is 3 seconds.
1705                           If set to zero, libdar will not wait but rather ask
1706                           the  user whether to retry or abort in case of net‐
1707                           work error.
1708
1709       -afile-auth, --alter=file-authentication
1710                           With this option, When reading or  writing  an  ar‐
1711                           chive  to  a  remote repository when no password is
1712                           provided, instead of  interactively  asking  for  a
1713                           password dar will first check the ~/.netrc file for
1714                           credentials when relying on FTP protocol  and  also
1715                           for  SFTP  protocol  (libcurl allows that, which is
1716                           unusual but somehow useful). If no  password  could
1717                           be  found  in ~/.netrc, in second time and for SFTP
1718                           only, dar will try to connect using public key  au‐
1719                           thentication.  Public  key  authentication is tried
1720                           without this option, but it is useful here to avoid
1721                           having password requested interactively.
1722
1723       -ab, --alter=blind-to-signatures
1724                           do not check whether an encrypted archive with pub‐
1725                           lic key that has also been signed have correct sig‐
1726                           natures.
1727
1728       SAVING,  ISOLATION, MERGING AND REPAIRING SPECIFIC OPTIONS (to use with
1729       -c, -C or -+)
1730
1731       -z, --compression={ [algo] | level | algo:level | algo:level:block-size
1732       }
1733            add compression within slices. If -z is not specified, no compres‐
1734            sion is performed, but if -z is specified without  algorithm  gzip
1735            will be assumed.
1736
1737            algo:
1738                 the  following  values  are available "gzip", "bzip2", "lzo",
1739                 "xz", "zstd" or "lz4".
1740
1741            level:
1742                 The compression level (an integer from 1 to 9 except for zstd
1743                 which  ranges from 1 to 22) is optional, and is 9 by default.
1744                 Be careful when using xz algorithm better specify a  compres‐
1745                 sion  ratio less than or equal to 6 to avoid important memory
1746                 requirements. A ratio of 1 means less compression and  faster
1747                 processing, while at the opposite a ratio of 9 gives the best
1748                 compression but longest processing time.
1749
1750            block-size:
1751                 if set to zero (which is also the default  value),  you  will
1752                 get  the legacy (and performant) "streaming compression" mode
1753                 that was the only available up to release 2.7.0. Since  then,
1754                 the  "block  compression"  mode gives the ability to leverage
1755                 multi-threading (see -G option) by compressing per block  and
1756                 giving  different blocks to different threads. The larger the
1757                 block is, the better the compression ratio will be (it  tends
1758                 to  be  as good as the one of the streaming compression mode,
1759                 when block size increases), but files smaller  than  a  block
1760                 size can only be processed by a single thread. The memory re‐
1761                 quirement also increases by the product  of  the  block  size
1762                 times  the  number  of  threads. Last, a too small block-size
1763                 will cost more CPU  cycles  (the  multi-threading  management
1764                 overhead will become important compared to the effective com‐
1765                 pression processing) and independently,  short  blocks  gives
1766                 poor  compression  rates. It is thus advised to use values at
1767                 least greater than 50 ~ 100 KiB (you can  use  the  k,M,G,...
1768                 suffixes  described  for the -s option). If the block-size is
1769                 not specified and given -G option leads to a number  of  com‐
1770                 pression  threads  greater or equal to 2, a block-size of 240
1771                 KiB is used. If you want the legacy streaming compression, do
1772                 not  use  -G  option (or use it specifying only 1 compression
1773                 thread) and do not set the compression block size (or set  it
1774                 to zero).
1775
1776            Valid  usage  of -z option is for example: -z, -z9, -zlzo, -zgzip,
1777            -zbzip2,  -zlzo:6,   -zbzip2:2,   -zgzip:1,   -zxz:6,   -zlz4::10k
1778            -z::12000  -zbzip2:8:10k  and  so on. Usage for long option is the
1779            same: --compression,  --compression=9,  --compression=lzo,  --com‐
1780            pression=gzip,  --compression=bzip2,  --compression=lzo:6,  --com‐
1781            pression=bzip2:2, --compression=gzip:1 --compression=xz:9  and  so
1782            on.
1783
1784            About lzo compression, the compression levels of dar and lzop pro‐
1785            gram do not match. If you want to get the behavior of  compression
1786            level  1  of  lzop,  use the lzop-1 algorithm in place of lzo with
1787            dar/libdar. If you want to get the behavior  of  lzop  compression
1788            level  3,  use the lzop-3 algorithm in place of the lzo algorithm.
1789            Lzop compression levels 2, 4, 5 and 6 are the  same  as  level  3.
1790            last,  there  is  no difference about compression level 7, 8 and 9
1791            between dar and lzop. The lzop-1 and lzop-3 algorithms do not make
1792            use  of  any  compression level (compression level is ignored with
1793            these algorithms).
1794
1795       -s, --slice <number>
1796                           Size of the slices in bytes. If the number  is  ap‐
1797                           pended  by k (or K), M, G, T, P, E, Z or Y the size
1798                           is in kilobytes, megabytes,  gigabytes,  terabytes,
1799                           petabytes,  exabytes,  zettabytes or yottabytes re‐
1800                           spectively. Example: "20M" means 20  megabytes,  by
1801                           default, it is the same as giving 20971520 as argu‐
1802                           ment (see also -aSI and -abinary options). If -s is
1803                           not  present the backup will be written to a single
1804                           slice whatever the size of the backup may  be  (as‐
1805                           suming  your operating system can support arbitrar‐
1806                           ily large files).
1807
1808       -S, --first-slice <number>
1809                           -S gives the size of the first slice which  may  be
1810                           chosen  independently  of  the  size  of  following
1811                           slices (either  bigger  or  smaller).  This  option
1812                           needs  -s  option  and by default of -S option, the
1813                           size of the first slice is the same as the  one  of
1814                           the following slices.
1815
1816       -p [<integer>], --pause[=<integer>]
1817                           pauses before writing to a new slice (this requires
1818                           -s). By default there is no pause, all  slices  are
1819                           written in the same directory, up to the end of the
1820                           backup or until the filesystem  is  full.  In  this
1821                           later  case,  the  user  is informed of the lack of
1822                           disk space and dar stops for user action.  As  soon
1823                           as  some disk space is available, the user can con‐
1824                           tinue the backup. The optional  integer  that  this
1825                           option  can  receive  tells dar to only pause every
1826                           'n' slice. Giving 3 for 'n'  will  make  dar  pause
1827                           only  after slices 3, 6, 9 and so on. If this inte‐
1828                           ger is not specified, the behavior is as if '1' was
1829                           given  as argument which makes dar pause after each
1830                           slice.
1831
1832       -D, --empty-dir     At backup time only, when excluding directories ei‐
1833                           ther  explicitly using -P or -] options, or implic‐
1834                           itly by giving a -g or -[ options (a  directory  is
1835                           excluded  if  it  does not match mask given with -g
1836                           options or -[ options) dar does not store  anything
1837                           about these. But with -D option, dar stores them as
1838                           empty directories. This can be useful, if excluding
1839                           a mount point (like /proc or /dev/pts). At restora‐
1840                           tion time, dar will then recreate these directories
1841                           (if  necessary). This option has no meaning with -C
1842                           and is ignored in that case. Independently of that,
1843                           -D can also be used at restoration time, but it ac‐
1844                           tivates a slightly different feature (see  RESTORA‐
1845                           TION SPECIFIC OPTIONS below).
1846
1847       -Z, --exclude-compression <mask>
1848                           Filenames  covered by this mask are not compressed.
1849                           It is only useful in conjunction with -z option. By
1850                           default,  all  files are compressed (if compression
1851                           is used). This option can be used several times, in
1852                           that  case  a  file that matches one of the -Z mask
1853                           will not be compressed. Argument given to  -Z  must
1854                           not be include any path, just the filename (eventu‐
1855                           ally/probably using wildcards).  This  option  used
1856                           while  merging or repairing allow one to change the
1857                           compression of files.
1858
1859       -Y, --include-compression <mask>
1860                           Filenames covered by this  mask  (and  not  covered
1861                           masks  given  to  -Z  option(s)) are the only to be
1862                           compressed. It is only available with -z option. By
1863                           default  all  files are compressed. This option can
1864                           be used several times, in that case all files  that
1865                           match  one of the -Y will be compressed, if they do
1866                           not also match on of  the  -Z  masks.  The  ordered
1867                           method  here  applies  too when activated (with -am
1868                           option), it works exactly the same as -I and -X op‐
1869                           tions,  but apply to file compression, not file se‐
1870                           lection. In other word, it matches only on the file
1871                           name,  not  on  the path of files. This option used
1872                           while merging or repairing allow one to change  the
1873                           compression of files.
1874
1875       -m, --mincompr <number>
1876                           files  which  size  is below this value will not be
1877                           compressed. If -m is not specified it is equivalent
1878                           to  giving  -m 100 as argument. If you want to com‐
1879                           press all files whatever their  size  is  you  thus
1880                           need  to  type  -m  0 on the command line. The size
1881                           unit is the byte (octet) and the same number exten‐
1882                           sions  as  those  used  with -s or -S are available
1883                           here, if you want to specify the size in  kilobyte,
1884                           megabyte, gigabyte etc.
1885
1886       -1, --sparse-file-min-size <number>
1887                           Define  the  minimum  length of zeroed bytes to re‐
1888                           place by "holes". By default, this feature is acti‐
1889                           vated  with a value of 15 bytes. To completely dis‐
1890                           able it, set the size to zero. Disabling this  fea‐
1891                           ture  will  bring some noticeable speed improvement
1892                           but will probably make the archive slightly  bigger
1893                           (depending on the nature of the data). Sparse files
1894                           are files  that  contain  so  called  holes.  On  a
1895                           filesystem,  the  portion  of  zeroed  bytes is not
1896                           stored on disk, thus an arbitrary large  file  with
1897                           huge  portion of zeros may only require a few bytes
1898                           of disk storage. While dar cannot detect how is al‐
1899                           located  a given file because it makes a filesystem
1900                           abstraction (it does not know the implementation of
1901                           any particular filesystem, where from its portabil‐
1902                           ity), when it finds  a  sequence  of  zeroed  bytes
1903                           larger  than the given threshold it can assume that
1904                           it is in presence of a hole. Doing so, it does  not
1905                           store  the given zeroed bytes into the archive, but
1906                           place a tag beside the saved  data  to  record  the
1907                           size  of  the hole and thus where to place the next
1908                           non zeroed bytes. This makes dar archive disk space
1909                           requirement  much  smaller  when  a sparse files is
1910                           met. At restoration time, dar  will  restore  holes
1911                           writing  normal  data  and seeking over the hole to
1912                           write down the normal data after each hole. If  the
1913                           underlying  file system supports sparse files, this
1914                           will restore the holes. Note that there is no  dif‐
1915                           ference  for  applications whether a file is sparse
1916                           or not, thus dar may well  transform  normal  files
1917                           into sparse files and vice-versa, only the disk re‐
1918                           quirement will change. Last point, if dar  can  re‐
1919                           duce  disk  requirement  for  archive with holes as
1920                           small as 15 bytes  (smaller  value  works  but  the
1921                           overhead  cost  more than what is required to store
1922                           the zeroed bytes normally), it may not be the  same
1923                           at  restoration, because filesystem allocation unit
1924                           is usually several kilobytes (a page), however  re‐
1925                           stored  file  will never be larger than it could be
1926                           without holes. The only drawback of this feature is
1927                           the additional CPU cycle it requires.
1928
1929       -ak, --alter=keep-compressed
1930                           During  merging and repairing operation, keep files
1931                           compressed, this has several restrictions : -z, -Z,
1932                           -Y,  -m  are  ignored,  if  two archives have to be
1933                           merged, both must use the  same  compression  algo‐
1934                           rithm  or  one  of them must not use compression at
1935                           all (this last restriction will probably  disappear
1936                           in a next version). The advantage of this option is
1937                           a greater speed of execution (compression  is  usu‐
1938                           ally CPU intensive).
1939
1940       -ah, --alter=holes-recheck
1941                           For  merging  and repairing, the sparse file detec‐
1942                           tion mechanism is disabled by default.  However  if
1943                           you  want  to activate it (assuming you have an old
1944                           archive you want to  convert  the  current  archive
1945                           format  taking  care  of sparse files), you need to
1946                           use -ah option to reactivate the sparse file detec‐
1947                           tion  mechanism.  Then  for  merging  and repairing
1948                           --sparse-file-min-size can  be  used  as  described
1949                           above  for  archive  creation. In addition, you can
1950                           have files stored as sparse file in the archive  of
1951                           reference  be  stored as normal files in the merged
1952                           archive using -ah and passing to --sparse-file-min-
1953                           size an value larger than all file sizes, for exam‐
1954                           ple as of today in year 2018, passing -ah --sparse-
1955                           file-min-size  1E  (1E  for  one exabyte) should be
1956                           large enough.
1957
1958       --nodump            do not save files which have the 'd' flag set  (see
1959                           chattr(1) lsattr(1) ext2 commands). This option may
1960                           not be available if the system dar  has  been  com‐
1961                           piled  on  did  not provide support for ext2 flags.
1962                           Note that this option does nothing with  -+  option
1963                           (merging)  as no filesystem is used for that opera‐
1964                           tion.
1965
1966       -5, --exclude-by-ea[=<extended attribute name>]
1967                           exclude inodes from backup that have been set  with
1968                           the  EA given in argument. If not argument is given
1969                           to that option the default EA used to exclude files
1970                           from backup is "user.libdar_no_backup". To set this
1971                           attribute to a given file, use the  following  com‐
1972                           mand:  "setfattr  -n  user.libdar_no_backup  <file‐
1973                           name>",  to  remove  it:  "setfattr  -x   user.lib‐
1974                           dar_no_backup <filename>". Last, to check the pres‐
1975                           ence this EA: "getfattr <filename>"
1976
1977       -M, --mount-points={ I:<path to fs> | X:<path to fs> }
1978                           If the argument is of the I:<path to fs> form,  the
1979                           filesystem  to which this path points to is consid‐
1980                           ered for the backup operation, that's to say, other
1981                           file  filtering  mechanism will be applied and some
1982                           or all files of that filesystem will be  saved  for
1983                           backup. While with the X:<path to fs> form, no file
1984                           in that filesystem  will  even  be  considered  for
1985                           backup.  both X: and I: forms must be provided with
1986                           an absolute path. -M option  can  be  used  several
1987                           times  on  the  command-line.  If only I: forms are
1988                           used, the filesystem based filtering mechanism  be‐
1989                           haves  as a white list (only those listed paths are
1990                           included). If only X: form is used, the  filesystem
1991                           based  filtering  mechanism behaves as a black list
1992                           (everything  is  considered  except  those   listed
1993                           paths).  Last,  while  a mix of I: and X: forms are
1994                           used, filsystems that will be considered for backup
1995                           will  be  those  given with an I: form and not also
1996                           given with an X: form. Note that this is filesystem
1997                           based  filtering,  not path based: If for example a
1998                           filesystem is mounted under /var directory and  you
1999                           specify I:/var/log all /var filesystem will be con‐
2000                           sidered for backup. If you rather want to only save
2001                           what  is  in /var/log use the -P/-g/-X/-I/-[/-] op‐
2002                           tions that realise the file filtering by  name  and
2003                           path+name.  You cannot exclude the filesystem which
2004                           contains the path given to -R option. The use of -M
2005                           option with argument erases any previous configura‐
2006                           tion done with -M option without argument (see  be‐
2007                           low),  and  vice  versa.  By  default (no -M option
2008                           specified), no filtering  based  on  filesystem  is
2009                           performed, in other worlds all files are considered
2010                           for other file filtering mechanism  (in  particular
2011                           -P/-g/-X/-I/-[/-]  options)  and  eventually backed
2012                           up.
2013
2014                           example of use:
2015                           -MI:/var -MX:/var/spool
2016                           --mount-points=I:/var --mount-point=X:/var/spool
2017
2018       -M, --no-mount-points
2019                           This is the legacy form  of  the  option  described
2020                           just above, that existed before release 2.7.0. When
2021                           -M option is provided without argument, only  files
2022                           located  on  the  filesystem pointed to by the path
2023                           given to -R option will be considered  for  backup.
2024                           Subdirectory  that  are  mounting  points for other
2025                           filesystems will not be saved (or saved empty if -D
2026                           option is used). This option is useless and ignored
2027                           for merging operation. The use of -M without option
2028                           lead  dar to ignore any previous -M I:<path> and -M
2029                           X:<path> options that could have been given on com‐
2030                           mand-line or -B included file so far.
2031
2032       -, ,  --cache-directory-tagging
2033                           don't  save  contents  of  directories that use the
2034                           Cache    Directory    Tagging     Standard.     See
2035                           http://www.brynosaurus.com/cachedir/spec.html   for
2036                           details. (this option is useless with -+ option)
2037
2038       -/ , --overwriting-policy <policy>
2039                           This option let the user define when  or  how  file
2040                           overwriting  can  occur  at  restoration or archive
2041                           merging time. It does no apply to slice overwriting
2042                           which  are driven by the -n option, it does instead
2043                           apply to file during extraction  and  files  inside
2044                           archives when merging two of them. When considering
2045                           overwriting, a file is said to be 'in place'  while
2046                           an  other  is  known  as 'new' or 'to be added'. At
2047                           restoration time, the 'in place' is the one that is
2048                           present  in  filesystem  while the 'to be added' is
2049                           the one from the archive. At merging time, the  'in
2050                           place'  is the one of the '-A' archive of reference
2051                           while the 'to be added' is the one from the  auxil‐
2052                           iary  '-@'  archive  or reference. This option does
2053                           not apply to archive repairing.
2054
2055                           As soon as you use -/ option -n only  applies  only
2056                           to slice overwriting and the -r, -k and -ae options
2057                           are ignored (restoration specific options).
2058
2059                           The given <policy> argument is composed of  actions
2060                           and  eventually of conditional expressions. Actions
2061                           do define how to solve overwriting  conflict  about
2062                           file's  data on one side and file's Attributes (Ex‐
2063                           tended and Filesystem Specific) on the other  side.
2064                           An  action  is thus a couple of action for Data and
2065                           for EA+FSA. Actions for Data are represented by up‐
2066                           percase  letters,  while  action for EA+FSA are de‐
2067                           fined by lowercase letters. Both actions are  inde‐
2068                           pendent of each other:
2069
2070                           P    means  'Preserve'.  When merging two archives,
2071                                the data of  the  resulting  archive  will  be
2072                                taken from the 'in place' file. While when ex‐
2073                                tracting, the data of the inode in  filesystem
2074                                will  be  preserved  (thus no overwriting will
2075                                occur for the data).
2076
2077                           O    means 'Overwrite'. When merging two  archives,
2078                                the  data  of  the  resulting  archive will be
2079                                taken from the 'to be added' file. While  when
2080                                extracting,  the data of the inode in filesys‐
2081                                tem will be overwritten by data from  the  ar‐
2082                                chive.
2083
2084                           S    means  'mark Saved and preserve'. When merging
2085                                two archives, the data of  the  resulting  ar‐
2086                                chive  will  be marked as already saved in the
2087                                archive of reference (making thus a  differen‐
2088                                tial archive, even if none of the original ar‐
2089                                chive were differential  archives).  All  data
2090                                will  be dropped in the resulting archive, but
2091                                the last modification date [aka  mtime]  (used
2092                                to detect change in file's data) will be taken
2093                                from the 'in place' file. This action does not
2094                                apply  when  extracting files, it is thus con‐
2095                                sidered equal to "Preserve" (P) in that situa‐
2096                                tion.
2097
2098                           T    means 'mark Saved and overwrite'. When merging
2099                                two archives, the data of  the  resulting  ar‐
2100                                chive will be marked as already saved (same as
2101                                'S' action): all data will be dropped  in  the
2102                                resulting  archive, however the last modifica‐
2103                                tion date [aka mtime] (used to detect  changes
2104                                in  a  file's data) will be taken from the 'to
2105                                be added' file. This  action  does  not  apply
2106                                when  extracting  files, it is thus considered
2107                                equal to "Overwrite" (O) in that situation.
2108
2109                           R    means 'Remove'. When merging two archives, the
2110                                resulting  archive  will not contain any entry
2111                                corresponding to the file that  were  in  con‐
2112                                flict.  This  also  implies that no EA will be
2113                                stored for that particular entry as the  entry
2114                                will  no  more  exist in the resulting archive
2115                                (as if it had never  yet  existed).  When  ex‐
2116                                tracting  files, this will lead to file's sup‐
2117                                pression.
2118
2119                           p    means 'Preserve', same as 'P'  (but  lowercase
2120                                letter)  preserve  the  whole  EA set and FSA.
2121                                When merging two archives, the Attributes  set
2122                                of  the resulting file will be the ones of the
2123                                'in place' file (whatever is  the  overwriting
2124                                action  taken  for  its  data). While when ex‐
2125                                tracting files to filesystem,  the  Attributes
2126                                of  the file in filesystem will not be changed
2127                                (whatever is the overwriting action taken  for
2128                                its data, unless the file is removed using the
2129                                'R' policy, which would remove the  inode  and
2130                                thus also any Attributes it had).
2131
2132                           o    means  'Overwrite', same as 'O' (but lowercase
2133                                letter) overwrite the whole EA  set  and  FSA.
2134                                When  merging two archives, the Attributes set
2135                                of the resulting file will be taken  from  the
2136                                'to  be  added'  file.  While  when extracting
2137                                files, the Attributes set of the file  in  the
2138                                filesystem will have its Attributes erased and
2139                                replaced by those of the file in  the  archive
2140                                (still  independent of what overwriting action
2141                                is taken for file's data).
2142
2143                           s    means 'mark Saved and preserve', same  as  'S'
2144                                (but  lowercase letter) for EA and FSA instead
2145                                of data. When merging two archives, the EA and
2146                                FSA  of  the  resulting file are marked as al‐
2147                                ready saved in the archive of reference,  thus
2148                                they  are  dropped  but the date of last inode
2149                                change [aka ctime] (used to detect changes  in
2150                                file's  EA and FSA) will be taken from the 'in
2151                                place' file. This action does not  apply  when
2152                                extracting files, it is thus considered equiv‐
2153                                alent to "Preserve" (p) in that situation.
2154
2155                           t    means 'mark Saved and overwrite', same as  'T'
2156                                (but  lowercase letter) for EA and FSA instead
2157                                of data. When merging two archives, the EA and
2158                                FSA  of  the  resulting file are marked as al‐
2159                                ready saved in the archive of reference,  thus
2160                                they  are  dropped  but the date of last inode
2161                                change [aka ctime] (use to  track  changes  in
2162                                EA) will be taken from the 'to be added' file.
2163                                This action does  not  apply  when  extracting
2164                                files,  it is thus considered an equivalent to
2165                                "Overwrite" (o) in that situation.
2166
2167                           m    means 'merge Attributes and preserve'. The re‐
2168                                sulting  file  in the merged archive will have
2169                                Attribute entries from both the 'in place' and
2170                                the 'to be added' files. If both files share a
2171                                same Attribute entry (same FSA or for  EA  the
2172                                same  key  for a given association) the one of
2173                                the 'in place' file is kept  (where  from  the
2174                                'preserve'  notion).  When  extracting a file,
2175                                the file in the filesystem will  have  its  EA
2176                                and  FSA  set enriched by the ones of the file
2177                                in the archive that do not exist  on  filesys‐
2178                                tem,  but its already existing Attributes will
2179                                stay untouched.
2180
2181                           n    means 'merge Attributes  and  overwrite'.  The
2182                                resulting file in the merged archive will have
2183                                Attribute entries from both the 'in place' and
2184                                the 'to be added' files. If both files share a
2185                                same Attribute entry (same FSA or for  EA  the
2186                                same  key  for a given association) the one of
2187                                the 'to be added' file  will  be  kept  (where
2188                                from  the 'overwrite' notion). When extracting
2189                                file, the file in the filesystem will have its
2190                                Attributes set enriched by ones of the file in
2191                                the archive with some of  them  possibly  been
2192                                overwritten.
2193
2194                           r    means 'remove', same as 'R' but for the Attri‐
2195                                bute set (thus all EA and FSA  entries)  of  a
2196                                given file ('r' is lowercase letter here). The
2197                                file of the resulting archive  during  merging
2198                                operation  will  not  own  any EA nor any FSA,
2199                                even if the  'in  place'  and/or  the  'to  be
2200                                added'  files  did have some. For file extrac‐
2201                                tion, this means that the file in the filesys‐
2202                                tem  will loose all its EA set. The FSA cannot
2203                                be 'removed' from a filesystem and may not al‐
2204                                ways  have  a  default value, thus this action
2205                                does not modify FSA at all in case of  archive
2206                                extraction. But in case of merging the FSA are
2207                                removed as previously described.  As  for  all
2208                                the  previous  tests, this Attribute operation
2209                                is independent of  the  operation  chosen  for
2210                                file's data (uppercase letters).
2211
2212                           d    means 'delete'. When a same EA or FSA entry is
2213                                found both in the 'in place' and 'to be added'
2214                                files,  such  entry  will be absent in the re‐
2215                                sulting archive. In other words, when merging,
2216                                the  EA  set  and FSA will only contain EA and
2217                                FSA entries specific to  the  'in  place'  and
2218                                those  specific to the 'to be added' file. En‐
2219                                tries in common will not be present. When  ex‐
2220                                tracting  a  file from an archive, the file on
2221                                filesystem will have its EA  set  enriched  by
2222                                entries of the 'to be added' file that are new
2223                                to the 'in place' file. The other  EA  entries
2224                                (which  are  thus  present in both archive and
2225                                filesystem) will  be  removed  from  the  set,
2226                                which  the  other FSA will stay untouched (FSA
2227                                cannot be "removed"  from  a  filesystem,  nor
2228                                they always have a default value).
2229
2230                           *    is  valid  for both EA and data. It tells that
2231                                the action is not yet defined at this step  of
2232                                the  evaluation and that further evaluation is
2233                                required (see the 'chain' operator below).
2234
2235                           A    means 'Ask for user decision'. This  uppercase
2236                                letter  concerns Data overwriting. An applica‐
2237                                tion interaction let the user define  the  ac‐
2238                                tion  for  each  file  in conflict. Note, that
2239                                this action if used alone may become very bor‐
2240                                ing  or painful. The idea is to use it in con‐
2241                                ditional statements (which are  described  be‐
2242                                low)  to  have  dar  ask  for only non obvious
2243                                cases.
2244
2245                           a    means 'Ask for user decision'. This  lowercase
2246                                letter is the equivalent for EA and FSA of the
2247                                'A' action. It is intended to be used  in  the
2248                                same conditional statements described below.
2249
2250                           An  action  is  thus a couple of letters, the first
2251                           being uppercase (for file's data) the second  being
2252                           lowercase  (for  file's EA and FSA). When -/ option
2253                           is not given, the action is equivalent to '-/  Oo',
2254                           making dar proceed to file, EA and FSA overwriting.
2255                           This is to stay as close as possible to the  former
2256                           default action where neither -n nor -w where speci‐
2257                           fied. Note that -w option stays untouched, in  con‐
2258                           sequences, in this default condition for -/ option,
2259                           a confirmation will be asked to the user before dar
2260                           proceed  to  any  overwriting. The former -n option
2261                           (still used to handle slice overwriting) can be re‐
2262                           placed by its equivalent '-/ Pp' for resolving file
2263                           overwriting conflict (never overwrite).  Here  fol‐
2264                           lows  some  examples of actions, all these are done
2265                           for any entry  found  in  conflict  during  archive
2266                           merging  or archive extraction, we will see further
2267                           how to define conditional actions.
2268
2269                           -/ Rr
2270                                will lead dar to remove any file from filesys‐
2271                                tem that ought to be restored(!). Note the ac‐
2272                                tion for EA/FSA is useless,  the  EA  and  FSA
2273                                will  always  be  erased as well as data using
2274                                'R'. Thus '-/ Rp' would lead to the  same  re‐
2275                                sult.
2276
2277                           -/ Po
2278                                will  keep  data of the 'in place' file and EA
2279                                and FSA set from the 'to be added' file.
2280
2281                           -/ Ss
2282                                Using this option when merging an archive with
2283                                itself  (used both as archive of reference (-A
2284                                option) and auxiliary archive of reference (-@
2285                                option)  )  will provide the same action as an
2286                                archive isolation of the archive of reference,
2287                                but using twice more memory (so keep using the
2288                                isolation operation as before!  Here  this  is
2289                                just an illustration of the possibility)
2290
2291                           As seem previously -u and -U options can be used to
2292                           filter which EA entry to consider and which to  ig‐
2293                           nore. The question here is to explain how this fil‐
2294                           tering mechanism interacts with the different poli‐
2295                           cies  we  just  presented above. For files that are
2296                           not in conflict (found only as 'in place' or as 'to
2297                           be  added'),  only  the  EA entries matching the EA
2298                           filter are kept. For files in conflict,  the  over‐
2299                           writing policy is evaluated first, then the filter‐
2300                           ing mechanism is applied *after* it. Thus for exam‐
2301                           ple,  using  the  following [ -/ "Po" -u "*test" ],
2302                           when merging two  archives,  only  EA  ending  with
2303                           "test"  will be retained, and when a conflict takes
2304                           place, this "*test" ending EA will  be  taken  from
2305                           the  'to  be  added' file if it has some EA of that
2306                           type, its other EA entry will be ignored as well as
2307                           any EA entry of the 'in place' file even those end‐
2308                           ing by "test". At restoration in using the same op‐
2309                           tions,  file without conflict will get restored but
2310                           only EA entry ending with "test" will be  restored,
2311                           and  for  file  with  conflict  (already present in
2312                           filesystem), EA set of file in filesystem  will  be
2313                           removed  and replaced the EA entries of the file in
2314                           archive that ends by "test", if some exist.
2315
2316                           the situation is similar with FSA family scope  and
2317                           overwriting policy. Only FSA of a family present in
2318                           the scope will be retained, the overwriting  policy
2319                           acts first then the FSA scope is applied. Note how‐
2320                           ever that any FSA present  on  filesystem  and  ex‐
2321                           cluded from the FSA scope are not touched.
2322
2323                           Well,  now let's see how to bring some more fun us‐
2324                           ing conditional statements in  all  these  actions.
2325                           The structure to use is the following:
2326
2327                           {<condition>}[<action if condition is true>]
2328                                This  syntax  let  you place an action (as the
2329                                ones we saw just above)  inside  the  brackets
2330                                '['  and ']' (for example [Pp]) that will take
2331                                effect only if the evaluation of  the  <condi‐
2332                                tion>  is  true.  Stated that a such statement
2333                                is a new type of action, you may have  guessed
2334                                that  you  may  use  it  recursively: {<condi‐
2335                                tion1>}[{<condition2>}[<action>]).
2336
2337                           Well so far it seems useless. But  instead  of  the
2338                           "if  <condition> then <action> else <action>" para‐
2339                           digm common to programming languages,  due  to  the
2340                           command  line context it has been chosen to instead
2341                           use and implicit  "OR"  operator  between  actions.
2342                           Thus  you  can  "stack" conditional statements this
2343                           way: {<condition1>}[<action1>]  {<condition2>}[<ac‐
2344                           tion2>] <action3>. In this example, if <condition1>
2345                           is true then <action1> will be used, ELSE if  <con‐
2346                           dition2>  is  true then <action2> will be used ELSE
2347                           <action3> will be used.  This  leads  to  the  same
2348                           possibilities as what is available with programming
2349                           languages, but with a slightly more simple  syntax.
2350                           Seen  this,  the recursion of conditional syntax is
2351                           more interesting.  For readability, you are allowed
2352                           to  add any space or tab in the overwriting policy,
2353                           but the resulting overwriting policy must be  given
2354                           as a single argument to dar, thus the use of quotes
2355                           (either simple ´arg´ or double "arg") is necessary.
2356
2357                           The last operator we will see is the 'chain' opera‐
2358                           tor. Once an expression is evaluated, the resulting
2359                           couple of action may contain an '*' (undefined  ac‐
2360                           tion  for  EA  or data). Further evaluation must be
2361                           done. The chain operator which is represented by  a
2362                           semicolon  ';' let one to separate several indepen‐
2363                           dent expressions that will be evaluated in turn  up
2364                           to  the time the couple of action is fully defined.
2365                           Once an action (for EA or for Data) is defined,  it
2366                           can  be redefined by a subsequent evaluation in the
2367                           chain, however if the action is defined  it  cannot
2368                           be set back to undefined, thus '*' will never over‐
2369                           write a previously defined action. If at the end of
2370                           the  policy  the  couple of action is not fully de‐
2371                           fined, the 'preserve' action is used  ('P'  or  'p'
2372                           depending  on  which  of  EA  or Data is left unde‐
2373                           fined). Here follow a example of syntax:
2374
2375                           -/ "{<condition1>}[P*] O* ; {<condition2>[*p] *o} ;
2376                           Rr"
2377                                The  first  expression will evaluate to either
2378                                P* or O*. At this step, as the action  is  not
2379                                completely  defined,  the  second  part of the
2380                                chain is evaluated, It will end with either *p
2381                                or  *o. In any case, we have after this second
2382                                statement of the chain a fully defined  action
2383                                for  both  data  and  EA (either Pp, Po, Op or
2384                                Oo). Thus the evaluation stops  here  and  the
2385                                "Rr" policy will never be evaluated.
2386
2387                           We  now  have  one last thing to see: the available
2388                           conditions (what to place between  braces  '{'  and
2389                           '}').  Conditions  are  defined  each  by a letter,
2390                           eventually followed by an argument  between  paren‐
2391                           thesis.  The usual logical operators are available:
2392                           negation  (!),  conjunction  (&)  disjunction  (|).
2393                           These  characters  must be escaped or quoted to not
2394                           be interpreted by the shell when used  on  command-
2395                           line.  In  particular the '!' under most shell must
2396                           be quoted and escaped (-/ '{\!R}[..]..', The escape
2397                           character  '\'  is  not  necessary inside DCF files
2398                           (those given to -B option) as no shell is  used  to
2399                           interpret these files. To these usual operators has
2400                           been added a new  one:  the  "inversion"  operator,
2401                           noted '~'. Like the negation, it is an unary opera‐
2402                           tor but unlike the negation, it inverses the  roles
2403                           of 'in place' and 'to be added' for the evaluation,
2404                           which is slightly different from taking  the  nega‐
2405                           tion of the result of the evaluation. All these op‐
2406                           erators follow the usual precedence:  unary  opera‐
2407                           tors  ('!'  and  '~') are evaluated first, then the
2408                           conjunction '&' then the disjunction '|'. To  over‐
2409                           ride  this, you can use parenthesis '(' and ')' in‐
2410                           side the condition. Over these  logical  operators,
2411                           the  conditions  are  based on atomic operator that
2412                           compare the 'in place' file to the  'to  be  added'
2413                           file. Here they follow:
2414
2415                           I    true  only if the 'in place' entry is an inode
2416                                (a 'detruit' which record the fact that a file
2417                                has  been  removed since the archive of refer‐
2418                                ence is not an inode for example). This condi‐
2419                                tion  do not have any consideration toward the
2420                                to be added object. Note that ~I can  be  used
2421                                to  check  the nature of the 'to be added' ob‐
2422                                ject.
2423
2424                           D    true only if the 'in place' entry is a  direc‐
2425                                tory.  To  know whether the 'to be added' is a
2426                                directory or not, one would  use  the  "inver‐
2427                                sion" operator: ~D
2428
2429                           F    true  only  if the 'in place' entry is a plain
2430                                file (true also if this plain file is a  'hard
2431                                link',  that's  it if its inode is linked sev‐
2432                                eral times to the directory tree)
2433
2434                           H    true only if the 'in place' entry is an  inode
2435                                linked  several times to the directory tree (=
2436                                hard link) it may be  a  plain  file,  a  Unix
2437                                socket,  a  pipe,  char device, a block device
2438                                for example.
2439
2440                           A    same as H but the current 'in place' entry  is
2441                                the  first  link we meet pointing to that hard
2442                                linked inode.
2443
2444                           R    true if the 'in place' entry  is  more  recent
2445                                than  or of same date as the 'to be added' en‐
2446                                try. The last modification date [aka mtime] is
2447                                used for this comparison. If the 'to be added'
2448                                entry is not an inode (and thus has no mtime),
2449                                the 'in place' is considered to be more recent
2450                                than the 'to be added' entry.  Same  thing  if
2451                                the  'in place' entry is not an inode (and has
2452                                no mtime available for comparison), it is here
2453                                too assumed to be more recent.
2454
2455                           R(<date>)
2456                                true  if  the  'in place' entry is more recent
2457                                than or of the same date as the  fixed  <date>
2458                                given  in  argument.  No consideration is done
2459                                toward the 'to be added' element.  The  <date>
2460                                format  is  the  same as the one used with -af
2461                                option. If an entry has no mtime (it is not an
2462                                inode  for  example)  it is assumed an virtual
2463                                mtime of zero.
2464
2465                           B    true only if both 'in place' and 'to be added'
2466                                are plain file (hard linked or not) and if the
2467                                'in place' file's data is larger or  equal  to
2468                                the  'to be added' file's data. If one or both
2469                                entry are not plain files  (or  hard  link  to
2470                                plain  file) and thus the file size comparison
2471                                is not possible, the 'in place' entry  is  as‐
2472                                sumed  to  be  'bigger' than the 'to be added'
2473                                entry.
2474
2475                           S    true only if the 'in place' data is  saved  in
2476                                the  archive  (not  marked  as  unchanged  nor
2477                                marked as only inode metadata  changed,  since
2478                                the archive of reference). Note that while ex‐
2479                                tracting files from an archive, the 'in place'
2480                                file  is  the one in the filesystem, which al‐
2481                                ways has its data 'saved' (from  libdar  point
2482                                of view). The 'inversion' of this atomic oper‐
2483                                ator ~S may still be interesting in  the  con‐
2484                                text of restoration.
2485
2486                           Y    true  only if the 'in place' data is saved but
2487                                dirty (plain file having its data  changed  at
2488                                the  time  it was read for backup). Note, that
2489                                restoring in sequential read mode, it  is  not
2490                                possible  to known whether a file is dirty (it
2491                                is possible to know it once  having  read  its
2492                                data,  but  sequential reading does not allows
2493                                then to skip forward to get the dirty state of
2494                                the  file  and skip backward to eventually re‐
2495                                store that file, depending on the  overwriting
2496                                policy result).
2497
2498                           X    true  only  if the 'in place' data is a sparse
2499                                file
2500
2501                           T    true only if the 'in place' and 'to be  added'
2502                                entries  are  of  same  type (plain file, Unix
2503                                socket, named pipe, block device, char device,
2504                                symlink,  directory,  'detruit'  (which stands
2505                                for file deleted since the archive  of  refer‐
2506                                ence was done), and so on). Note that the num‐
2507                                ber of links to inode (i.e. whether this is  a
2508                                hard links or not) is not taken into account.
2509
2510                           L    true  only  if  the 'in place' entry has delta
2511                                signature associated with it.
2512
2513                           e    true if the 'in place' entry has EA (may  they
2514                                be saved or just recorded as existing).
2515
2516                           r    true  if  the 'in place' entry has more recent
2517                                or equal dated EA to the 'to be added'  entry.
2518                                If  'to  be added' has no EA or is even not an
2519                                inode, true is returned. If 'in place' has  no
2520                                EA  or  is even not an inode, true is returned
2521                                unless 'to be added' has some EA. The compari‐
2522                                son is done on ctime dates.
2523
2524                           r(<date>)
2525                                true  if  the 'in place' entry has more recent
2526                                or equal dated EA to the fixed <date> given in
2527                                argument.  No consideration is done toward the
2528                                'to be added' element. The  <date>  format  is
2529                                the  same  as the one used with -af option. If
2530                                an entry has no date (ctime date) (when it  is
2531                                not  an  inode  for  example) it is assumed an
2532                                virtual ctime of value zero.
2533
2534                           m    true only if 'in place' has more or equal num‐
2535                                ber  of  EA entry in its set of EA than 'to be
2536                                added' has. If an entry has not EA or  is  not
2537                                even  an  inode, it is assumed it has zero en‐
2538                                try. The comparison is done  on  this  number.
2539                                Note  that  the  number of EA entry is not the
2540                                size used to store these entries. For example,
2541                                the  EA  entry "user.test" counts for 1, what‐
2542                                ever is the length of the value associated  to
2543                                it.
2544
2545                           b    true if the 'in place' entry has bigger EA set
2546                                or equal size EA set than the  'to  be  added'
2547                                entry. If an entry has no EA or is even not an
2548                                inode, it is assumed that it has a  zero  byte
2549                                length  EA set. The comparison is done on this
2550                                number in that case. Note that the  comparison
2551                                is  done  on the bytes used to store the whole
2552                                EA set associated to a given file.
2553
2554                           s    true if the 'in place' entry is an inode (or a
2555                                hard linked inode) and has its EA saved in the
2556                                archive of reference, not only marked  present
2557                                but  unchanged  since  last  backup. This test
2558                                does not take the 'to be added' entry into ac‐
2559                                count.
2560
2561                           Well,  you've  seen  that uppercase letter are kept
2562                           when comparison is based on the inode or data while
2563                           lowercase  letter  is used for atomics based on EA.
2564                           Now that we have completed our tour of this feature
2565                           let's see some examples:
2566
2567                           -/ Pp
2568                                as seen previously this is what does -n option
2569                                for files when no overwriting  policy  is  de‐
2570                                fined,  which  avoids any overwriting for Data
2571                                as well as for EA.
2572
2573                           -/ "{!T}[Pp] {R}[{r}[Pp]Po] {r}[Op] Oo"
2574                                Space and tabs are allowed to  ease  readabil‐
2575                                ity.  Here  the policy stands for: If files in
2576                                conflicts are not of the same type  then  keep
2577                                Data  and  EA of the entry 'in place'. Else if
2578                                'in place' has a more recent data then if  'in
2579                                place'  has  more recent EA then keep both its
2580                                Data and EA, else keep only its Data and over‐
2581                                write  its EA. Else (if 'in place' has not the
2582                                more recent data), if it has the  more  recent
2583                                EA  then  overwrite  the data but keep its EA,
2584                                else overwrite both its  data  and  EA.   This
2585                                policy  tends to preserve the most recent data
2586                                or EA, but it does not take into  account  the
2587                                fact that EA or Data is effectively saved into
2588                                the archive of just marked as unchanged  since
2589                                the archive of reference.
2590
2591                           -/ "{!T}[{~D}[Oo] Pp]"
2592                                If  entries  are  not of the same type, if the
2593                                'to be added' entry is  a  directory  then  we
2594                                keep  it  and  overwrite the 'in place' entry,
2595                                else we keep the 'in place'  entry.  If  entry
2596                                are  of same type, the policy does not provide
2597                                any action, thus the default action  is  used:
2598                                "Pp".  You can change this default action eas‐
2599                                ily using a chain operator:
2600
2601                           -/ "{!T}[{~D}[Oo] Pp] ; Aa"
2602                                In this case instead, if entry are of the same
2603                                type, the user will be asked what to.
2604
2605                           -/  "{!T|!I}[{R}[Pp]  Oo]  {S}[{~S}[{R}[P*] O*] P*]
2606                           {~S}[O*] {R}[P*] O*]  ;  {s}[{~s}[{r}[*p]  *o]  *p]
2607                           {~s}[*o] {r}[*p] *o]"
2608                                Well this may seems a bit too complex but just
2609                                see it as an illustration of what is  possible
2610                                to  do:  If  both 'in place' and 'to be added'
2611                                are not of the same type we keep data  and  EA
2612                                of  the  most  recent  file (last modification
2613                                date). Else, both are of  the  same  type.  If
2614                                both  are  inode we evaluate a two expressions
2615                                chain (expressions are separated  by  a  semi‐
2616                                colon ';') we will see in detail further. Else
2617                                if they are of same type but are not inode  we
2618                                take  the EA and data of the most recent entry
2619                                (this is the last 10  chars  of  the  string).
2620                                Well,  now  let's  see  the case of inode: The
2621                                first expression in the chain sets the  action
2622                                for data and keep the action for EA undefined.
2623                                While the seconds, is the exact equivalent but
2624                                instead  it  leaves  the action for data unde‐
2625                                fined '*' and set the action for EA. These two
2626                                expressions follow the same principle: If both
2627                                entries are saved (by opposition to be  marked
2628                                as  unchanged  since the archive of reference)
2629                                in the archives, the most  recent  EA/Data  is
2630                                kept, else, the one of the inode that is saved
2631                                is kept, but if none is saved in  the  archive
2632                                the most recent entry (mtime/ctime) is kept.
2633
2634       -^, --slice-mode perm[:user[:group]]
2635                           defines  the  permission  and  ownership to use for
2636                           created slices. By default, dar creates slices with
2637                           read  and  write  available  for anyone letting the
2638                           umask variable disable some privileges according to
2639                           user's  preferences.  If  you  need  some  more re‐
2640                           stricted permissions, you can provide  the  permis‐
2641                           sion  as an octal value (thus beginning by a zero),
2642                           like 0600 to only grant read and  write  access  to
2643                           the  user.  Be  careful not to avoid dar writing to
2644                           its own slices, if for example you provide  permis‐
2645                           sion  such as 0400. Note also that the umask is al‐
2646                           ways applied thus specifying -^ 0777 will not grant
2647                           word  wide  read-write  access unless your umask is
2648                           0000.
2649
2650       -_, --retry-on-change count[:max-byte]
2651                           When a file has changed at the time it was read for
2652                           backup,  you  can ask dar to retry saving it again.
2653                           By default a file can be re-saved  up  to  3  times
2654                           (this is the 'count' field), you can set it to zero
2655                           to disable this feature. In option the overall max‐
2656                           imum  amount  of  byte  allowed to be wasted due to
2657                           retry changing file's backup can be given  after  a
2658                           colon  character (:), this is the 'max-byte' field.
2659                           By default (no --retry-on-change option  specified)
2660                           a  limit  of  1 wasted byte is allowed which is the
2661                           mininum. Specifying zero for max-byte set no  limit
2662                           on  the amount of wasted bytes (same as if no 'max-
2663                           byte' was specified), each changing  file  is  then
2664                           saved up to 'count' times if necessary.
2665
2666                           A file is considered as changed when the last modi‐
2667                           fication time has changed between the time the file
2668                           has been opened for backup and the time it has been
2669                           completely read. In some situation it is not possi‐
2670                           ble  to  replace  the already saved data for a file
2671                           (writing archive to a pipe for  example),  in  that
2672                           situation  only, a second copy of the file is added
2673                           just after the first previous try which leads  that
2674                           previous  try  to  becomes inaccessible, however it
2675                           holds some place in the  archive,  where  from  the
2676                           designation  of  "wasted bytes". You can remove all
2677                           wasted bytes from an archive using the merging/fil‐
2678                           tering feature: dar -+ new_arch -A old_arch -ak.
2679
2680                           Note:  since  release 2.5.0, in normal condition no
2681                           byte is wasted when a file changed at the  time  it
2682                           was  read for backup, except when doing a backup to
2683                           pipe (using '-c -' option), except if the beginning
2684                           of the modified file is located in a previous slice
2685                           and except if slice hashing or strong encryption is
2686                           used.
2687
2688       -ad, --alter=decremental
2689                           This  flag  is to be used only when merging two ar‐
2690                           chives. Instead of the  usual  merging  where  each
2691                           files  of  both archives are added to the resulting
2692                           archive with eventually a tie using the overwriting
2693                           policy  (see -/ option), here the merging builds an
2694                           archive which corresponds to the decremental backup
2695                           done  based  on  two full backups. the -A backup is
2696                           expected to receive the older archive while the  -@
2697                           is  expected  to  point  to the more recent one. If
2698                           this option is  used,  the  eventually  overwriting
2699                           policy  is  ignored  and  replaced internally by -/
2700                           "{T&R&~R&(A|!H)}[S*]              P*              ;
2701                           {(e&~e&r&~r)|(!e&!~e)}[*s] *p". Additionally, files
2702                           found in the newer archive that do not  existed  in
2703                           the  older are replaced by a 'detruit' entry, which
2704                           marks them to be remove at  restoration  time.  For
2705                           more information about decremental backups read the
2706                           usage_notes.html file in  the  documentation.  Note
2707                           that  decremental  backup  is  not  compatible with
2708                           delta binary.
2709
2710       -asecu, --alter=secu
2711                           This option disable the ctime check done by default
2712                           during  an  differential backup: If the ctime of an
2713                           plain file has changed since the archive of  refer‐
2714                           ence was done while all other values stay unchanged
2715                           (inode type, ownership, permission, last  modifica‐
2716                           tion  date),  dar  issues  a "SECURITY WARNING", as
2717                           this may be the sign of the presence of a  rootkit.
2718                           You  should  use  the -asecu option to disable this
2719                           type of warning globally, if you are doing  a  dif‐
2720                           ferential backup of a just restored data (a differ‐
2721                           ential backup with the archive used for restoration
2722                           taken as reference). Effectively in that situation,
2723                           as it is not possible to  restore  ctime,  the  re‐
2724                           stored  data's  ctime will have changed while other
2725                           parameters  will  be  unchanged  for  all  restored
2726                           files,  leading  dar to issue a warning for all re‐
2727                           stored files. This security check is disabled  (im‐
2728                           plicitly) if dar is run with -ac option. Last, if a
2729                           file has only its EA changed since the  archive  of
2730                           reference  was  done  (new EA, removed EA, modified
2731                           EA), the security warning will  show  (false  posi‐
2732                           tive).
2733
2734       -., --user-comment "<message>"
2735                           This  option  let the user add an arbitrary message
2736                           into the archive header. Warning! this  message  is
2737                           always stored in clear text, even if the archive is
2738                           encrypted. You can see the message inserted  in  an
2739                           archive displaying the archive summary (dar -l <ar‐
2740                           chive> -q). Some macro can be used inside the <mes‐
2741                           sage>:
2742
2743                           %c   is  replaced  by  the  command line used. Note
2744                                that for security, any option related  to  ar‐
2745                                chive  encryption  is removed (-K, -J, -$, -#,
2746                                -*, -%). The command included from a DCF  file
2747                                (see -B option) are never added by this macro.
2748                                As a consequence, if you do not  want  to  see
2749                                --user-comment stored in user comments you can
2750                                add the --user-comment definition  in  an  in‐
2751                                cluded file like ~/.darrc for example.
2752
2753                           %d   this is the current date and time
2754
2755                           %u   this is the uid under which dar has been run
2756
2757                           %g   this is the gid under which dar has been run
2758
2759                           %h   the  hostname  on  which  the archive has been
2760                                created
2761
2762                           %%   the % character.
2763
2764       -3, --hash <algo>   With this option  set,  when  creating,  isolating,
2765                           merging or repairing an archive, beside each gener‐
2766                           ated slices an on-fly hash file  of  the  slice  is
2767                           created  using  the  specified algorithm. Available
2768                           algorithm are "md5", "sha1" and  "sha512".  By  de‐
2769                           fault no hash file is generated. The hash file gen‐
2770                           erated is named based on the name of the slice with
2771                           the .md5, .sha1 or .sha512 extension added to it at
2772                           the end. These  hash  files  can  be  processes  by
2773                           md5sum,   sha1sum   and  sha512sum  usual  commands
2774                           (md5sum -c <hash file>) to verify  that  the  slice
2775                           has  not  been  corrupted.  Note that the result is
2776                           different  than  generating  the  hash  file  using
2777                           md5sum  or  sha1sum  once  the slice is created, in
2778                           particular if the media is faulty:  calling  md5sum
2779                           or  sha1sum on the written slice will make you com‐
2780                           pute the hash result on  a  possibly  already  cor‐
2781                           rupted  file,  thus the corruption will not be seen
2782                           when testing the file against the hash at  a  later
2783                           time. Note also that the creation of a hash file is
2784                           not available when producing the archive on a  pipe
2785                           ("dar -c -").
2786
2787       -7, --sign email[,email[,...email]]
2788                           When  creating,  isolating, merging or repairing an
2789                           archive with public key encryption (read -K option)
2790                           it  is also possible to sign it with one or more of
2791                           your private key(s). At the difference of the  hash
2792                           feature above, only the randomly generated key used
2793                           to cipher the archive, key that is dropped  at  the
2794                           beginning and at the end of the archive, is signed.
2795                           If the archive is modified at some place, that part
2796                           will  not  be  possible  to decipher, but signature
2797                           verification will stay quick and valid, unless  the
2798                           part  that  has been tempered is the key inside the
2799                           archive in which case signature check will report a
2800                           failure and archive will not be readable at all. If
2801                           the signature is valid and the archive could be ex‐
2802                           tracted  without  error, the whole archive could be
2803                           assumed to be signed by the gnupg key  owners,  but
2804                           read below the security note. See also GNUPGHOME in
2805                           the ENVIRONMENT section at the end  of  this  docu‐
2806                           ment.
2807
2808                           A  summary information about the signature informa‐
2809                           tion is displayed while listing an archive in  sum‐
2810                           mary  mode "dar -l <archive> -q". For any operation
2811                           involving a signed archive, a  short  message  only
2812                           shows  if the archive is signed an one or more sig‐
2813                           nature check failed, no  message  is  displayed  in
2814                           case  of  successful  signature check. This warning
2815                           may be disabled using  the  --alter=blind-to-signa‐
2816                           tures command.
2817
2818       -<, --backup-hook-include <mask>
2819                           The  mask is applied to path+filename during backup
2820                           operation only. If a given file matches the mask, a
2821                           user  command (see -= option below) will be run be‐
2822                           fore proceeding to the backup and once  the  backup
2823                           will be completed. See also -> option below. IMPOR‐
2824                           TANT: if using the short option, you  need  to  en‐
2825                           close  it between quotes: '-<' for the shell not to
2826                           interpret the < as a redirection.
2827
2828       -> --backup-hook-exclude <mask>
2829                           The mask is applied to path+filename during  backup
2830                           operation  only.  If a given file matches the mask,
2831                           even if it matches a mask given after -< option, no
2832                           user  command will be executed before and after its
2833                           backup. The -< and -> options act like -g  and  -P,
2834                           they  can receive wildcard expression and thus have
2835                           their comportment driven by the  --alter=globe  and
2836                           --alter=regex  expressions  seen  above, as well as
2837                           the --alter=mask option. Last the --alter=case  and
2838                           --alter=no-case  modify also the way case sensitiv‐
2839                           ity is considered for these masks. By  default,  no
2840                           ->  or  -<  option, no file get selected for backup
2841                           hook. IMPORTANT: if using  the  short  option,  you
2842                           need  to  enclose  it  between quotes: '->' for the
2843                           shell not to interpret the > as a redirection.
2844
2845       -=, --backup-hook-execute <string>
2846                           for files covered by the mask  provided  thanks  to
2847                           the -< and -> options, the given string is executed
2848                           before the backup of that file starts and  once  it
2849                           has  completed.  Several macro can be used that are
2850                           substituted at run time:
2851
2852                           %%        will be replaced by a literal %
2853
2854                           %p        will be replaced by the full  path  under
2855                                     backup
2856
2857                           %f        will be replaced by the filename (without
2858                                     the path)
2859
2860                           %u        will be replaced by the UID of the file
2861
2862                           %g        will be replaced by the GID of the file
2863
2864                           %t        will be replaced by a letter  correspond‐
2865                                     ing  to  the type of inode: 'f' for plain
2866                                     file, 'l' for symlink, 'd' for directory,
2867                                     'c'  for  char devices, 'b' for block de‐
2868                                     vices, 's' for sockets,  'p'  for  pipes,
2869                                     'o' for doors.
2870
2871                           %c        and most interesting, %c (c for context),
2872                                     will be replaced by "start" or  by  "end"
2873                                     when  the  command  is executed before or
2874                                     after the backup respectively.
2875       This way, one can dump a database in a  directory  just  before  it  is
2876       about  to  be backed up, and clean it up once the backup has completed.
2877       Note that the masks seen above that drive the execution of this command
2878       can  be  applied to a directory or a plain file for example. When a di‐
2879       rectory is selected for this feature, the command is logically ran  be‐
2880       fore  starting (with the context "start") to backup any file located in
2881       that directory or in a subdirectory of it, and once all files  in  that
2882       directory  or subdirectories have been saved, the command is ran a sec‐
2883       ond time (with the context "end"). During that time,  if  any  file  do
2884       match  the backup-hook masks, no command will be executed for these. It
2885       is assumed that when a directory has been asked for a backup-hook to be
2886       executed this hook (or user command) is prepare for backup all data lo‐
2887       cated in that directory. The environment variable DAR_DUC_PATH also ap‐
2888       plies  to  these  user commands (see -E above, or the ENVIRONMENT para‐
2889       graph below).
2890
2891       -ai, --alter=ignore-unknown-inode-type
2892                           When dar meets an inode type it is not aware  about
2893                           (some  times ago, it was the case for Door inode on
2894                           Solaris for example, Door inodes are handled by dar
2895                           since release 2.4.0), it issues a warning about its
2896                           inability to handle such inode. This warning occurs
2897                           even  if  that entry is filtered out by mean of -X,
2898                           -I, -P, -g, -[ or -] options, as soon as some other
2899                           entry  in  that same directory has to be considered
2900                           for backup, leading dar to read that directory con‐
2901                           tents  and failing on that unknown inode type (fil‐
2902                           tering is done based on  the  result  of  directory
2903                           listing).  This option is to avoid dar issuing such
2904                           warning in that situation.
2905
2906       -8, --delta sig     This option can be used for archive backup,  isola‐
2907                           tion  and  merging.  Important:  read also the best
2908                           practice paragraph below
2909
2910                           Called during a backup operation it  leads  dar  to
2911                           create  delta  signature for each file: If the file
2912                           is new or has changed, a signature is computed  and
2913                           stored  beside the file's data, which increases the
2914                           archive size. If the file is not new  and  has  not
2915                           changed  (differential  backup context) if an delta
2916                           signature is found in the archive of reference  (or
2917                           isolated  catalogue),  this  signature is copied to
2918                           the resulting archive, but not the file's data.  If
2919                           the  reference  archive  does not hold delta signa‐
2920                           ture, a new delta signature is  computed  based  on
2921                           the  current data found on filesystem for that file
2922                           and then stored in the resulting archive.   But  in
2923                           any case, without --delta sig the resulting archive
2924                           will hold no delta signature. Note that delta  sig‐
2925                           nature transfer is not possible when the archive of
2926                           reference is read in sequential  mode,  thus  delta
2927                           signature is disabled when the archive of reference
2928                           is read in sequential mode.
2929
2930                           For isolation and merging operations, the  behavior
2931                           is  slightly  different: --delta sig option let dar
2932                           transfer existing delta signatures from the  origi‐
2933                           nal archive to the isolated/merged one but does not
2934                           lead dar to compute delta signatures for files that
2935                           do not have one, unless one of the --include-delta-
2936                           sig or --exclude-delta-sig option is specified;  in
2937                           that   case   the   delta   signatures  are  trans‐
2938                           fered/dropped and if not present calculated accord‐
2939                           ingly  to  these mask options. However note that it
2940                           is not possible to calculate  delta  signature  for
2941                           unsaved  files in the archive of reference (because
2942                           the archive of reference does not hold their  data)
2943                           as  well  as  for fully saved files when merging is
2944                           performed keeping files  compressed  (see  -ak  op‐
2945                           tion).  Another restriction while merging concernes
2946                           sparse files, it is not possible to  calculate  bi‐
2947                           nary signature for file stored as sparse files, but
2948                           if sparse file detection mechanism is activated  at
2949                           merging time, delta signature can be calculated for
2950                           sparse files too even if it is missing in the  ref‐
2951                           erence archive. In short: if you want recalculation
2952                           of delta signature while merging, do not keep  file
2953                           compressed  (do not use -ak option) and if you want
2954                           to avoid having  sparse  files  excluded  from  the
2955                           delta signature recalcutation, activate sparse file
2956                           detection (use -ah option). Delta signature  trans‐
2957                           fer  is not possible for on-fly isolation, you need
2958                           to do normal archive isolation to  obtain  an  iso‐
2959                           lated catalogue with delta signatures.
2960
2961       -8, --delta sig:<function>:<multiplier>[:<divisor>[:<min>[:<max>]]]
2962                           this  variant of '--delta sig' option let you spec‐
2963                           ify the block length used  to  build  delta  signa‐
2964                           tures.  Larger  values  reduce CPU load required to
2965                           build delta signature, but also lead to less  accu‐
2966                           racy  when  computing  delta  binary,  which  means
2967                           larger delta patch and more data saved when a  file
2968                           has  changed. The block len is calculated following
2969                           the formula: block_len =  function(filesize)*multi‐
2970                           plier/divisor  If  this  calculated  value is lower
2971                           than "min", it is set to  min.  If  the  calculated
2972                           value is greater than "max" it is set to max unless
2973                           max is set to zero in which case the value is  kept
2974                           as  is.  Of  course  "divisor"  cannot be null. The
2975                           available functions are:
2976
2977                           fixed
2978                                always returns 1, in other  terms,  the  block
2979                                size  is  independent  from  the  file size to
2980                                build delta signature for
2981
2982                           linear
2983                                returns the filesize. here, you will  most  of
2984                                the time use 1 for multiplier and increase di‐
2985                                visor to at least 10 for it makes sense
2986
2987                           log2 returns the upper rounded power of  2  closest
2988                                to the file size (base 2 logarithm).
2989
2990                           square2
2991                                returns  the  approximated value of the square
2992                                root of the file size. Note  that  for  better
2993                                performance  and  as accuracy is not important
2994                                here,  this   function   is   implemented   as
2995                                exp2(log2(filesize)/2) where exp2 and log2 are
2996                                based on the integer left and right bit  shift
2997                                operations.
2998
2999                           square3
3000                                returns  the  approximated  value  of the cube
3001                                root    of    filesize,     implemented     as
3002                                exp2(log(filesize)/3)
3003                           All  numerical fields can receive multiplier suffix
3004                           (k, M, ...) for more details about these  suffixes,
3005                           see  -s  option description. If not specified "max"
3006                           defaults to zero (no maximum value defined). If not
3007                           specified  "min"  defaults  to RS_DEFAULT_BLOCK_LEN
3008                           (see below for details  on  this  symbol).  If  not
3009                           specified  "divisor"  defaults to 1. Using "--delta
3010                           sig" without additional fields is equivalent to us‐
3011                           ing  --delta  sig:fixed:RS_DEFAULT_BLOCK_LEN  where
3012                           "RS_DEFAULT_BLOCK_LEN" is taken from  librsync  and
3013                           is today equal to 2048 bytes (which may well change
3014                           in the future by the way  if  librsync  maintainers
3015                           decide to do so).
3016
3017
3018       -{, --include-delta-sig <mask>
3019                           By default when --delta sig is provided, delta sig‐
3020                           natures are computed for all files enrolled in  the
3021                           backup operation (see also --delta-sig-min-size op‐
3022                           tion). This option  and  --exclude-delta-sig  allow
3023                           restricting  the  files  for  which delta signature
3024                           have to be calculated in that situation.  The  mask
3025                           applies  to  the  whole path, the same way as -P/-g
3026                           options do.
3027
3028                           For merging or isolation operations,  when  --delta
3029                           sig is used no delta signature is computed only ex‐
3030                           isting ones are transferred as is without  restric‐
3031                           tion.  To change that behavior and thus either drop
3032                           or add delta signature to files that did  not  have
3033                           one  in the archive of reference, specify an combi‐
3034                           nation of --include-delta-sig  or  --exclude-delta-
3035                           sig with --delta sig.  This option as well as --ex‐
3036                           clude-delta-sig can be used several times  on  com‐
3037                           mand-line  but  are useless/ignored without --delta
3038                           sig. See also -am, -ag and -ar options.
3039
3040       -}, --exclude-delta-sig <mask>
3041                           Files matching the given mask will never have their
3042                           delta signatures calculated, may --delta sig option
3043                           be specified or not. See  also  --include-delta-sig
3044                           option above and --delta-sig-min-size below.
3045
3046       -6, --delta-sig-min-size <number>
3047                           For  archive  merging, isolation and creation, when
3048                           dar has to (re-)calculate  delta  signatures,  this
3049                           option  modifies  the  minimum file size (in bytes)
3050                           below which dar never calculates delta  signatures.
3051                           This  option  acts  independently  from  --include-
3052                           delta-sig and --exclude-delta-sig , however it can‐
3053                           not  re-activate  delta  signature recalculation by
3054                           itself while merging/isolating an archive,  it  re‐
3055                           quires  either  --exclude-delta-sig  or  --include-
3056                           delta-sig option to be active  in  that  situation.
3057                           For  archive  backup  instead,  it does not require
3058                           --exclude-delta-sig nor --include-delta-sig to act,
3059                           but  only need --delta sig option to be set. By de‐
3060                           fault, this minimum size is 10 kio. The same option
3061                           suffixes  (k  for  kilo, M for mega, G for giga, T,
3062                           ...) as the ones available with --slice option  can
3063                           be  used here too. Using zero as argument gives the
3064                           same result as not specifying this  option  at  all
3065                           (default size).
3066
3067       -8, --delta no-patch
3068                           In  the context of differential backup, this option
3069                           leads dar to never consider files for delta  binary
3070                           even  if  delta  signatures are present. By default
3071                           delta binary (rsync-like)  operation  is  performed
3072                           when a file has changed since the archive of refer‐
3073                           ence was made *and* if a delta signature  could  be
3074                           found in the archive of reference for that file (or
3075                           in the isolated catalogue used as reference for the
3076                           incremental/differential  backup). If no delta sig‐
3077                           nature could be found or  if  --delta  no-patch  is
3078                           used, the normal behavior is done, which consist of
3079                           saving that whole file in the archive. Note that if
3080                           the  archive  of  reference  is  read in sequential
3081                           mode, the --delta no patch is  implicitly  used  as
3082                           reading  in sequential mode an archive does not let
3083                           skipping backward to fetch the delta signature nec‐
3084                           essary to setup a delta patch.
3085
3086       Binary delta options usage and best practices:
3087              First  it  must  be  understood that binary delta has advantages
3088              (less storage requirement) and drawbacks: data corruption has  a
3089              wider impact on the ability to restore a given file, restoration
3090              of incrementally backed up file may ask much more than  one  ar‐
3091              chive to be used. To limit the impact of the first drawback, dar
3092              binary delta is done per file, not globally on the total  amount
3093              of  saved data. You are also strongly encouraged to protect your
3094              backups with parity data using par2 (see dar_par.dcf file in the
3095              examples  section  of  the documentation). Adding par2 data will
3096              increase storage requirement by a little, but usually much  less
3097              than the amount gained using binary delta. Last drawback, binary
3098              delta relies on checksum (contained in the delta signature)  and
3099              not on the real data to build the binary delta. There is chances
3100              that two different files provide the same checksum, even if  the
3101              chances  are  very low, probability is not null. The consequence
3102              is that using binary delta the risk  exists  that  the  restored
3103              data do not match the original data and this will not be noticed
3104              by the librsync library on which libdar relies for that feature.
3105              Dar  adds  a second level of checksum, to detect data corruption
3106              inside the archive and to check that the file the delta patch is
3107              about  to be applied is the expected base file, this reduces the
3108              risk of "collision" but does not  remove  it  completely.  After
3109              these  warnings,  let's  now see the best practices about binary
3110              delta:
3111
3112              Once a full backup has been done using --delta sig, any  differ‐
3113              ential  backup  made  based on this archive will use binary diff
3114              for file having a delta signature present in the full backup. If
3115              you  always make differential (not incremental) backups based on
3116              such full backup you have nothing more specific to do in  regard
3117              to binary delta, dar will handle it transparently. In particular
3118              you do not need to invoke --delta sig at subsequent backup, this
3119              saves space in differential archives as well as CPU cycles.
3120
3121              However,  When doing incremental (not differential) backups this
3122              time, if you want to have dar using binary delta at each  subse‐
3123              quent  incremental  backup,  delta signatures must be present in
3124              the successive  incremental  backups.  This  is  done  by  using
3125              --delta sig option for each new incremental backup created.
3126
3127              If you were used to use isolated catalogues before release 2.6.0
3128              you can add --delta sig option while isolating a catalogue  from
3129              an  archive containing delta signatures. Such isolated catalogue
3130              will be much larger than what it can be without this option  but
3131              it  can  be used as reference for a new differential/incremental
3132              backup letting dar relying on binary delta.  Isolated  catalogue
3133              generated without --delta sig do not contain delta signature and
3134              cannot lead to binary delta operation when used as reference for
3135              an incremental or decremental backup.
3136
3137              Another  way  of  doing  differential backup is to make a normal
3138              full backup without --delta sig option, and only add delta  sig‐
3139              natures  at  archive isolation time using --delta sig --include-
3140              delta-sig "*" options. Binary delta signature will then be  cal‐
3141              culated based on the saved files. Then, using the resulting iso‐
3142              lated catalogue as reference dar will be able to proceed to  bi‐
3143              nary  delta  for  the  differential backup. If this works pretty
3144              well for differential backup (or the first  incremental  backup)
3145              which  is based on a full backup, for incremental backup this is
3146              less adapted as a file that has not changed since the archive of
3147              reference  was  made  does not hold any data and calculating the
3148              delta signature is not possible. The first method explained  two
3149              paragraphs above is better as the incremental backup fetches the
3150              already calculated delta signature from the reference to keep it
3151              in  the  resulting incremental backup, so even without data, bi‐
3152              nary delta is still possible.
3153
3154              Isolated catalogue using the --delta sig option,  can  still  be
3155              used as backup of the internal catalogue they have been isolated
3156              from. However, as they hold their  own  delta  signatures,  such
3157              isolated  catalogue can only have access to its own ones, not to
3158              those of the archive of reference. In particular when testing an
3159              archive  (-t  option), using -A option to rescue the archive in‐
3160              ternal catalogue using an isolated  catalogue  containing  delta
3161              signatures,  dar will not be able to check that there is no cor‐
3162              ruption in the delta signatures  fields  of  the  archive  under
3163              test. For that type of testing either use the internal catalogue
3164              of the archive or rescue it using an  isolated  catalogue  built
3165              without --delta sig option.
3166
3167       -az, --alter=zeroing-negative-dates
3168                           dar/libdar saves dates as a number of seconds since
3169                           the beginning of year 1970, the  well  known  "Unix
3170                           time"  (plus  a  positive  fraction  for sub-second
3171                           time-stamping). Some systems may return a  negative
3172                           number as the Unix time of a given file (files hav‐
3173                           ing dates before 1970), in that  situation  by  de‐
3174                           fault  and since release 2.5.12 dar pauses and asks
3175                           the user whether to assume the date as being  zero.
3176                           But  with  -az option, dar/libdar automatically as‐
3177                           sumes such negative dates to be zero and just issue
3178                           a warning about the problem met.
3179
3180       -\, --ignored-as-symlink <absolute path>[:<absolute path>[:...]]
3181                           When  dar  reaches  an  inode which is part of this
3182                           provided colon-separated list, if this inode is not
3183                           a symlink this option has no effect, but if it is a
3184                           symlinks dar saves the file the symlink  points  to
3185                           and  not the symlink itself as dar does by default.
3186                           In particular, if the pointed to inode is a  direc‐
3187                           tory  dar  recurses in that directory. You can also
3188                           pass  this  list  as  argument   to   the   DAR_IG‐
3189                           NORED_AS_SYMLINK environment instead of using --ig‐
3190                           nored-as-symlink (which takes precedence  over  the
3191                           environment variable).
3192
3193       -'\'',  --modified-data-detection=any-inode-change, --modified-data-de‐
3194       tection=mtime-and-size
3195                           Before release 2.6.0, during a  differential/incre‐
3196                           mental  backup  if any part of a file's inode meta‐
3197                           data changed (ownership, permission, ...)  even  if
3198                           the  mtime  (last  modification time) and file size
3199                           stood the same, dar had no choice than resaving the
3200                           whole  file  for  backup  to  record  the  metadata
3201                           changes. This lead to a waste of  backup  time  and
3202                           space if in fact and for example only the ownership
3203                           had been modified. You can still keep this histori‐
3204                           cal behavior by invoking the --modified-data-detec‐
3205                           tion=any-inode-change option.  Since release  2.6.0
3206                           a  new  entry status ("inode-only") has been added.
3207                           Dar can now re-save only metadata  when  the  inode
3208                           change  does  not concern the data. To know whether
3209                           the data has changed or not, by default (no --modi‐
3210                           fied-data-detection  option  given)  dar  looks  at
3211                           mtime and at file's size only.  Specifying  --modi‐
3212                           fied-data-detection=mtime-and-size  (which  is  the
3213                           default behavior) can be used to revert the  action
3214                           of  --modified-data-detection=any-inode-change  for
3215                           example  when  playing  with  included  files  (DCF
3216                           files): the latest met takes precedence.
3217
3218       -T, --kdf-param <integer>[:<hash algo>]
3219                           At  the  difference of the listing context (see be‐
3220                           low), in the context of archive  creation,  merging
3221                           and  isolation, -T option let you define the itera‐
3222                           tion count used to derive the archive key from  the
3223                           passphrase  you  provided  (archive encryption con‐
3224                           text) and the hash algorithm used for that  deriva‐
3225                           tion.  -T  has another older meaning when doing ar‐
3226                           chive listing, but due to the lack of free  charac‐
3227                           ter  to create a new CLI option, there was no other
3228                           choice than recycling an existing option  not  used
3229                           in  the  context of archive creation/merging/isola‐
3230                           tion. The consequence is that the  -T  option  must
3231                           appear  after  the  -+/-c/-C options for the opera‐
3232                           tional context to be known at the time the  -T  op‐
3233                           tion is met and its --kdf-param meaning to be taken
3234                           into account. As --kdf-param is  an  alias  to  -T,
3235                           this  long  form  of this option must also be found
3236                           after the use of either -c, -C or -+ option.
3237
3238              Without --kdf-param the KDF fonction uses 200,000 iterations for
3239              md5, sha1 and sha512 (PBKDF2 from PKCS#5 v2) but only 10,000 for
3240              argon2. If libargon2 is present, this is the default hash  algo‐
3241              rithm,  else  sha1  is  used  with  PBKDF2. Valid parameters are
3242              "sha1", "sha512", "md5" and "argon2" for the hash algorithms and
3243              a  value  greater  than 1 for the iteration count. However it is
3244              advise to use a value equal or greater  to  the  default  values
3245              mentionned  previously. The suffixes described for -s option are
3246              also available here (k, M, G, T, P, ...) however  pay  attention
3247              to the -aSI/-abinary mode which default to binary, in which case
3248              "-T 1k" is equivalent to "-T 1024". Example of use:  --kdf-param
3249              20k:argon2
3250
3251       RESTORATION SPECIFIC OPTIONS (to use with -x)
3252
3253       -k[{ignored|only}], --deleted[={ignore|only}]
3254                           Without  argument  or  with  the "ignore" argument,
3255                           this option leads dar at restoration  time  to  not
3256                           delete  files  that  have  been  deleted  since the
3257                           backup of reference (file overwriting can still oc‐
3258                           cur).  By  default,  files that have been destroyed
3259                           since the backup of reference  are  deleted  during
3260                           restoration,  but  a  warning is issued before pro‐
3261                           ceeding, except if -w is used. If -n  is  used,  no
3262                           file  will be deleted (nor overwritten), thus -k is
3263                           useless when using -n. If -/ option is  used,  this
3264                           option without argument is ignored! With the "only"
3265                           argument, this option only consider files marked as
3266                           to  be  removed  in the archive to restore, no file
3267                           are restored but some file are removed. When -konly
3268                           (or  --deleted=only)  is used, the -/ option is ig‐
3269                           nored (at the opposition  of  the  "--no-delete=ig‐
3270                           nore" option which is ignored when the -/ is used).
3271                           Of   course   "--no-delete=ignore"    and    "--no-
3272                           delete=only"  are  mutually  exclusive,  because if
3273                           both of them were available at the  same  time  dar
3274                           would do nothing at all.
3275
3276       -r, --recent        only  restore  files that are absent or more recent
3277                           than those present in filesystem. If -/  option  is
3278                           used, this option is ignored!
3279
3280       -f, --flat          do  not restore directory structure. All files will
3281                           be restored in the directory given to  -R,  if  two
3282                           files  of  the  same  name have to be restored, the
3283                           usual scheme for warning (-w option) and  overwrit‐
3284                           ing  (-n  option)  is  used.  No  rename  scheme is
3285                           planned actually. When this option is set, dar does
3286                           not  remove  files that have been stored as deleted
3287                           since last backup. (-f implicitly implies -k).
3288
3289       -ae, --alter=erase_ea
3290                           [DEPRECATED use -/ instead] Drop all existing EA of
3291                           files  present  in  filesystem that will have to be
3292                           restored. This way, the restored  files  will  have
3293                           the  exact  set  of  EA they had at the time of the
3294                           backup. If this option is not given, a file to  re‐
3295                           store will have its EA overwritten by those present
3296                           in the backup and if some  extra  EAs  are  present
3297                           they will remain untouched. See the Note concerning
3298                           Extended Attributes (EA) above for a  detailed  ex‐
3299                           planation  about  this  behavior.  If  -/ option is
3300                           used, this option is ignored!
3301
3302       -D, --empty-dir     At restoration time, if -D is  not  specified  (de‐
3303                           fault) any file and directory is restored in regard
3304                           to the filtering mechanism specified (see  -I,  -X,
3305                           -P,  -g,  -[  and  -] options). But if -D option is
3306                           provided the restoration skips directory trees that
3307                           do  not  contain  saved  files. This avoid having a
3308                           huge empty tree with a  few  restored  files  espe‐
3309                           cially  when restoring a differential archive in an
3310                           empty place. Note: This feature  cannot  work  when
3311                           --sequential-read is used, as it is not possible to
3312                           know whether a directory contains or not some saved
3313                           files  at the time the directory inode is read from
3314                           the archive in sequential reading mode.
3315
3316       -2, --dirty-behavior { ignore | no-warn }
3317                           At restoration time, if a file in  the  archive  is
3318                           flagged  as "dirty" (meaning that it had changed at
3319                           the time it was saved), user is asked for confirma‐
3320                           tion  before restoring it. Specifying "ignore" will
3321                           skip those dirty files, while  "no-warn"  will  re‐
3322                           store  them without user confirmation. This feature
3323                           is incompatible with sequential  reading  mode,  in
3324                           this  mode  dar cannot know whether a file is dirty
3325                           before having  restored  it.  In  consequences,  in
3326                           --sequential-read,  once  a file has been restored,
3327                           if it is found to be dirty it will be  removed  un‐
3328                           less dirty-behavior is set to "no-warn".
3329
3330       -/, --overwriting-policy <policy>
3331                           Overwriting policy can be used for archive restora‐
3332                           tion to define when and how  file  overwriting  can
3333                           occur. See above the description of this option.
3334
3335       -A, --ref [[<URL>]<path>]/<basename>
3336                           The --ref option can be used with an isolated cata‐
3337                           logue to rescue an archive that has a corruption in
3338                           the  catalogue  part, see GENERAL OPTIONS above for
3339                           more details.
3340
3341       -au, --alter=unix-sockets
3342                           Do not restore unix-sockets. By default saved  unix
3343                           sockets are recreated at restoration time.
3344
3345       -ap, --alter=place  Since  version  2.7.1  libdar stores the filesystem
3346                           root path (given -R option) used  when  creating  a
3347                           backup,  this  is the known as the 'in-place' path.
3348                           At restoration time by default, dar uses  the  pro‐
3349                           vided  -R  option or if not specified uses the cur‐
3350                           rent directory as root directory for  the  restora‐
3351                           tion  operation.  Using -ap option lead dar to read
3352                           the in-place path from the backup and  restore  the
3353                           data  using  this path instead. This option is thus
3354                           exclusive with -R option and may lead dar to report
3355                           an error if the archive has not stored any in-place
3356                           path (older archive format or backup  resulting  of
3357                           the  merging  of  two  backups having different in-
3358                           place path).
3359
3360       TESTING AND DIFFERENCE SPECIFIC OPTIONS (to use with -t or -d)
3361
3362       -ado-not-compare-symlink-mtime, --alter=do-not-compare-symlink-mtime
3363                           With this option set, when comparing a symlink,  no
3364                           message  shows  when symlink in archive and symlink
3365                           on filesystem do only differ by  their  mtime.  See
3366                           also -O option.
3367
3368       -ap, --alter=place  is  also  available  as  described  just  above for
3369                           restoration options.
3370
3371       No other specific option, but all general options are available  except
3372       for  example  -w  which  is useless, as testing and comparing only read
3373       data. -A option is available as described in GENERAL OPTIONS to  backup
3374       of  internal  catalogue  of the archive (assuming you have a previously
3375       isolated catalogue available).
3376
3377       Doing a difference in sequential read mode is possible but hard  linked
3378       inodes  can  only be compared to the filesystem the first time they are
3379       met, next hard links to this same inode cannot obtain the corresponding
3380       data because skipping backward in sequential read mode is forbidden. In
3381       that situation, the hard links are reported as  skipped,  meaning  that
3382       data comparison could not be performed.
3383
3384       LISTING OPTIONS (to use with -l)
3385
3386       -T, --list-format=<normal | tree | xml | slicing>
3387                           By default, listing provides a tar-like output (the
3388                           'normal' output). You can however get  a  tree-like
3389                           output,  an  XML structured output or an output fo‐
3390                           cusing on slice(s) where each file's data,  EA  and
3391                           FSA  is  located in. The option --tree-format is an
3392                           alias to --list-format=tree  (backward  compatibil‐
3393                           ity). Note that the files doc/dar-catalog-*.dtd de‐
3394                           fine the format of the  XML  output  listing  (This
3395                           file is also installed under $PREFIX/share/doc)
3396
3397                           the -Tslicing option can also be used with isolated
3398                           catalogue generated with dar  2.5.0  or  above,  as
3399                           isolated catalogues now contain a copy of the slic‐
3400                           ing layout of the archive of reference. However, if
3401                           the  archive of reference has been re-sliced (using
3402                           dar_xform) after the isolated  catalogue  has  been
3403                           built,  the  slicing  information would not be cor‐
3404                           rect. For that corner case, you can use the -s  and
3405                           -S  options  with -Tslicing to specify what are the
3406                           new slice sizes of the archive of reference.  Last,
3407                           -Tslicing  and  --sequential-read  options  are not
3408                           compatible except for isolated catalogues.
3409
3410       -as, --alter=saved  list only saved files
3411
3412       -alist-ea, --alter=list-ea
3413                           list Extended Attributes name for  each  file  that
3414                           has some.
3415
3416       -ay, --alter=byte, --alter=bytes
3417                           by  default  files  size is displayed to occupy the
3418                           shortest number of characters by using the  largest
3419                           unit possible (KiB, MiB, GiB, and so on). With this
3420                           option instead, the size is displayed with  maximum
3421                           precision  using the exact number of bytes used for
3422                           each file.
3423
3424       -I, -X, -P, -g, -[, -]
3425                           can be used to filter file to list  base  on  their
3426                           name or path.
3427
3428       -aheader            displays  the  header  (when  --sequential-read  is
3429                           used) or the trailer of the archive and then stops.
3430                           This archive header/trailer is always in clear text
3431                           even when the archive is ciphered. This  option  is
3432                           here to let you access to these fields without pro‐
3433                           viding the encryption key.
3434
3435       From the general options it seems only -vm and  -b  stay  useful  here.
3436       Note  that  -vm  displays an archive summary first, where a detailed of
3437       information about the archive can be obtained. If you want  to  display
3438       only this summary use -q with -l option.
3439
3440       displayed fields
3441
3442                 [Data]    possible  values  are [     ] or [Saved] or [InRef]
3443                           or [DIRTY] or [Inode] or  [Delta].  [      ]  means
3444                           that  the  data has not been saved because there is
3445                           no change since backup of reference. [Saved]  means
3446                           that  the  data has been saved completely, and thus
3447                           this archive is able to restore  the  file  without
3448                           other  help.  [InRef] was used in archive generated
3449                           by dar version 2.3.x and before  when  isolating  a
3450                           catalogue  from an archive, and means that the file
3451                           was saved in the reference archive.  [DIRTY]  means
3452                           that  data  is saved (like [Saved]) but has changed
3453                           at the time dar was reading it for backup,  leading
3454                           dar  to possibly store the file in a state it never
3455                           had. [Inode] means only  permission  ownership  and
3456                           ctime  data  changed since the archive of reference
3457                           was done is recorded in the archive, the  data  did
3458                           not changed according to the --comparison-field set
3459                           or not set. Last [Delta] means the file's  data  is
3460                           saved  as a binary delta (or delta patch), which is
3461                           much shorter than the full data  as  what  is  done
3462                           with  [Saved].  It also means that you can only re‐
3463                           store the file if it exists on  filesystem  in  the
3464                           state  it  had  when  the  archive of reference was
3465                           done, for the patch to be possible to apply on  it.
3466                           This  is  the case for example if you just restored
3467                           this file from the archive of reference.
3468
3469                 [D]       possible values are [-], [ ] or [D]. [D] means that
3470                           delta signature associate with this file is present
3471                           in the archive. [ ] means that the file has no  as‐
3472                           sociated  delta signature and thus binary diff will
3473                           not be possible for it. [-] is used for  non  plain
3474                           files  inodes  for which delta signature is not ap‐
3475                           plicable.
3476
3477                 [EA]      possible values are " " (empty string) or  [      ]
3478                           or  [InRef],  [Saved]  or [Suppr]. It Shows whether
3479                           Extended   Attributes   are   present   and   saved
3480                           ([Saved]),  are  present  but  not  saved ([     ])
3481                           which means there is no change since backup of ref‐
3482                           erence,  if  there  is  no  EA  saved for this file
3483                           (empty string) or if some EA were  present  in  the
3484                           archive  of  reference but none is currently avail‐
3485                           able ([Suppr]). [InRef] was used when  isolating  a
3486                           catalogue  (release  2.3.x  and before) from an ar‐
3487                           chive and means that the file was saved in the ref‐
3488                           erence archive.
3489
3490                 [FSA]     Each character represent a FSA Family:
3491
3492                           "L"  is  the  first  character (L/l/-) representing
3493                                ext2/3/4 FSA family
3494
3495                           "H"  is the second character  (H/h/-)  representing
3496                                HFS+ FSA family
3497
3498                           "-"  the third character is reserved for future FSA
3499                                family and is always a dash for now.
3500
3501                           Uppercase means the FSA  set  is  saved,  lowercase
3502                           means  the  FSA is present in the archive of refer‐
3503                           ence and has not changed since that  time.  Last  a
3504                           dash (-) means no FSA of that family has been saved
3505                           for that file.
3506
3507                 [compr]   possible values are [....%] or [-----] or  [      ]
3508                           or  [worse].  Shows if the file has been compressed
3509                           ([...%]) and the compression ratio reached "(uncom‐
3510                           pressed-compressed)/uncompressed",  for  example  [
3511                           33%] means that the compressed data uses  only  66%
3512                           of  the  space  required to store uncompressed data
3513                           (33% of space saved thanks to compression),  or  if
3514                           the  file is stored without compression ([    ] see
3515                           -m, -Y and -Z options) or if the file is  not  sub‐
3516                           ject to compression because it is not a saved regu‐
3517                           lar file ([----]), or if the file takes more  space
3518                           compressed than its original size ([worse]), due to
3519                           compression overhead. Note that 1% compression  ra‐
3520                           tio brings quite no data reduction, while obviously
3521                           98% is a very  performant  compression  (compressed
3522                           file  takes only 2% of the size required by the un‐
3523                           compressed date).
3524
3525                 [S]       possible values are [ ] or [X]. [X] only applies to
3526                           saved  plain  files,  and  tells  that  the file is
3527                           stored using sparse file data  structure:  not  all
3528                           data is stored, long sequence of zeros are skipped.
3529                           This also means that at restoration  time,  if  the
3530                           filesystem  supports it, holes will be restored. To
3531                           store hole information libdar uses escape  sequence
3532                           (special  sequence of byte), but to avoid real data
3533                           to be considered as such escape sequence, a special
3534                           escape sequence is used when data looks like an es‐
3535                           cape sequence. So if a data contains a such  escape
3536                           sequence,  it  must be read as if it contains holes
3537                           to be able to restore back the data in its original
3538                           form.  For  that reason, in some rare circumstances
3539                           (saving an dar archive inside a dar archive without
3540                           compression  or  encryption,  for  example)  a file
3541                           without hole may be marked [X] as if it  had  holes
3542                           and  will  be  longer  by on byte for each data se‐
3543                           quence looking like an escape sequence.
3544
3545                 permission
3546                           see ls man page. Note that a star (*) is  prepended
3547                           to the permission string if the corresponding inode
3548                           is linked several times to the directory  structure
3549                           (hard link).
3550
3551                 user      owner of the file
3552
3553                 group     group owner of the file
3554
3555                 size      size  in  byte  of  the file (if compression is en‐
3556                           abled, the real size in the archive is "compression
3557                           rate" time smaller).
3558
3559                 date      the  last  modification  date of the file. The last
3560                           access time is also saved  and  restored,  but  not
3561                           displayed.
3562
3563                 filename  The name of the file.
3564
3565                 Extended Attributes
3566                           When using -alist-ea option, for hard linked inode,
3567                           the filename is  followed  by  an  integer  between
3568                           braces:  Entries  with the same number do point the
3569                           the same inode.
3570
3571                 Slice(s)  In -Tslice mode, each file is given  the  range  of
3572                           slices  it  is  located in. If slice size is chosen
3573                           particularly small,  some  slices  may  contain  no
3574                           file,  EA,  FSA data but only tape marks or the in‐
3575                           ternal catalogue, leading the  aggregation  of  re‐
3576                           ported  slices not to cover all available slices of
3577                           the archive.
3578

EXPLICIT OPTIONAL ARGUMENTS

3580       When dar has not been compiled with GNU getopt, which is not present by
3581       default  on  some systems like FreeBSD, you may lack the optional argu‐
3582       ments syntax. For example "-z" will create a parse  error  on  command-
3583       line,  or in -B configuration files. The solution is to explicitly give
3584       the argument. Here follows a list of explicit argument to use in  place
3585       of optional ones:
3586
3587       -z                  must be replaced by -z 9
3588
3589       -w                  must be replaced by -w d or -w default
3590
3591       -H                  must be replaced by -H 1
3592
3593       -0                  must be replaced by -0 ref
3594
3595       -5                  must be replaced by -5 ""
3596
3597       -p                  must be replaced by -p 1
3598
3599       -v                  must be replaced by -v all
3600
3601       -k                  must be replaced by -k ignore
3602
3603       -5                  must be replaced by -5 user.libdar_no_backup
3604
3605       -M                  must be replaced by -M I:/
3606
3607       important  !  When using GNU getopt(), optional arguments are available
3608       by sticking the argument to the  short  option:  "-z"  for  example  is
3609       available  as  well  as  "-z9". But "-z 9" is wrong, it will be read as
3610       "-z" option and "9", a command line argument (not an argument to the -z
3611       option). In the other side, when using a non GNU getopt this time, "-z"
3612       becomes an option that always requires an argument, and thus "-z 9"  is
3613       read  as "-z" option with "9" as argument, while "-z9" will be rejected
3614       as a unknown option, and "-z" alone will generate an error as no  argu‐
3615       ment  is provided. In consequences, you need a space between the option
3616       (like "-z") and its argument (like "9"), when dar does not  rely  on  a
3617       GNU  getopt() call, which also imply you to explicitly use arguments to
3618       options listed just above.
3619
3620

EXIT CODES

3622       dar exits with the following code:
3623
3624       0         Operation successful.
3625
3626       1         Syntax error on command-line or DCF included file
3627
3628       2         Error due to a hardware problem or a lack of memory.
3629
3630       3         Detection of a condition that should never happen, and  which
3631                 is considered as a bug of the application.
3632
3633       4         Code issued when the user has aborted the program answering a
3634                 question from dar. This also happens when dar is not run from
3635                 a  terminal (for example launched from crontab) and dar has a
3636                 question to the user. In that case, dar aborts the  same  way
3637                 as if the user pressed the escape key at the question prompt.
3638
3639       5         is  returned  when  an  error concerning the treated data has
3640                 been detected. While saving, this is the  case  when  a  file
3641                 could  not be opened or read. While restoring, it is the case
3642                 when a file could not be created or replaced.  While  compar‐
3643                 ing, it is the case when a file in the archive does not match
3644                 the one in the filesystem. While testing, it is the case when
3645                 a file is corrupted in the archive.
3646
3647       6         an error occurred while executing user command (given with -E
3648                 or -F option). Mainly because the creation of a  new  process
3649                 is  not  possible (process table is full) or the user command
3650                 returned an error code (exit status different from zero).
3651
3652       7         an error has occurred when calling  a  libdar  routine.  This
3653                 means  the caller (dar program), did not respect the specifi‐
3654                 cation of the API (and this can be considered as a particular
3655                 case of bug).
3656
3657       8         the  version  of  dar used is based on finite length integers
3658                 (it has been compiled  with  the  option  --enable-mode=...).
3659                 This  code is returned when an integer overflow occurred. use
3660                 the full version (based in the so called "infinint" class) to
3661                 avoid this error.
3662
3663       9         this  code  indicates an unknown error. The exception caching
3664                 code to take care of new exceptions has probably been forgot‐
3665                 ten  to  be update ... this is a minor bug you are welcome to
3666                 report.
3667
3668       10        you have tried to use a feature that  has  been  disabled  at
3669                 compilation time.
3670
3671       11        some  saved  files  have  changed while dar was reading them,
3672                 this may lead the data saved for this file not correspond  to
3673                 a  valid  state  for this file. For example, if the beginning
3674                 and the end of the file have been modified at the  same  time
3675                 (while dar is reading it), only the change at the end will be
3676                 saved (the beginning has already been  read),  the  resulting
3677                 state  of  the  file as recorded by dar has never existed and
3678                 may cause problem to the application using it. This is  known
3679                 as a "dirty" file in the archive.
3680
3681

SIGNALS

3683       If  dar  receives  a signal (see kill(2) man page) it will take the de‐
3684       fault behavior which most of the time will abruptly abort the  program,
3685       except for the following signals:
3686
3687       SIGINT    This  signal is generated by the terminal when hitting CTRL-C
3688                 (with the terminal's default settings), it can also be gener‐
3689                 ated with the kill command
3690
3691       SIGTERM   This  signal is generated by the system when changing of run-
3692                 level in particular when doing a shutdown,  it  can  also  be
3693                 generated with the kill command
3694
3695       SIGHUP    Depending  on  the system, this signal may be sent before the
3696                 SIGTERM signal at shutdown time, it  can  also  be  generated
3697                 with the kill command
3698
3699       SIGQUIT   This  signal is generated by the terminal when hitting CTRL-\
3700                 (with the terminal's default settings), it can also be gener‐
3701                 ated with the kill command
3702
3703       SIGUSR1   This signal can be generated by the kill command
3704
3705       SIGUSR2   This signal can be generated by the kill command
3706
3707
3708       For  those  previous  signals,  two  behavior exit. For SIGHUP, SIGINT,
3709       SIGQUIT, SIGTERM and SIGUSR1, a delayed termination is done: the backup
3710       or isolation operation is stopped, the catalogue is appended to the ar‐
3711       chive and the archive is properly completed with the correct terminator
3712       string,  this  way  the generated archive is usable, and can be used as
3713       reference for a differential backup at a later time. Note  that  if  an
3714       on-fly  isolation  had  been  asked, it will *not* be performed, and no
3715       user command will be launched even if dar has been configured  for  (-E
3716       option).  For  SIGUSR2  instead  a fast termination is done: in case of
3717       backup or isolation, the archive is not completed at all,  only  memory
3718       and mutex are released properly.
3719
3720       For both type of termination and other operations than backup or isola‐
3721       tion, dar's behavior is the same: For restoration, all opened  directo‐
3722       ries  are  closed and permissions are set back to their original values
3723       (if they had to be changed for restoration). For  listing,  comparison,
3724       testing, the program aborts immediately.
3725
3726       Another  point, when using one of the previous signals, dar will return
3727       with the exist status 4 meaning that the user has  aborted  the  opera‐
3728       tion. Note that answering "no" to a question from dar may also lead dar
3729       to exit this way. last, If before the end of the program the same  sig‐
3730       nal is received a second time, dar will abort immediately.
3731
3732

FILES

3734       $HOME/.darrc  and  /etc/darrc if present are read for configuration op‐
3735       tion. They share the same  syntax  as  file  given  to  -B  option.  If
3736       $HOME/.darrc  is  not present and only in that case, /etc/darrc is con‐
3737       sulted. You can still launch /etc/darrc from .darrc using  a  statement
3738       like -B /etc/darrc.  None of these file need to be present, but if they
3739       are they are parsed AFTER any option on the command line and AFTER  in‐
3740       cluded  files  from  the  command  line (files given to the -B option).
3741       NOTE: if $HOME is not defined $HOME/.darrc default to /.darrc  (at  the
3742       root of the filesystem).
3743
3744       Else  you  can  see  conditional syntax below, and -N option above that
3745       leads dar to ignore the /etc/darrc and $HOME/.darrc files.
3746
3747

CONDITIONAL SYNTAX

3749       configuration files (-B option, $HOME/.darrc  and  /etc/darrc)  usually
3750       contain a simple list of command-line arguments, split or not over sev‐
3751       eral lines, and eventually mixed  with  comments  (see  -B  option  for
3752       more).  But, you can also use make-like targets to ask for a particular
3753       set of commands to be used in certain conditions.
3754
3755       A condition takes the form of reserved word immediately followed  by  a
3756       colon  ':'.  This word + colon must stand alone on its line, eventually
3757       with spaces or tabs beside it. The available conditions are:
3758
3759       extract:            all options listed after this condition get used if
3760                           previously  on  command line or file the -x command
3761                           has been used
3762
3763       create:             all options listed after this condition get used if
3764                           previously  on command line or file (-B option) the
3765                           -c command has been used
3766
3767       list: (or listing:) if -l command has been used
3768
3769       test:               if -t command has been used
3770
3771       diff:               if -d command has been used
3772
3773       isolate:            if -C command has been used
3774
3775       merge:              if -+ command has been used
3776
3777       repair:             if -y command has been used
3778
3779       reference:          if -A option has been used (except when -A is  used
3780                           for  the  snapshot  feature  or in conjunction with
3781                           -af)
3782
3783       auxiliary:          if -@ option has been used
3784
3785       all:                in any case
3786
3787       default:            if no -c, -d, -x, -t, -C, -l  or -+ option has been
3788                           used at this point of the parsing.
3789
3790       The  condition stops when the next condition starts, or at End of File.
3791       The commands inserted before any condition are equivalent to those  in‐
3792       serted  after  the "all:" condition. Remark : -c -d -x -t -C and -l are
3793       mutual exclusive, only one of them can be used while calling dar.
3794
3795       Here is an example of conditional syntax
3796
3797              create:
3798                # upon creation exclude the
3799                # following files from compression
3800              -Z "*.mp3" -Z "*.mpg"
3801
3802              all:
3803              -b
3804              -p
3805
3806              default:
3807              # this will get read if not
3808              # command has been set yet
3809              -V
3810              # thus by default dar shows its version
3811
3812              all:
3813              -v
3814              # for any command we also ask to be verbose
3815              # this is added to the previous all: condition
3816
3817       Last point, you may have several time the same condition (several  all:
3818       ) for example. They will be concatenated together.
3819
3820

USER TARGETS

3822       User  targets  are  arbitrary  words found on command line, that do not
3823       start by a dash ('-'). On most system they should be placed after  com‐
3824       mand  and  options.  They  are  collected from command-line first, then
3825       comes the parsing of command and optional arguments. Their  use  is  to
3826       extend  conditional  syntax described just above by having a set of op‐
3827       tions activated by the user just adding a single word on  command-line.
3828       Of  course  user targets must not be equal to one of the reserved words
3829       of the conditional syntax (extract, create, ... all, default). A  valid
3830       target  is  a word (thus without space) composed of lowercase or upper‐
3831       case letters (case is sensitive) with eventually digits, dashes '-'  or
3832       underscores '_' characters.
3833
3834       Let's see an example of use:
3835
3836       first  a  DCF  file  named  'example.dcf' that will be given on command
3837       line:
3838
3839              # normal set of files considered for backup
3840
3841              create:
3842                -R /
3843                -P proc
3844                -P sys
3845                -P mnt
3846                -D
3847
3848              # if the "home" user target is applied on command line the  fol‐
3849              lowing command get added
3850
3851              home:
3852                 -g home
3853
3854              #  if  the "verbose" user target is used, we will have some more
3855              verbosity ...
3856
3857              verbose:
3858                -v
3859                -vs
3860
3861       Then we could run dar in the following ways:
3862
3863       dar -c test -B example.dcf
3864                           in that case only the command in the "create:" sec‐
3865                           tion of example.dcf would be used.
3866
3867       dar -c test -B example.dcf verbose
3868                           here  over  the "create:" target the commands under
3869                           the "verbose:" target (-v and -vs)  would  be  also
3870                           used
3871
3872       dar -c test -B example.dcf verbose home
3873                           last we use two user targets "verbose:" and "home:"
3874                           in addition the the "create:" target of  the  usual
3875                           conditional syntax.
3876
3877       Note  that if the last option *may* receive an argument, the first user
3878       target that follows it will be assumed an argument to that  option.  To
3879       avoid  this, either change the order of options on command line for the
3880       last option been an option that never or always uses an  argument  (for
3881       example  -b never has an argument while -s always has one). Or separate
3882       the options from the user targets by the -- word. And of course you can
3883       also  use  the  explicit  argument of the last option (see EXPLICIT OP‐
3884       TIONAL ARGUMENT section, above).
3885
3886       Second point: It is allowed to have user targets  inside  a  DCF  file.
3887       Note  however  that targets are collected in a first phase, which leads
3888       some part of the file to be hidden (because  the  corresponding  condi‐
3889       tional  syntax or user target is not present). Then, the remaining part
3890       of the file is then parsed and actions for each option found is  taken.
3891       At that time, new user targets found are just recorded, but they do not
3892       modify the current DCF file layout, in particular, hidden part  of  the
3893       file  stay hidden even if the corresponding user target is read in this
3894       same file. Next DCF parsing (which may be triggered by a second -B  op‐
3895       tion  on  the command line, or by a -B option inside the current parsed
3896       DCF file) will thus be done with the additional targets found  in  that
3897       first  DCF  file,  so  in a way you may have user targets that activate
3898       other user targets, but they will be activated in starting the next  -B
3899       file.  Here  follows  an  examples of two DCF files, first.dcf and sec‐
3900       ond.dcf:
3901
3902              # cat first.dcf
3903                target3:
3904                  -K toto
3905
3906                target1:
3907                  target2
3908                  -B second.dcf
3909                  target3
3910
3911                target2:
3912                  #never reached
3913                  -s 10k
3914
3915              # cat second.dcf
3916                target2:
3917                  -v
3918                target3:
3919                  -b
3920
3921       In that example, target1 activates both target2 and target3, but at the
3922       time  of the parsing of first.dcf, neither target2 nor target3 were yet
3923       activated thus '-K toto' and '-s 10k' will never be given to  dar  (un‐
3924       less  activated  beside  target1  before first.dcf get parsed), however
3925       when comes the time to parse second.dcf, target2 *and* target3 are  ac‐
3926       tivated,  thus  both '-v' and '-b' will be passed to dar, even if 'tar‐
3927       get3' is located after '-B second.dcf' in the file first.dcf
3928
3929
3930

ENVIRONMENT

3932       DAR_DCF_PATH
3933                 if set, dar looks for Dar Configuration File (DCF files,  see
3934                 -B  option)  that  do not have an fully qualified path in the
3935                 directories listed in DAR_DCF_PATH environment variable. This
3936                 variable  receives  a  colon  (:) separated list of paths and
3937                 look in each of them in turn, up to the first file found  un‐
3938                 der the requested name.
3939
3940       DAR_DUC_PATH
3941                 if  set,  dar  looks for Dar User Command (DUC files, see -E,
3942                 -F, -~, -= options) that do not have a fully  qualified  path
3943                 in  the directories listed in DAR_DUC_PATH. This variable re‐
3944                 ceives a colon (:) separated list of paths and looks in  each
3945                 of  them  in  turn,  up to the first file found under the re‐
3946                 quested name.
3947
3948       DAR_SFTP_KNOWNHOSTS_FILE
3949                 if set, dar will not use the $HOME/.ssh/known_hosts  file  to
3950                 check  sftp  remote server authenticity but the file given as
3951                 value for this environment variable. Note that  setting  this
3952                 variable  to  an empty string completely disable host valida‐
3953                 tion, which is not recommended. Dar, the command line  inter‐
3954                 face  program  for  disk archive relies on libdar for archive
3955                 format management which relies on libcurl for network  trans‐
3956                 fer  which  in  turn  relies on libssh2 for all that concerns
3957                 ssh/sftp protocol. In the known_hosts file, libssh2 does  not
3958                 support recent lines like those with "ecdsa-sha2-nistp256" in
3959                 second argument before its release 1.9.0 (you will also  need
3960                 curl/libcurl  7.69.1  or  more recent), in these old versions
3961                 you only have support for "ssh-rsa" lines. Check libssh2  and
3962                 libcurl  documentations and literature for more details about
3963                 that limitation. The workaround, if you have not yet  libssh2
3964                 1.9.0 or more recent, is to disable known hosts validation or
3965                 set up a restricted known hosts file without any "ecdsa*" en‐
3966                 try and have DAR_SFTP_KNOWNHOSTS_FILE pointing to it.
3967
3968       DAR_SFTP_PUBLIC_KEYFILE
3969                 by   default   dar   will   fetch  the  public  key  file  in
3970                 $HOME/.ssh/id_rsa.pub file. If you use the former  id_dsa.pub
3971                 or  more  recent  key  types you need to set this environment
3972                 variable to point to the appropriated filename
3973
3974       DAR_SFTP_PRIVATE_KEYFILE
3975                 by  default  dar  will  fetch  the   public   key   file   in
3976                 $HOME/.ssh/id_rsa  file.  If you use the former id_dsa.pub or
3977                 more recent key types you need to set this environment  vari‐
3978                 able to point to the appropriated filename
3979
3980       DAR_IGNORED_AS_SYMLINK
3981                 receive  a  colon  separated list of absolute paths, which if
3982                 they are symlinks are not saved as symlink but as  the  inode
3983                 they  point to. For more details see the --ignored-as-symlink
3984                 option above.
3985
3986       GNUPGHOME for asymmetric encryption and signature, the keyring used  is
3987                 $HOME/.gnupg  by default. You can change this default by set‐
3988                 ting GNUPGHOME to the directory containing the  keyring.  For
3989                 example,  if you are running dar as root and want to use your
3990                 unprivileged account keyring use the following:
3991
3992                 export GNUPGHOME=~myaccount/.gnupg
3993
3994                 dar -K gnupg:...@...,...@... --sign:...@... etc.
3995
3996

CAPABILITIES

3998       dar fully supports the cap_chown capability, but by  design,  dar  only
3999       uses  this capability to restore files at their original ownership. Dar
4000       will thus not use this capability to access files and  directories  the
4001       caller  would normally not have access to. In other words, it should be
4002       ok to set the  cap_chown  capability  to  the  dar  executable  (setcap
4003       cap_chown+p  dar).  Calling  dar from a process having the cap_chown in
4004       the inheritable set would lead the system to grant this  capability  to
4005       the  dar process while other users would not be granted this capability
4006       and would not be able to modify ownership of files at restoration time.
4007       This  can be used for the system account that has the role of restoring
4008       data upon user requests, without giving root privilege to this restora‐
4009       tion process.
4010
4011

EXAMPLES

4013       You  can  find  some  more examples of use in the tutorial, mini-howto,
4014       sample scripts, and other related documentation. All these  are  avail‐
4015       able  in dar's source package, and are also installed beside dar in the
4016       <--prefix>/share/dar directory. This documentation  is  also  available
4017       on-line at http://dar.linux.free.fr/doc/index.html
4018
4019

SEE ALSO

4021       dar_xform(1),  dar_slave(1),  dar_manager(1),  dar_cp(1), dar_split(1),
4022       TUTORIAL and NOTES included in the source package and also available at
4023       http://dar.linux.free.fr/doc/index.html
4024
4025

KNOWN LIMITATIONS

4027       dar saves and restores atime, mtime, birthtime but cannot restore ctime
4028       (last inode change), there does not seems to be a standard call  to  do
4029       that  under  UNIX.  An  up  to  date  list  of  known  limitation is at
4030       http://dar.linux.free.fr/doc/Limitations.html
4031
4032

KNOWN BUGS

4034       http://sourceforge.net/p/dar/bugs/
4035
4036

AUTHOR

4038       http://dar.linux.free.fr/
4039       Denis Corbin
4040       France
4041       Europe
4042
4043
4044
40453rd Berkeley Distribution       May 13th, 2021                          DAR(1)
Impressum