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