1DAR(1) General Commands Manual DAR(1)
2
6 dar - creates, tests, lists, extracts, compares, merges, isolates, re‐
7 pairs dar archives
8
10 dar [-c | -t | -l | -x | -d | -+ | -C | -y] [[<URL>]<path>/]<basename>
11 [<options>] [<user targets>]
12 dar -h
14 dar -V
16
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 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 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 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 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 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 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 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 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 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 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 Last, dar is also able to properly save and restore hard-links
111
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
120 The rest of this document is organized that way:
121 COMMANDS
123 The eight actions you can performs with dar
124 GENERAL OPTIONS
126 A set of options common to all actions
127 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 RESTORATION SPECIFIC OPTIONS
133 A set of options that are specific to the restoration oper‐
134 ation
135 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 LISTING OPTIONS
141 A set of options that are specific to archive listing oper‐
142 ation
143 EXPLICIT OPTIONAL ARGUMENTS
145 Some system do not allow optional arguments to options,
146 this chapter explain how to overcome this restriction
147 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 SIGNALS
154 details the signal and their action on a running dar
155 process
156 FILES
158 List configuration files that dar checks for
159 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 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 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
178 COMMANDS:
179 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 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 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 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 -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 -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 -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 -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 -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 -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 -+, --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 -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 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 -h, --help displays help usage.
389 -V, --version displays version information.
391 Remote repository syntax for [<URL>]<path>
393 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 proto://[login[:password]@]hostname[:port]/path
402 proto
404 is either ftp or sftp
405 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 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 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 port
445 if not provided, dar will use the default/standard port in
446 regard to the protocol specified in the "proto" field
447 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 GENERAL OPTIONS:
457 -v, --verbose For backward compatibility, this is an alias to
459 "-vt -vm" (both options set).
460 -vs, --verbose=skipped
462 Display files skipped because of file filtering ex‐
463 clusion specified by the user
464 -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 -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 -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 -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 -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 -vmasks, --verbose=masks
498 Display raw information about the masks set by dar
499 and passed to libdar
500 -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 -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 -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 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 -N, --noconf Do not try to read neither ~/.darrc nor /etc/darrc
547 configuration files. See files section below.
548 -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 -n, --no-overwrite do not allow overwriting
563 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 -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 -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 -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 - An existing archive basename, which will
613 be taken as reference
614 - 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 - 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 - 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 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 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 During Catalogue isolation (-C option), dar will
676 create the isolated catalogue from the one given
677 with -A option.
678 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 -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 <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 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 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 -@, --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 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 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 -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 -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 -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 -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 -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 -[, --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 -], --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 File selection in brief:
872 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 since version 2.2.0 two modes of interpretation of these options exist.
879 The normal original method and the ordered method:
880 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 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 -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 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 -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 -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 Note concerning Extended Attributes (EA)
951 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 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 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 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 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 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 -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 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 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 none "none" is not a FSA family but can be used
1042 alone to ignore all FSA families.
1043 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 Example of use: --fsa-scope extX,HFS+
1058 -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 -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 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 -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 -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 -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 -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 -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 -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 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 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 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 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 -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 -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 %% will be replaced by %
1232 %p will be replaced by the slice path
1234 %b will be replaced by the slice basename
1236 %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 %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 %e will be replaced by the slice extension
1259 (always substituted by "dar")
1260 %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 %u will be replaced by the full URL of path
1279 where the slice is stored
1280 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 -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 --aduc modifies the way the next DUC file is sticked to the previous
1312 command, in other words:
1313 dar --aduc -E script1 -E script2 ...
1315 leads libdar to call a shell with the following line
1316 "script1 && script2"
1317 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 -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 -~, --aux-execute <string>
1329 same as -E and -F but is applied between slices of
1330 the auxiliary archive (-@ option).
1331 -K, --key [[<algo>]:]<string>
1333 -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 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 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 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 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 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 -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 -$, --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 -#, --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 -*, --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 -%, --aux-crypto-block <size>
1483 same as --crypto-block but to read the auxiliary
1484 archive of reference (-@ option).
1485 -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 -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 -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 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 -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 -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 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 -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 -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 -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 --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 -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 -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 -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 -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 -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 SAVING, ISOLATION, MERGING AND REPAIRING SPECIFIC OPTIONS (to use with
1729 -c, -C or -+)
1730 -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 algo:
1738 the following values are available "gzip", "bzip2", "lzo",
1739 "xz", "zstd" or "lz4".
1740 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 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 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 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 -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 -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 -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 -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 -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 -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 -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 -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 -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 -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 --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 -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 -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 example of use:
2015 -MI:/var -MX:/var/spool
2016 --mount-points=I:/var --mount-point=X:/var/spool
2017 -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 -, , --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 -/ , --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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 * 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 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 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 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 -/ 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 -/ Po
2278 will keep data of the 'in place' file and EA
2279 and FSA set from the 'to be added' file.
2280 -/ 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 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 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 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 {<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 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 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 -/ "{<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 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 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 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 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 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 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 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 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 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 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 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 X true only if the 'in place' data is a sparse
2499 file
2500 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 L true only if the 'in place' entry has delta
2511 signature associated with it.
2512 e true if the 'in place' entry has EA (may they
2514 be saved or just recorded as existing).
2515 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 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 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 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 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 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 -/ 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 -/ "{!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 -/ "{!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 -/ "{!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 -/ "{!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 -^, --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 -_, --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 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 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 -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 -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 -., --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 %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 %d this is the current date and time
2754 %u this is the uid under which dar has been run
2756 %g this is the gid under which dar has been run
2758 %h the hostname on which the archive has been
2760 created
2761 %% the % character.
2763 -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 -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 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 -<, --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 -> --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 -=, --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 %% will be replaced by a literal %
2853 %p will be replaced by the full path under
2855 backup
2856 %f will be replaced by the filename (without
2858 the path)
2859 %u will be replaced by the UID of the file
2861 %g will be replaced by the GID of the file
2863 %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 %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 -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 -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 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 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 -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 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 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 log2 returns the upper rounded power of 2 closest
2988 to the file size (base 2 logarithm).
2989 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 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 -{, --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 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 -}, --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 -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 -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 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 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 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 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 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 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 -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 -\, --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 -'\'', --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 -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 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 RESTORATION SPECIFIC OPTIONS (to use with -x)
3252 -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 -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 -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 -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 -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 -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 -/, --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 -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 -au, --alter=unix-sockets
3342 Do not restore unix-sockets. By default saved unix
3343 sockets are recreated at restoration time.
3344 -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 TESTING AND DIFFERENCE SPECIFIC OPTIONS (to use with -t or -d)
3361 -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 -ap, --alter=place is also available as described just above for
3369 restoration options.
3370 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 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 LISTING OPTIONS (to use with -l)
3385 -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 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 -as, --alter=saved list only saved files
3411 -alist-ea, --alter=list-ea
3413 list Extended Attributes name for each file that
3414 has some.
3415 -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 -I, -X, -P, -g, -[, -]
3425 can be used to filter file to list base on their
3426 name or path.
3427 -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 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 displayed fields
3441 [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 [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 [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 [FSA] Each character represent a FSA Family:
3491 "L" is the first character (L/l/-) representing
3493 ext2/3/4 FSA family
3494 "H" is the second character (H/h/-) representing
3496 HFS+ FSA family
3497 "-" the third character is reserved for future FSA
3499 family and is always a dash for now.
3500 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 [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 [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 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 user owner of the file
3552 group group owner of the file
3554 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 date the last modification date of the file. The last
3560 access time is also saved and restored, but not
3561 displayed.
3562 filename The name of the file.
3564 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 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
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 -z must be replaced by -z 9
3588 -w must be replaced by -w d or -w default
3590 -H must be replaced by -H 1
3592 -0 must be replaced by -0 ref
3594 -5 must be replaced by -5 ""
3596 -p must be replaced by -p 1
3598 -v must be replaced by -v all
3600 -k must be replaced by -k ignore
3602 -5 must be replaced by -5 user.libdar_no_backup
3604 -M must be replaced by -M I:/
3606 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
3622 dar exits with the following code:
3623 0 Operation successful.
3625 1 Syntax error on command-line or DCF included file
3627 2 Error due to a hardware problem or a lack of memory.
3629 3 Detection of a condition that should never happen, and which
3631 is considered as a bug of the application.
3632 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 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 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 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 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 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 10 you have tried to use a feature that has been disabled at
3669 compilation time.
3670 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
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 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 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 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 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 SIGUSR1 This signal can be generated by the kill command
3704 SIGUSR2 This signal can be generated by the kill command
3706 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 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 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
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 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
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 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 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 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 list: (or listing:) if -l command has been used
3768 test: if -t command has been used
3770 diff: if -d command has been used
3772 isolate: if -C command has been used
3774 merge: if -+ command has been used
3776 repair: if -y command has been used
3778 reference: if -A option has been used (except when -A is used
3780 for the snapshot feature or in conjunction with
3781 -af)
3782 auxiliary: if -@ option has been used
3784 all: in any case
3786 default: if no -c, -d, -x, -t, -C, -l or -+ option has been
3788 used at this point of the parsing.
3789 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 Here is an example of conditional syntax
3796 create:
3798 # upon creation exclude the
3799 # following files from compression
3800 -Z "*.mp3" -Z "*.mpg"
3801 all:
3803 -b
3804 -p
3805 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 all:
3813 -v
3814 # for any command we also ask to be verbose
3815 # this is added to the previous all: condition
3816 Last point, you may have several time the same condition (several all:
3818 ) for example. They will be concatenated together.
3819
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 Let's see an example of use:
3835 first a DCF file named 'example.dcf' that will be given on command
3837 line:
3838 # normal set of files considered for backup
3840 create:
3842 -R /
3843 -P proc
3844 -P sys
3845 -P mnt
3846 -D
3847 # if the "home" user target is applied on command line the fol‐
3849 lowing command get added
3850 home:
3852 -g home
3853 # if the "verbose" user target is used, we will have some more
3855 verbosity ...
3856 verbose:
3858 -v
3859 -vs
3860 Then we could run dar in the following ways:
3862 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 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 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 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 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 # cat first.dcf
3903 target3:
3904 -K toto
3905 target1:
3907 target2
3908 -B second.dcf
3909 target3
3910 target2:
3912 #never reached
3913 -s 10k
3914 # cat second.dcf
3916 target2:
3917 -v
3918 target3:
3919 -b
3920 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
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 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 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 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 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 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 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 export GNUPGHOME=~myaccount/.gnupg
3993 dar -K gnupg:...@...,...@... --sign:...@... etc.
3995
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
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
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
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
4034 http://sourceforge.net/p/dar/bugs/
4035
4038 http://dar.linux.free.fr/
4039 Denis Corbin
4040 France
4041 Europe
40423rd Berkeley Distribution May 13th, 2021 DAR(1)