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 or Y the size
1802 is in kilobytes, megabytes, gigabytes, terabytes,
1803 petabytes, exabytes, zettabytes or yottabytes re‐
1804 spectively. Example: "20M" means 20 megabytes, by
1805 default, it is the same as giving 20971520 as argu‐
1806 ment (see also -aSI and -abinary options). If -s is
1807 not present the backup will be written to a single
1808 slice whatever the size of the backup may be (as‐
1809 suming your operating system can support arbitrar‐
1810 ily large files).
1811 -S, --first-slice <number>
1813 -S gives the size of the first slice which may be
1814 chosen independently of the size of following
1815 slices (either bigger or smaller). This option
1816 needs -s option and by default of -S option, the
1817 size of the first slice is the same as the one of
1818 the following slices.
1819 -p [<integer>], --pause[=<integer>]
1821 pauses before writing to a new slice (this requires
1822 -s). By default there is no pause, all slices are
1823 written in the same directory, up to the end of the
1824 backup or until the filesystem is full. In this
1825 later case, the user is informed of the lack of
1826 disk space and dar stops for user action. As soon
1827 as some disk space is available, the user can con‐
1828 tinue the backup. The optional integer that this
1829 option can receive tells dar to only pause every
1830 'n' slice. Giving 3 for 'n' will make dar pause
1831 only after slices 3, 6, 9 and so on. If this inte‐
1832 ger is not specified, the behavior is as if '1' was
1833 given as argument which makes dar pause after each
1834 slice.
1835 -D, --empty-dir At backup time only, when excluding directories ei‐
1837 ther explicitly using -P or -] options, or implic‐
1838 itly by giving a -g or -[ options (a directory is
1839 excluded if it does not match mask given with -g
1840 options or -[ options) dar does not store anything
1841 about these. But with -D option, dar stores them as
1842 empty directories. This can be useful, if excluding
1843 a mount point (like /proc or /dev/pts). At restora‐
1844 tion time, dar will then recreate these directories
1845 (if necessary). This option has no meaning with -C
1846 and is ignored in that case. Independently of that,
1847 -D can also be used at restoration time, but it ac‐
1848 tivates a slightly different feature (see RESTORA‐
1849 TION SPECIFIC OPTIONS below).
1850 -Z, --exclude-compression <mask>
1852 Filenames covered by this mask are not compressed.
1853 It is only useful in conjunction with -z option. By
1854 default, all files are compressed (if compression
1855 is used). This option can be used several times, in
1856 that case a file that matches one of the -Z mask
1857 will not be compressed. Argument given to -Z must
1858 not be include any path, just the filename (eventu‐
1859 ally/probably using wildcards). This option used
1860 while merging or repairing allow one to change the
1861 compression of files.
1862 -Y, --include-compression <mask>
1864 Filenames covered by this mask (and not covered
1865 masks given to -Z option(s)) are the only to be
1866 compressed. It is only available with -z option. By
1867 default all files are compressed. This option can
1868 be used several times, in that case all files that
1869 match one of the -Y will be compressed, if they do
1870 not also match on of the -Z masks. The ordered
1871 method here applies too when activated (with -am
1872 option), it works exactly the same as -I and -X op‐
1873 tions, but apply to file compression, not file se‐
1874 lection. In other word, it matches only on the file
1875 name, not on the path of files. This option used
1876 while merging or repairing allow one to change the
1877 compression of files.
1878 -m, --mincompr <number>
1880 files which size is below this value will not be
1881 compressed. If -m is not specified it is equivalent
1882 to giving -m 100 as argument. If you want to com‐
1883 press all files whatever their size is you thus
1884 need to type -m 0 on the command line. The size
1885 unit is the byte (octet) and the same number exten‐
1886 sions as those used with -s or -S are available
1887 here, if you want to specify the size in kilobyte,
1888 megabyte, gigabyte etc.
1889 -1, --sparse-file-min-size <number>
1891 Define the minimum length of zeroed bytes to re‐
1892 place by "holes". By default, this feature is acti‐
1893 vated with a value of 15 bytes. To completely dis‐
1894 able it, set the size to zero. Disabling this fea‐
1895 ture will bring some noticeable speed improvement
1896 but will probably make the archive slightly bigger
1897 (depending on the nature of the data). Sparse files
1898 are files that contain so called holes. On a
1899 filesystem, the portion of zeroed bytes is not
1900 stored on disk, thus an arbitrary large file with
1901 huge portion of zeros may only require a few bytes
1902 of disk storage. While dar cannot detect how is al‐
1903 located a given file because it makes a filesystem
1904 abstraction (it does not know the implementation of
1905 any particular filesystem, where from its portabil‐
1906 ity), when it finds a sequence of zeroed bytes
1907 larger than the given threshold it can assume that
1908 it is in presence of a hole. Doing so, it does not
1909 store the given zeroed bytes into the archive, but
1910 place a tag beside the saved data to record the
1911 size of the hole and thus where to place the next
1912 non zeroed bytes. This makes dar archive disk space
1913 requirement much smaller when a sparse files is
1914 met. At restoration time, dar will restore holes
1915 writing normal data and seeking over the hole to
1916 write down the normal data after each hole. If the
1917 underlying file system supports sparse files, this
1918 will restore the holes. Note that there is no dif‐
1919 ference for applications whether a file is sparse
1920 or not, thus dar may well transform normal files
1921 into sparse files and vice-versa, only the disk re‐
1922 quirement will change. Last point, if dar can re‐
1923 duce disk requirement for archive with holes as
1924 small as 15 bytes (smaller value works but the
1925 overhead cost more than what is required to store
1926 the zeroed bytes normally), it may not be the same
1927 at restoration, because filesystem allocation unit
1928 is usually several kilobytes (a page), however re‐
1929 stored file will never be larger than it could be
1930 without holes. The only drawback of this feature is
1931 the additional CPU cycle it requires.
1932 -ak, --alter=keep-compressed
1934 During merging and repairing operation, keep files
1935 compressed, this has several restrictions : -z, -Z,
1936 -Y, -m are ignored, if two archives have to be
1937 merged, both must use the same compression algo‐
1938 rithm or one of them must not use compression at
1939 all (this last restriction will probably disappear
1940 in a next version). The advantage of this option is
1941 a greater speed of execution (compression is usu‐
1942 ally CPU intensive).
1943 -ah, --alter=holes-recheck
1945 For merging and repairing, the sparse file detec‐
1946 tion mechanism is disabled by default. However if
1947 you want to activate it (assuming you have an old
1948 archive you want to convert the current archive
1949 format taking care of sparse files), you need to
1950 use -ah option to reactivate the sparse file detec‐
1951 tion mechanism. Then for merging and repairing
1952 --sparse-file-min-size can be used as described
1953 above for archive creation. In addition, you can
1954 have files stored as sparse file in the archive of
1955 reference be stored as normal files in the merged
1956 archive using -ah and passing to --sparse-file-min-
1957 size an value larger than all file sizes, for exam‐
1958 ple as of today in year 2018, passing -ah --sparse-
1959 file-min-size 1E (1E for one exabyte) should be
1960 large enough.
1961 --nodump do not save files which have the 'd' flag set (see
1963 chattr(1) lsattr(1) ext2 commands). This option may
1964 not be available if the system dar has been com‐
1965 piled on did not provide support for ext2 flags.
1966 Note that this option does nothing with -+ option
1967 (merging) as no filesystem is used for that opera‐
1968 tion.
1969 -5, --exclude-by-ea[=<extended attribute name>]
1971 exclude inodes from backup that have been set with
1972 the EA given in argument. If not argument is given
1973 to that option the default EA used to exclude files
1974 from backup is "user.libdar_no_backup". To set this
1975 attribute to a given file, use the following com‐
1976 mand: "setfattr -n user.libdar_no_backup <file‐
1977 name>", to remove it: "setfattr -x user.lib‐
1978 dar_no_backup <filename>". Last, to check the pres‐
1979 ence this EA: "getfattr <filename>"
1980 -M, --mount-points={ I:<path to fs> | X:<path to fs> }
1982 If the argument is of the I:<path to fs> form, the
1983 filesystem to which this path points to is consid‐
1984 ered for the backup operation, that's to say, other
1985 file filtering mechanism will be applied and some
1986 or all files of that filesystem will be saved for
1987 backup. While with the X:<path to fs> form, no file
1988 in that filesystem will even be considered for
1989 backup. both X: and I: forms must be provided with
1990 an absolute path. -M option can be used several
1991 times on the command-line. If only I: forms are
1992 used, the filesystem based filtering mechanism be‐
1993 haves as a white list (only those listed paths are
1994 included). If only X: form is used, the filesystem
1995 based filtering mechanism behaves as a black list
1996 (everything is considered except those listed
1997 paths). Last, while a mix of I: and X: forms are
1998 used, filsystems that will be considered for backup
1999 will be those given with an I: form and not also
2000 given with an X: form. Note that this is filesystem
2001 based filtering, not path based: If for example a
2002 filesystem is mounted under /var directory and you
2003 specify I:/var/log all /var filesystem will be con‐
2004 sidered for backup. If you rather want to only save
2005 what is in /var/log use the -P/-g/-X/-I/-[/-] op‐
2006 tions that realise the file filtering by name and
2007 path+name. You cannot exclude the filesystem which
2008 contains the path given to -R option. The use of -M
2009 option with argument erases any previous configura‐
2010 tion done with -M option without argument (see be‐
2011 low), and vice versa. By default (no -M option
2012 specified), no filtering based on filesystem is
2013 performed, in other worlds all files are considered
2014 for other file filtering mechanism (in particular
2015 -P/-g/-X/-I/-[/-] options) and eventually backed
2016 up.
2017 example of use:
2019 -MI:/var -MX:/var/spool
2020 --mount-points=I:/var --mount-point=X:/var/spool
2021 -M, --no-mount-points
2023 This is the legacy form of the option described
2024 just above, that existed before release 2.7.0. When
2025 -M option is provided without argument, only files
2026 located on the filesystem pointed to by the path
2027 given to -R option will be considered for backup.
2028 Subdirectory that are mounting points for other
2029 filesystems will not be saved (or saved empty if -D
2030 option is used). This option is useless and ignored
2031 for merging operation. The use of -M without option
2032 lead dar to ignore any previous -M I:<path> and -M
2033 X:<path> options that could have been given on com‐
2034 mand-line or -B included file so far.
2035 -, , --cache-directory-tagging
2037 don't save contents of directories that use the
2038 Cache Directory Tagging Standard. See
2039 http://www.brynosaurus.com/cachedir/spec.html for
2040 details. (this option is useless with -+ option)
2041 -/ , --overwriting-policy <policy>
2043 This option let the user define when or how file
2044 overwriting can occur at restoration or archive
2045 merging time. It does no apply to slice overwriting
2046 which are driven by the -n option, it does instead
2047 apply to file during extraction and files inside
2048 archives when merging two of them. When considering
2049 overwriting, a file is said to be 'in place' while
2050 an other is known as 'new' or 'to be added'. At
2051 restoration time, the 'in place' is the one that is
2052 present in filesystem while the 'to be added' is
2053 the one from the archive. At merging time, the 'in
2054 place' is the one of the '-A' archive of reference
2055 while the 'to be added' is the one from the auxil‐
2056 iary '-@' archive or reference. This option does
2057 not apply to archive repairing.
2058 As soon as you use -/ option -n only applies only
2060 to slice overwriting and the -r, -k and -ae options
2061 are ignored (restoration specific options).
2062 The given <policy> argument is composed of actions
2064 and eventually of conditional expressions. Actions
2065 do define how to solve overwriting conflict about
2066 file's data on one side and file's Attributes (Ex‐
2067 tended and Filesystem Specific) on the other side.
2068 An action is thus a couple of action for Data and
2069 for EA+FSA. Actions for Data are represented by up‐
2070 percase letters, while action for EA+FSA are de‐
2071 fined by lowercase letters. Both actions are inde‐
2072 pendent of each other:
2073 P means 'Preserve'. When merging two archives,
2075 the data of the resulting archive will be
2076 taken from the 'in place' file. While when ex‐
2077 tracting, the data of the inode in filesystem
2078 will be preserved (thus no overwriting will
2079 occur for the data).
2080 O means 'Overwrite'. When merging two archives,
2082 the data of the resulting archive will be
2083 taken from the 'to be added' file. While when
2084 extracting, the data of the inode in filesys‐
2085 tem will be overwritten by data from the ar‐
2086 chive.
2087 S means 'mark Saved and preserve'. When merging
2089 two archives, the data of the resulting ar‐
2090 chive will be marked as already saved in the
2091 archive of reference (making thus a differen‐
2092 tial archive, even if none of the original ar‐
2093 chive were differential archives). All data
2094 will be dropped in the resulting archive, but
2095 the last modification date [aka mtime] (used
2096 to detect change in file's data) will be taken
2097 from the 'in place' file. This action does not
2098 apply when extracting files, it is thus con‐
2099 sidered equal to "Preserve" (P) in that situa‐
2100 tion.
2101 T means 'mark Saved and overwrite'. When merging
2103 two archives, the data of the resulting ar‐
2104 chive will be marked as already saved (same as
2105 'S' action): all data will be dropped in the
2106 resulting archive, however the last modifica‐
2107 tion date [aka mtime] (used to detect changes
2108 in a file's data) will be taken from the 'to
2109 be added' file. This action does not apply
2110 when extracting files, it is thus considered
2111 equal to "Overwrite" (O) in that situation.
2112 R means 'Remove'. When merging two archives, the
2114 resulting archive will not contain any entry
2115 corresponding to the file that were in con‐
2116 flict. This also implies that no EA will be
2117 stored for that particular entry as the entry
2118 will no more exist in the resulting archive
2119 (as if it had never yet existed). When ex‐
2120 tracting files, this will lead to file's sup‐
2121 pression.
2122 p means 'Preserve', same as 'P' (but lowercase
2124 letter) preserve the whole EA set and FSA.
2125 When merging two archives, the Attributes set
2126 of the resulting file will be the ones of the
2127 'in place' file (whatever is the overwriting
2128 action taken for its data). While when ex‐
2129 tracting files to filesystem, the Attributes
2130 of the file in filesystem will not be changed
2131 (whatever is the overwriting action taken for
2132 its data, unless the file is removed using the
2133 'R' policy, which would remove the inode and
2134 thus also any Attributes it had).
2135 o means 'Overwrite', same as 'O' (but lowercase
2137 letter) overwrite the whole EA set and FSA.
2138 When merging two archives, the Attributes set
2139 of the resulting file will be taken from the
2140 'to be added' file. While when extracting
2141 files, the Attributes set of the file in the
2142 filesystem will have its Attributes erased and
2143 replaced by those of the file in the archive
2144 (still independent of what overwriting action
2145 is taken for file's data).
2146 s means 'mark Saved and preserve', same as 'S'
2148 (but lowercase letter) for EA and FSA instead
2149 of data. When merging two archives, the EA and
2150 FSA of the resulting file are marked as al‐
2151 ready saved in the archive of reference, thus
2152 they are dropped but the date of last inode
2153 change [aka ctime] (used to detect changes in
2154 file's EA and FSA) will be taken from the 'in
2155 place' file. This action does not apply when
2156 extracting files, it is thus considered equiv‐
2157 alent to "Preserve" (p) in that situation.
2158 t means 'mark Saved and overwrite', same as 'T'
2160 (but lowercase letter) for EA and FSA instead
2161 of data. When merging two archives, the EA and
2162 FSA of the resulting file are marked as al‐
2163 ready saved in the archive of reference, thus
2164 they are dropped but the date of last inode
2165 change [aka ctime] (use to track changes in
2166 EA) will be taken from the 'to be added' file.
2167 This action does not apply when extracting
2168 files, it is thus considered an equivalent to
2169 "Overwrite" (o) in that situation.
2170 m means 'merge Attributes and preserve'. The re‐
2172 sulting file in the merged archive will have
2173 Attribute entries from both the 'in place' and
2174 the 'to be added' files. If both files share a
2175 same Attribute entry (same FSA or for EA the
2176 same key for a given association) the one of
2177 the 'in place' file is kept (where from the
2178 'preserve' notion). When extracting a file,
2179 the file in the filesystem will have its EA
2180 and FSA set enriched by the ones of the file
2181 in the archive that do not exist on filesys‐
2182 tem, but its already existing Attributes will
2183 stay untouched.
2184 n means 'merge Attributes and overwrite'. The
2186 resulting file in the merged archive will have
2187 Attribute entries from both the 'in place' and
2188 the 'to be added' files. If both files share a
2189 same Attribute entry (same FSA or for EA the
2190 same key for a given association) the one of
2191 the 'to be added' file will be kept (where
2192 from the 'overwrite' notion). When extracting
2193 file, the file in the filesystem will have its
2194 Attributes set enriched by ones of the file in
2195 the archive with some of them possibly been
2196 overwritten.
2197 r means 'remove', same as 'R' but for the Attri‐
2199 bute set (thus all EA and FSA entries) of a
2200 given file ('r' is lowercase letter here). The
2201 file of the resulting archive during merging
2202 operation will not own any EA nor any FSA,
2203 even if the 'in place' and/or the 'to be
2204 added' files did have some. For file extrac‐
2205 tion, this means that the file in the filesys‐
2206 tem will loose all its EA set. The FSA cannot
2207 be 'removed' from a filesystem and may not al‐
2208 ways have a default value, thus this action
2209 does not modify FSA at all in case of archive
2210 extraction. But in case of merging the FSA are
2211 removed as previously described. As for all
2212 the previous tests, this Attribute operation
2213 is independent of the operation chosen for
2214 file's data (uppercase letters).
2215 d means 'delete'. When a same EA or FSA entry is
2217 found both in the 'in place' and 'to be added'
2218 files, such entry will be absent in the re‐
2219 sulting archive. In other words, when merging,
2220 the EA set and FSA will only contain EA and
2221 FSA entries specific to the 'in place' and
2222 those specific to the 'to be added' file. En‐
2223 tries in common will not be present. When ex‐
2224 tracting a file from an archive, the file on
2225 filesystem will have its EA set enriched by
2226 entries of the 'to be added' file that are new
2227 to the 'in place' file. The other EA entries
2228 (which are thus present in both archive and
2229 filesystem) will be removed from the set,
2230 which the other FSA will stay untouched (FSA
2231 cannot be "removed" from a filesystem, nor
2232 they always have a default value).
2233 * is valid for both EA and data. It tells that
2235 the action is not yet defined at this step of
2236 the evaluation and that further evaluation is
2237 required (see the 'chain' operator below).
2238 A means 'Ask for user decision'. This uppercase
2240 letter concerns Data overwriting. An applica‐
2241 tion interaction let the user define the ac‐
2242 tion for each file in conflict. Note, that
2243 this action if used alone may become very bor‐
2244 ing or painful. The idea is to use it in con‐
2245 ditional statements (which are described be‐
2246 low) to have dar ask for only non obvious
2247 cases.
2248 a means 'Ask for user decision'. This lowercase
2250 letter is the equivalent for EA and FSA of the
2251 'A' action. It is intended to be used in the
2252 same conditional statements described below.
2253 An action is thus a couple of letters, the first
2255 being uppercase (for file's data) the second being
2256 lowercase (for file's EA and FSA). When -/ option
2257 is not given, the action is equivalent to '-/ Oo',
2258 making dar proceed to file, EA and FSA overwriting.
2259 This is to stay as close as possible to the former
2260 default action where neither -n nor -w where speci‐
2261 fied. Note that -w option stays untouched, in con‐
2262 sequences, in this default condition for -/ option,
2263 a confirmation will be asked to the user before dar
2264 proceed to any overwriting. The former -n option
2265 (still used to handle slice overwriting) can be re‐
2266 placed by its equivalent '-/ Pp' for resolving file
2267 overwriting conflict (never overwrite). Here fol‐
2268 lows some examples of actions, all these are done
2269 for any entry found in conflict during archive
2270 merging or archive extraction, we will see further
2271 how to define conditional actions.
2272 -/ Rr
2274 will lead dar to remove any file from filesys‐
2275 tem that ought to be restored(!). Note the ac‐
2276 tion for EA/FSA is useless, the EA and FSA
2277 will always be erased as well as data using
2278 'R'. Thus '-/ Rp' would lead to the same re‐
2279 sult.
2280 -/ Po
2282 will keep data of the 'in place' file and EA
2283 and FSA set from the 'to be added' file.
2284 -/ Ss
2286 Using this option when merging an archive with
2287 itself (used both as archive of reference (-A
2288 option) and auxiliary archive of reference (-@
2289 option) ) will provide the same action as an
2290 archive isolation of the archive of reference,
2291 but using twice more memory (so keep using the
2292 isolation operation as before! Here this is
2293 just an illustration of the possibility)
2294 As seem previously -u and -U options can be used to
2296 filter which EA entry to consider and which to ig‐
2297 nore. The question here is to explain how this fil‐
2298 tering mechanism interacts with the different poli‐
2299 cies we just presented above. For files that are
2300 not in conflict (found only as 'in place' or as 'to
2301 be added'), only the EA entries matching the EA
2302 filter are kept. For files in conflict, the over‐
2303 writing policy is evaluated first, then the filter‐
2304 ing mechanism is applied *after* it. Thus for exam‐
2305 ple, using the following [ -/ "Po" -u "*test" ],
2306 when merging two archives, only EA ending with
2307 "test" will be retained, and when a conflict takes
2308 place, this "*test" ending EA will be taken from
2309 the 'to be added' file if it has some EA of that
2310 type, its other EA entry will be ignored as well as
2311 any EA entry of the 'in place' file even those end‐
2312 ing by "test". At restoration in using the same op‐
2313 tions, file without conflict will get restored but
2314 only EA entry ending with "test" will be restored,
2315 and for file with conflict (already present in
2316 filesystem), EA set of file in filesystem will be
2317 removed and replaced the EA entries of the file in
2318 archive that ends by "test", if some exist.
2319 the situation is similar with FSA family scope and
2321 overwriting policy. Only FSA of a family present in
2322 the scope will be retained, the overwriting policy
2323 acts first then the FSA scope is applied. Note how‐
2324 ever that any FSA present on filesystem and ex‐
2325 cluded from the FSA scope are not touched.
2326 Well, now let's see how to bring some more fun us‐
2328 ing conditional statements in all these actions.
2329 The structure to use is the following:
2330 {<condition>}[<action if condition is true>]
2332 This syntax let you place an action (as the
2333 ones we saw just above) inside the brackets
2334 '[' and ']' (for example [Pp]) that will take
2335 effect only if the evaluation of the <condi‐
2336 tion> is true. Stated that a such statement
2337 is a new type of action, you may have guessed
2338 that you may use it recursively: {<condi‐
2339 tion1>}[{<condition2>}[<action>]).
2340 Well so far it seems useless. But instead of the
2342 "if <condition> then <action> else <action>" para‐
2343 digm common to programming languages, due to the
2344 command line context it has been chosen to instead
2345 use and implicit "OR" operator between actions.
2346 Thus you can "stack" conditional statements this
2347 way: {<condition1>}[<action1>] {<condition2>}[<ac‐
2348 tion2>] <action3>. In this example, if <condition1>
2349 is true then <action1> will be used, ELSE if <con‐
2350 dition2> is true then <action2> will be used ELSE
2351 <action3> will be used. This leads to the same
2352 possibilities as what is available with programming
2353 languages, but with a slightly more simple syntax.
2354 Seen this, the recursion of conditional syntax is
2355 more interesting. For readability, you are allowed
2356 to add any space or tab in the overwriting policy,
2357 but the resulting overwriting policy must be given
2358 as a single argument to dar, thus the use of quotes
2359 (either simple ´arg´ or double "arg") is necessary.
2360 The last operator we will see is the 'chain' opera‐
2362 tor. Once an expression is evaluated, the resulting
2363 couple of action may contain an '*' (undefined ac‐
2364 tion for EA or data). Further evaluation must be
2365 done. The chain operator which is represented by a
2366 semicolon ';' let one to separate several indepen‐
2367 dent expressions that will be evaluated in turn up
2368 to the time the couple of action is fully defined.
2369 Once an action (for EA or for Data) is defined, it
2370 can be redefined by a subsequent evaluation in the
2371 chain, however if the action is defined it cannot
2372 be set back to undefined, thus '*' will never over‐
2373 write a previously defined action. If at the end of
2374 the policy the couple of action is not fully de‐
2375 fined, the 'preserve' action is used ('P' or 'p'
2376 depending on which of EA or Data is left unde‐
2377 fined). Here follow a example of syntax:
2378 -/ "{<condition1>}[P*] O* ; {<condition2>[*p] *o} ;
2380 Rr"
2381 The first expression will evaluate to either
2382 P* or O*. At this step, as the action is not
2383 completely defined, the second part of the
2384 chain is evaluated, It will end with either *p
2385 or *o. In any case, we have after this second
2386 statement of the chain a fully defined action
2387 for both data and EA (either Pp, Po, Op or
2388 Oo). Thus the evaluation stops here and the
2389 "Rr" policy will never be evaluated.
2390 We now have one last thing to see: the available
2392 conditions (what to place between braces '{' and
2393 '}'). Conditions are defined each by a letter,
2394 eventually followed by an argument between paren‐
2395 thesis. The usual logical operators are available:
2396 negation (!), conjunction (&) disjunction (|).
2397 These characters must be escaped or quoted to not
2398 be interpreted by the shell when used on command-
2399 line. In particular the '!' under most shell must
2400 be quoted and escaped (-/ '{\!R}[..]..', The escape
2401 character '\' is not necessary inside DCF files
2402 (those given to -B option) as no shell is used to
2403 interpret these files. To these usual operators has
2404 been added a new one: the "inversion" operator,
2405 noted '~'. Like the negation, it is an unary opera‐
2406 tor but unlike the negation, it inverses the roles
2407 of 'in place' and 'to be added' for the evaluation,
2408 which is slightly different from taking the nega‐
2409 tion of the result of the evaluation. All these op‐
2410 erators follow the usual precedence: unary opera‐
2411 tors ('!' and '~') are evaluated first, then the
2412 conjunction '&' then the disjunction '|'. To over‐
2413 ride this, you can use parenthesis '(' and ')' in‐
2414 side the condition. Over these logical operators,
2415 the conditions are based on atomic operator that
2416 compare the 'in place' file to the 'to be added'
2417 file. Here they follow:
2418 I true only if the 'in place' entry is an inode.
2420 This condition does not have any consideration
2421 toward the to be added object. Note that ~I
2422 can be used to check the nature of the 'to be
2423 added' object. A 'detruit' entry, which record
2424 the fact that a file has been removed since
2425 the archive of reference, is not an inode for
2426 example, and the only type of entry that is
2427 not an inode is a 'detruit'. Thus you can de‐
2428 fine an action on 'detruit' objects using the
2429 "!I" expression for the 'in place' entry and
2430 "!~I" for the 'to be added' entry.
2431 D true only if the 'in place' entry is a direc‐
2433 tory. To know whether the 'to be added' is a
2434 directory or not, one would use the "inver‐
2435 sion" operator: ~D
2436 F true only if the 'in place' entry is a plain
2438 file (true also if this plain file is a 'hard
2439 link', that's it if its inode is linked sev‐
2440 eral times to the directory tree)
2441 H true only if the 'in place' entry is an inode
2443 linked several times to the directory tree (=
2444 hard link) it may be a plain file, a Unix
2445 socket, a pipe, char device, a block device
2446 for example.
2447 A same as H but the current 'in place' entry is
2449 the first link we meet pointing to that hard
2450 linked inode.
2451 R true if the 'in place' entry is more recent
2453 than or of same date as the 'to be added' en‐
2454 try. The last modification date [aka mtime] is
2455 used for this comparison. If the 'to be added'
2456 entry is not an inode (and thus has no mtime),
2457 the 'in place' is considered to be more recent
2458 than the 'to be added' entry. Same thing if
2459 the 'in place' entry is not an inode (and has
2460 no mtime available for comparison), it is here
2461 too assumed to be more recent.
2462 R(<date>)
2464 true if the 'in place' entry is more recent
2465 than or of the same date as the fixed <date>
2466 given in argument. No consideration is done
2467 toward the 'to be added' element. The <date>
2468 format is the same as the one used with -af
2469 option. If an entry has no mtime (it is not an
2470 inode for example) it is assumed an virtual
2471 mtime of zero.
2472 B true only if both 'in place' and 'to be added'
2474 are plain file (hard linked or not) and if the
2475 'in place' file's data is larger or equal to
2476 the 'to be added' file's data. If one or both
2477 entry are not plain files (or hard link to
2478 plain file) and thus the file size comparison
2479 is not possible, the 'in place' entry is as‐
2480 sumed to be 'bigger' than the 'to be added'
2481 entry.
2482 S true only if the 'in place' data is saved in
2484 the archive (not marked as unchanged nor
2485 marked as only inode metadata changed, since
2486 the archive of reference). Note that while ex‐
2487 tracting files from an archive, the 'in place'
2488 file is the one in the filesystem, which al‐
2489 ways has its data 'saved' (from libdar point
2490 of view). The 'inversion' of this atomic oper‐
2491 ator ~S may still be interesting in the con‐
2492 text of restoration.
2493 Y true only if the 'in place' data is saved but
2495 dirty (plain file having its data changed at
2496 the time it was read for backup). Note, that
2497 restoring in sequential read mode, it is not
2498 possible to known whether a file is dirty (it
2499 is possible to know it once having read its
2500 data, but sequential reading does not allows
2501 then to skip forward to get the dirty state of
2502 the file and skip backward to eventually re‐
2503 store that file, depending on the overwriting
2504 policy result).
2505 X true only if the 'in place' data is a sparse
2507 file
2508 T true only if the 'in place' and 'to be added'
2510 entries are of same type (plain file, Unix
2511 socket, named pipe, block device, char device,
2512 symlink, directory, 'detruit' (which stands
2513 for file deleted since the archive of refer‐
2514 ence was done), and so on). Note that the num‐
2515 ber of links to inode (i.e. whether this is a
2516 hard links or not) is not taken into account.
2517 L true only if the 'in place' entry has delta
2519 signature associated with it.
2520 e true if the 'in place' entry has EA (may they
2522 be saved or just recorded as existing).
2523 r true if the 'in place' entry has more recent
2525 or equal dated EA to the 'to be added' entry.
2526 If 'to be added' has no EA or is even not an
2527 inode, true is returned. If 'in place' has no
2528 EA or is even not an inode, true is returned
2529 unless 'to be added' has some EA. The compari‐
2530 son is done on ctime dates.
2531 r(<date>)
2533 true if the 'in place' entry has more recent
2534 or equal dated EA to the fixed <date> given in
2535 argument. No consideration is done toward the
2536 'to be added' element. The <date> format is
2537 the same as the one used with -af option. If
2538 an entry has no date (ctime date) (when it is
2539 not an inode for example) it is assumed an
2540 virtual ctime of value zero.
2541 m true only if 'in place' has more or equal num‐
2543 ber of EA entry in its set of EA than 'to be
2544 added' has. If an entry has not EA or is not
2545 even an inode, it is assumed it has zero en‐
2546 try. The comparison is done on this number.
2547 Note that the number of EA entry is not the
2548 size used to store these entries. For example,
2549 the EA entry "user.test" counts for 1, what‐
2550 ever is the length of the value associated to
2551 it.
2552 b true if the 'in place' entry has bigger EA set
2554 or equal size EA set than the 'to be added'
2555 entry. If an entry has no EA or is even not an
2556 inode, it is assumed that it has a zero byte
2557 length EA set. The comparison is done on this
2558 number in that case. Note that the comparison
2559 is done on the bytes used to store the whole
2560 EA set associated to a given file.
2561 s true if the 'in place' entry is an inode (or a
2563 hard linked inode) and has its EA saved in the
2564 archive of reference, not only marked present
2565 but unchanged since last backup. This test
2566 does not take the 'to be added' entry into ac‐
2567 count.
2568 Well, you've seen that uppercase letter are kept
2570 when comparison is based on the inode or data while
2571 lowercase letter is used for atomics based on EA.
2572 Now that we have completed our tour of this feature
2573 let's see some examples:
2574 -/ Pp
2576 as seen previously this is what does -n option
2577 for files when no overwriting policy is de‐
2578 fined, which avoids any overwriting for Data
2579 as well as for EA.
2580 -/ "{!T}[Pp] {R}[{r}[Pp]Po] {r}[Op] Oo"
2582 Space and tabs are allowed to ease readabil‐
2583 ity. Here the policy stands for: If files in
2584 conflicts are not of the same type then keep
2585 Data and EA of the entry 'in place'. Else if
2586 'in place' has a more recent data then if 'in
2587 place' has more recent EA then keep both its
2588 Data and EA, else keep only its Data and over‐
2589 write its EA. Else (if 'in place' has not the
2590 more recent data), if it has the more recent
2591 EA then overwrite the data but keep its EA,
2592 else overwrite both its data and EA. This
2593 policy tends to preserve the most recent data
2594 or EA, but it does not take into account the
2595 fact that EA or Data is effectively saved into
2596 the archive of just marked as unchanged since
2597 the archive of reference.
2598 -/ "{!T}[{~D}[Oo] Pp]"
2600 If entries are not of the same type, if the
2601 'to be added' entry is a directory then we
2602 keep it and overwrite the 'in place' entry,
2603 else we keep the 'in place' entry. If entry
2604 are of same type, the policy does not provide
2605 any action, thus the default action is used:
2606 "Pp". You can change this default action eas‐
2607 ily using a chain operator:
2608 -/ "{!T}[{~D}[Oo] Pp] ; Aa"
2610 In this case instead, if entry are of the same
2611 type, the user will be asked what to.
2612 -/ "{!T|!I}[{R}[Pp] Oo] {I&~I}[{S}[{~S}[{R}[P*] O*]
2614 P*] {~S}[O*] {R}[P*] O* ; {s}[{~s}[{r}[*p] *o] *p]
2615 {~s}[*o] ] {r}[*p] *o"
2616 Well this may seems a bit too complex but just
2617 see it as an illustration of what is possible
2618 to do: If both 'in place' and 'to be added'
2619 are not of the same type we keep data and EA
2620 of the most recent file (last modification
2621 date). Else, both are of the same type. If
2622 both are inode we evaluate a two expressions
2623 chain (expressions are separated by a semi‐
2624 colon ';') we will see in detail further. Else
2625 if they are of same type but are not inode we
2626 take the EA and data of the most recent entry
2627 (this is the last 10 chars of the string).
2628 Well, now let's see the case of inode: The
2629 first expression in the chain sets the action
2630 for data and keep the action for EA undefined.
2631 While the seconds, is the exact equivalent but
2632 instead it leaves the action for data unde‐
2633 fined '*' and set the action for EA. These two
2634 expressions follow the same principle: If both
2635 entries are saved (by opposition to be marked
2636 as unchanged since the archive of reference)
2637 in the archives, the most recent EA/Data is
2638 kept, else, the one of the inode that is saved
2639 is kept, but if none is saved in the archive
2640 the most recent entry (mtime/ctime) is kept.
2641 -^, --slice-mode perm[:user[:group]]
2644 defines the permission and ownership to use for
2645 created slices. By default, dar creates slices with
2646 read and write available for anyone letting the
2647 umask variable disable some privileges according to
2648 user's preferences. If you need some more re‐
2649 stricted permissions, you can provide the permis‐
2650 sion as an octal value (thus beginning by a zero),
2651 like 0600 to only grant read and write access to
2652 the user. Be careful not to avoid dar writing to
2653 its own slices, if for example you provide permis‐
2654 sion such as 0400. Note also that the umask is al‐
2655 ways applied thus specifying -^ 0777 will not grant
2656 word wide read-write access unless your umask is
2657 0000.
2658 -_, --retry-on-change count[:max-byte]
2660 When a file has changed at the time it was read for
2661 backup, you can ask dar to retry saving it again.
2662 By default a file can be re-saved up to 3 times
2663 (this is the 'count' field), you can set it to zero
2664 to disable this feature. In option the overall max‐
2665 imum amount of byte allowed to be wasted due to
2666 retry changing file's backup can be given after a
2667 colon character (:), this is the 'max-byte' field.
2668 By default (no --retry-on-change option specified)
2669 a limit of 1 wasted byte is allowed which is the
2670 mininum. Specifying zero for max-byte set no limit
2671 on the amount of wasted bytes (same as if no 'max-
2672 byte' was specified), each changing file is then
2673 saved up to 'count' times if necessary.
2674 A file is considered as changed when the last modi‐
2676 fication time has changed between the time the file
2677 has been opened for backup and the time it has been
2678 completely read. In some situation it is not possi‐
2679 ble to replace the already saved data for a file
2680 (writing archive to a pipe for example), in that
2681 situation only, a second copy of the file is added
2682 just after the first previous try which leads that
2683 previous try to becomes inaccessible, however it
2684 holds some place in the archive, where from the
2685 designation of "wasted bytes". You can remove all
2686 wasted bytes from an archive using the merging/fil‐
2687 tering feature: dar -+ new_arch -A old_arch -ak.
2688 Note: since release 2.5.0, in normal condition no
2690 byte is wasted when a file changed at the time it
2691 was read for backup, except when doing a backup to
2692 pipe (using '-c -' option), except if the beginning
2693 of the modified file is located in a previous slice
2694 and except if slice hashing or strong encryption is
2695 used.
2696 -ad, --alter=decremental
2698 This flag is to be used only when merging two ar‐
2699 chives. Instead of the usual merging where each
2700 files of both archives are added to the resulting
2701 archive with eventually a tie using the overwriting
2702 policy (see -/ option), here the merging builds an
2703 archive which corresponds to the decremental backup
2704 done based on two full backups. the -A backup is
2705 expected to receive the older archive while the -@
2706 is expected to point to the more recent one. If
2707 this option is used, the eventually overwriting
2708 policy is ignored and replaced internally by -/
2709 "{T&R&~R&(A|!H)}[S*] P* ;
2710 {(e&~e&r&~r)|(!e&!~e)}[*s] *p". Additionally, files
2711 found in the newer archive that do not existed in
2712 the older are replaced by a 'detruit' entry, which
2713 marks them to be remove at restoration time. For
2714 more information about decremental backups read the
2715 usage_notes.html file in the documentation. Note
2716 that decremental backup is not compatible with
2717 delta binary.
2718 -asecu, --alter=secu
2720 This option disable the ctime check done by default
2721 during an differential backup: If the ctime of an
2722 plain file has changed since the archive of refer‐
2723 ence was done while all other values stay unchanged
2724 (inode type, ownership, permission, last modifica‐
2725 tion date), dar issues a "SECURITY WARNING", as
2726 this may be the sign of the presence of a rootkit.
2727 You should use the -asecu option to disable this
2728 type of warning globally, if you are doing a dif‐
2729 ferential backup of a just restored data (a differ‐
2730 ential backup with the archive used for restoration
2731 taken as reference). Effectively in that situation,
2732 as it is not possible to restore ctime, the re‐
2733 stored data's ctime will have changed while other
2734 parameters will be unchanged for all restored
2735 files, leading dar to issue a warning for all re‐
2736 stored files. This security check is disabled (im‐
2737 plicitly) if dar is run with -ac option. Last, if a
2738 file has only its EA changed since the archive of
2739 reference was done (new EA, removed EA, modified
2740 EA), the security warning will show (false posi‐
2741 tive).
2742 -., --user-comment "<message>"
2744 This option let the user add an arbitrary message
2745 into the archive header. Warning! this message is
2746 always stored in clear text, even if the archive is
2747 encrypted. You can see the message inserted in an
2748 archive displaying the archive summary (dar -l <ar‐
2749 chive> -q). Some macro can be used inside the <mes‐
2750 sage>:
2751 %c is replaced by the command line used. Note
2753 that for security, any option related to ar‐
2754 chive encryption is removed (-K, -J, -$, -#,
2755 -*, -%). The command included from a DCF file
2756 (see -B option) are never added by this macro.
2757 As a consequence, if you do not want to see
2758 --user-comment stored in user comments you can
2759 add the --user-comment definition in an in‐
2760 cluded file like ~/.darrc for example.
2761 %d this is the current date and time
2763 %u this is the uid under which dar has been run
2765 %g this is the gid under which dar has been run
2767 %h the hostname on which the archive has been
2769 created
2770 %% the % character.
2772 -3, --hash <algo> With this option set, when creating, isolating,
2774 merging or repairing an archive, beside each gener‐
2775 ated slices an on-fly hash file of the slice is
2776 created using the specified algorithm. Available
2777 algorithm are "md5", "sha1" and "sha512". By de‐
2778 fault no hash file is generated. The hash file gen‐
2779 erated is named based on the name of the slice with
2780 the .md5, .sha1 or .sha512 extension added to it at
2781 the end. These hash files can be processes by
2782 md5sum, sha1sum and sha512sum usual commands
2783 (md5sum -c <hash file>) to verify that the slice
2784 has not been corrupted. Note that the result is
2785 different than generating the hash file using
2786 md5sum or sha1sum once the slice is created, in
2787 particular if the media is faulty: calling md5sum
2788 or sha1sum on the written slice will make you com‐
2789 pute the hash result on a possibly already cor‐
2790 rupted file, thus the corruption will not be seen
2791 when testing the file against the hash at a later
2792 time. Note also that the creation of a hash file is
2793 not available when producing the archive on a pipe
2794 ("dar -c -").
2795 -7, --sign email[,email[,...email]]
2797 When creating, isolating, merging or repairing an
2798 archive with public key encryption (read -K option)
2799 it is also possible to sign it with one or more of
2800 your private key(s). At the difference of the hash
2801 feature above, only the randomly generated key used
2802 to cipher the archive, key that is dropped at the
2803 beginning and at the end of the archive, is signed.
2804 If the archive is modified at some place, that part
2805 will not be possible to decipher, but signature
2806 verification will stay quick and valid, unless the
2807 part that has been tempered is the key inside the
2808 archive in which case signature check will report a
2809 failure and archive will not be readable at all. If
2810 the signature is valid and the archive could be ex‐
2811 tracted without error, the whole archive could be
2812 assumed to be signed by the gnupg key owners, but
2813 read below the security note. See also GNUPGHOME in
2814 the ENVIRONMENT section at the end of this docu‐
2815 ment.
2816 A summary information about the signature informa‐
2818 tion is displayed while listing an archive in sum‐
2819 mary mode "dar -l <archive> -q". For any operation
2820 involving a signed archive, a short message only
2821 shows if the archive is signed an one or more sig‐
2822 nature check failed, no message is displayed in
2823 case of successful signature check. This warning
2824 may be disabled using the --alter=blind-to-signa‐
2825 tures command.
2826 -<, --backup-hook-include <mask>
2828 The mask is applied to path+filename during backup
2829 operation only. If a given file matches the mask, a
2830 user command (see -= option below) will be run be‐
2831 fore proceeding to the backup and once the backup
2832 will be completed. See also -> option below. IMPOR‐
2833 TANT: if using the short option, you need to en‐
2834 close it between quotes: '-<' for the shell not to
2835 interpret the < as a redirection.
2836 -> --backup-hook-exclude <mask>
2838 The mask is applied to path+filename during backup
2839 operation only. If a given file matches the mask,
2840 even if it matches a mask given after -< option, no
2841 user command will be executed before and after its
2842 backup. The -< and -> options act like -g and -P,
2843 they can receive wildcard expression and thus have
2844 their comportment driven by the --alter=globe and
2845 --alter=regex expressions seen above, as well as
2846 the --alter=mask option. Last the --alter=case and
2847 --alter=no-case modify also the way case sensitiv‐
2848 ity is considered for these masks. By default, no
2849 -> or -< option, no file get selected for backup
2850 hook. IMPORTANT: if using the short option, you
2851 need to enclose it between quotes: '->' for the
2852 shell not to interpret the > as a redirection.
2853 -=, --backup-hook-execute <string>
2855 for files covered by the mask provided thanks to
2856 the -< and -> options, the given string is executed
2857 before the backup of that file starts and once it
2858 has completed. Several macro can be used that are
2859 substituted at run time:
2860 %% will be replaced by a literal %
2862 %p will be replaced by the full path under
2864 backup
2865 %f will be replaced by the filename (without
2867 the path)
2868 %u will be replaced by the UID of the file
2870 %g will be replaced by the GID of the file
2872 %t will be replaced by a letter correspond‐
2874 ing to the type of inode: 'f' for plain
2875 file, 'l' for symlink, 'd' for directory,
2876 'c' for char devices, 'b' for block de‐
2877 vices, 's' for sockets, 'p' for pipes,
2878 'o' for doors.
2879 %c and most interesting, %c (c for context),
2881 will be replaced by "start" or by "end"
2882 when the command is executed before or
2883 after the backup respectively.
2884 This way, one can dump a database in a directory just before it is
2885 about to be backed up, and clean it up once the backup has completed.
2886 Note that the masks seen above that drive the execution of this command
2887 can be applied to a directory or a plain file for example. When a di‐
2888 rectory is selected for this feature, the command is logically ran be‐
2889 fore starting (with the context "start") to backup any file located in
2890 that directory or in a subdirectory of it, and once all files in that
2891 directory or subdirectories have been saved, the command is ran a sec‐
2892 ond time (with the context "end"). During that time, if any file do
2893 match the backup-hook masks, no command will be executed for these. It
2894 is assumed that when a directory has been asked for a backup-hook to be
2895 executed this hook (or user command) is prepare for backup all data lo‐
2896 cated in that directory. The environment variable DAR_DUC_PATH also ap‐
2897 plies to these user commands (see -E above, or the ENVIRONMENT para‐
2898 graph below).
2899 -ai, --alter=ignore-unknown-inode-type
2901 When dar meets an inode type it is not aware about
2902 (some times ago, it was the case for Door inode on
2903 Solaris for example, Door inodes are handled by dar
2904 since release 2.4.0), it issues a warning about its
2905 inability to handle such inode. This warning occurs
2906 even if that entry is filtered out by mean of -X,
2907 -I, -P, -g, -[ or -] options, as soon as some other
2908 entry in that same directory has to be considered
2909 for backup, leading dar to read that directory con‐
2910 tents and failing on that unknown inode type (fil‐
2911 tering is done based on the result of directory
2912 listing). This option is to avoid dar issuing such
2913 warning in that situation.
2914 -8, --delta sig This option can be used for archive backup, isola‐
2916 tion and merging. Important: read also the best
2917 practice paragraph below
2918 Called during a backup operation it leads dar to
2920 create delta signature for each file: If the file
2921 is new or has changed, a signature is computed and
2922 stored beside the file's data, which increases the
2923 archive size. If the file is not new and has not
2924 changed (differential backup context) if an delta
2925 signature is found in the archive of reference (or
2926 isolated catalogue), this signature is copied to
2927 the resulting archive, but not the file's data. If
2928 the reference archive does not hold delta signa‐
2929 ture, a new delta signature is computed based on
2930 the current data found on filesystem for that file
2931 and then stored in the resulting archive. But in
2932 any case, without --delta sig the resulting archive
2933 will hold no delta signature. Note that delta sig‐
2934 nature transfer is not possible when the archive of
2935 reference is read in sequential mode, thus delta
2936 signature is disabled when the archive of reference
2937 is read in sequential mode.
2938 For isolation and merging operations, the behavior
2940 is slightly different: --delta sig option let dar
2941 transfer existing delta signatures from the origi‐
2942 nal archive to the isolated/merged one but does not
2943 lead dar to compute delta signatures for files that
2944 do not have one, unless one of the --include-delta-
2945 sig or --exclude-delta-sig option is specified; in
2946 that case the delta signatures are trans‐
2947 fered/dropped and if not present calculated accord‐
2948 ingly to these mask options. However note that it
2949 is not possible to calculate delta signature for
2950 unsaved files in the archive of reference (because
2951 the archive of reference does not hold their data)
2952 as well as for fully saved files when merging is
2953 performed keeping files compressed (see -ak op‐
2954 tion). Another restriction while merging concernes
2955 sparse files, it is not possible to calculate bi‐
2956 nary signature for file stored as sparse files, but
2957 if sparse file detection mechanism is activated at
2958 merging time, delta signature can be calculated for
2959 sparse files too even if it is missing in the ref‐
2960 erence archive. In short: if you want recalculation
2961 of delta signature while merging, do not keep file
2962 compressed (do not use -ak option) and if you want
2963 to avoid having sparse files excluded from the
2964 delta signature recalcutation, activate sparse file
2965 detection (use -ah option). Delta signature trans‐
2966 fer is not possible for on-fly isolation, you need
2967 to do normal archive isolation to obtain an iso‐
2968 lated catalogue with delta signatures.
2969 -8, --delta sig:<function>:<multiplier>[:<divisor>[:<min>[:<max>]]]
2971 this variant of '--delta sig' option let you spec‐
2972 ify the block length used to build delta signa‐
2973 tures. Larger values reduce CPU load required to
2974 build delta signature, but also lead to less accu‐
2975 racy when computing delta binary, which means
2976 larger delta patch and more data saved when a file
2977 has changed. The block len is calculated following
2978 the formula: block_len = function(filesize)*multi‐
2979 plier/divisor If this calculated value is lower
2980 than "min", it is set to min. If the calculated
2981 value is greater than "max" it is set to max unless
2982 max is set to zero in which case the value is kept
2983 as is. Of course "divisor" cannot be null. The
2984 available functions are:
2985 fixed
2987 always returns 1, in other terms, the block
2988 size is independent from the file size to
2989 build delta signature for
2990 linear
2992 returns the filesize. here, you will most of
2993 the time use 1 for multiplier and increase di‐
2994 visor to at least 10 for it makes sense
2995 log2 returns the upper rounded power of 2 closest
2997 to the file size (base 2 logarithm).
2998 square2
3000 returns the approximated value of the square
3001 root of the file size. Note that for better
3002 performance and as accuracy is not important
3003 here, this function is implemented as
3004 exp2(log2(filesize)/2) where exp2 and log2 are
3005 based on the integer left and right bit shift
3006 operations.
3007 square3
3009 returns the approximated value of the cube
3010 root of filesize, implemented as
3011 exp2(log(filesize)/3)
3012 All numerical fields can receive multiplier suffix
3013 (k, M, ...) for more details about these suffixes,
3014 see -s option description. If not specified "max"
3015 defaults to zero (no maximum value defined). If not
3016 specified "min" defaults to RS_DEFAULT_BLOCK_LEN
3017 (see below for details on this symbol). If not
3018 specified "divisor" defaults to 1. Using "--delta
3019 sig" without additional fields is equivalent to us‐
3020 ing --delta sig:fixed:RS_DEFAULT_BLOCK_LEN where
3021 "RS_DEFAULT_BLOCK_LEN" is taken from librsync and
3022 is today equal to 2048 bytes (which may well change
3023 in the future by the way if librsync maintainers
3024 decide to do so).
3025 -{, --include-delta-sig <mask>
3028 By default when --delta sig is provided, delta sig‐
3029 natures are computed for all files enrolled in the
3030 backup operation (see also --delta-sig-min-size op‐
3031 tion). This option and --exclude-delta-sig allow
3032 restricting the files for which delta signature
3033 have to be calculated in that situation. The mask
3034 applies to the whole path, the same way as -P/-g
3035 options do.
3036 For merging or isolation operations, when --delta
3038 sig is used no delta signature is computed only ex‐
3039 isting ones are transferred as is without restric‐
3040 tion. To change that behavior and thus either drop
3041 or add delta signature to files that did not have
3042 one in the archive of reference, specify an combi‐
3043 nation of --include-delta-sig or --exclude-delta-
3044 sig with --delta sig. This option as well as --ex‐
3045 clude-delta-sig can be used several times on com‐
3046 mand-line but are useless/ignored without --delta
3047 sig. See also -am, -ag and -ar options.
3048 -}, --exclude-delta-sig <mask>
3050 Files matching the given mask will never have their
3051 delta signatures calculated, may --delta sig option
3052 be specified or not. See also --include-delta-sig
3053 option above and --delta-sig-min-size below.
3054 -6, --delta-sig-min-size <number>
3056 For archive merging, isolation and creation, when
3057 dar has to (re-)calculate delta signatures, this
3058 option modifies the minimum file size (in bytes)
3059 below which dar never calculates delta signatures.
3060 This option acts independently from --include-
3061 delta-sig and --exclude-delta-sig , however it can‐
3062 not re-activate delta signature recalculation by
3063 itself while merging/isolating an archive, it re‐
3064 quires either --exclude-delta-sig or --include-
3065 delta-sig option to be active in that situation.
3066 For archive backup instead, it does not require
3067 --exclude-delta-sig nor --include-delta-sig to act,
3068 but only need --delta sig option to be set. By de‐
3069 fault, this minimum size is 10 kio. The same option
3070 suffixes (k for kilo, M for mega, G for giga, T,
3071 ...) as the ones available with --slice option can
3072 be used here too. Using zero as argument gives the
3073 same result as not specifying this option at all
3074 (default size).
3075 -8, --delta no-patch
3077 In the context of differential backup, this option
3078 leads dar to never consider files for delta binary
3079 even if delta signatures are present. By default
3080 delta binary (rsync-like) operation is performed
3081 when a file has changed since the archive of refer‐
3082 ence was made *and* if a delta signature could be
3083 found in the archive of reference for that file (or
3084 in the isolated catalogue used as reference for the
3085 incremental/differential backup). If no delta sig‐
3086 nature could be found or if --delta no-patch is
3087 used, the normal behavior is done, which consist of
3088 saving that whole file in the archive. Note that if
3089 the archive of reference is read in sequential
3090 mode, the --delta no patch is required, dar will
3091 refuse to execute the operation: sequential read
3092 and binary delta are not compatible, because read‐
3093 ing in sequential mode an archive does not let
3094 skipping backward to fetch the delta signature nec‐
3095 essary to setup a delta patch.
3096 Binary delta options usage and best practices:
3098 First it must be understood that binary delta has advantages
3099 (less storage requirement) and drawbacks: data corruption has a
3100 wider impact on the ability to restore a given file, restoration
3101 of incrementally backed up file may ask much more than one ar‐
3102 chive to be used. To limit the impact of the first drawback, dar
3103 binary delta is done per file, not globally on the total amount
3104 of saved data. You are also strongly encouraged to protect your
3105 backups with parity data using par2 (see dar_par.dcf file in the
3106 examples section of the documentation). Adding par2 data will
3107 increase storage requirement by a little, but usually much less
3108 than the amount gained using binary delta. Last drawback, binary
3109 delta relies on checksum (contained in the delta signature) and
3110 not on the real data to build the binary delta. There is chances
3111 that two different files provide the same checksum, even if the
3112 chances are very low, probability is not null. The consequence
3113 is that using binary delta the risk exists that the restored
3114 data do not match the original data and this will not be noticed
3115 by the librsync library on which libdar relies for that feature.
3116 Dar adds a second level of checksum, to detect data corruption
3117 inside the archive and to check that the file the delta patch is
3118 about to be applied is the expected base file, this reduces the
3119 risk of "collision" but does not remove it completely. After
3120 these warnings, let's now see the best practices about binary
3121 delta:
3122 Once a full backup has been done using --delta sig, any differ‐
3124 ential backup made based on this archive will use binary diff
3125 for file having a delta signature present in the full backup. If
3126 you always make differential (not incremental) backups based on
3127 such full backup you have nothing more specific to do in regard
3128 to binary delta, dar will handle it transparently. In particular
3129 you do not need to invoke --delta sig at subsequent backup, this
3130 saves space in differential archives as well as CPU cycles.
3131 However, When doing incremental (not differential) backups this
3133 time, if you want to have dar using binary delta at each subse‐
3134 quent incremental backup, delta signatures must be present in
3135 the successive incremental backups. This is done by using
3136 --delta sig option for each new incremental backup created.
3137 If you were used to use isolated catalogues before release 2.6.0
3139 you can add --delta sig option while isolating a catalogue from
3140 an archive containing delta signatures. Such isolated catalogue
3141 will be much larger than what it can be without this option but
3142 it can be used as reference for a new differential/incremental
3143 backup letting dar relying on binary delta. Isolated catalogue
3144 generated without --delta sig do not contain delta signature and
3145 cannot lead to binary delta operation when used as reference for
3146 an incremental or decremental backup.
3147 Another way of doing differential backup is to make a normal
3149 full backup without --delta sig option, and only add delta sig‐
3150 natures at archive isolation time using --delta sig --include-
3151 delta-sig "*" options. Binary delta signature will then be cal‐
3152 culated based on the saved files. Then, using the resulting iso‐
3153 lated catalogue as reference dar will be able to proceed to bi‐
3154 nary delta for the differential backup. If this works pretty
3155 well for differential backup (or the first incremental backup)
3156 which is based on a full backup, for incremental backup this is
3157 less adapted as a file that has not changed since the archive of
3158 reference was made does not hold any data and calculating the
3159 delta signature is not possible. The first method explained two
3160 paragraphs above is better as the incremental backup fetches the
3161 already calculated delta signature from the reference to keep it
3162 in the resulting incremental backup, so even without data, bi‐
3163 nary delta is still possible.
3164 Isolated catalogue using the --delta sig option, can still be
3166 used as backup of the internal catalogue they have been isolated
3167 from. However, as they hold their own delta signatures, such
3168 isolated catalogue can only have access to its own ones, not to
3169 those of the archive of reference. In particular when testing an
3170 archive (-t option), using -A option to rescue the archive in‐
3171 ternal catalogue using an isolated catalogue containing delta
3172 signatures, dar will not be able to check that there is no cor‐
3173 ruption in the delta signatures fields of the archive under
3174 test. For that type of testing either use the internal catalogue
3175 of the archive or rescue it using an isolated catalogue built
3176 without --delta sig option.
3177 -az, --alter=zeroing-negative-dates
3179 dar/libdar saves dates as a number of seconds since
3180 the beginning of year 1970, the well known "Unix
3181 time" (plus a positive fraction for sub-second
3182 time-stamping). Some systems may return a negative
3183 number as the Unix time of a given file (files hav‐
3184 ing dates before 1970), in that situation by de‐
3185 fault and since release 2.5.12 dar pauses and asks
3186 the user whether to assume the date as being zero.
3187 But with -az option, dar/libdar automatically as‐
3188 sumes such negative dates to be zero and just issue
3189 a warning about the problem met.
3190 -\, --ignored-as-symlink <absolute path>[:<absolute path>[:...]]
3192 When dar reaches an inode which is part of this
3193 provided colon-separated list, if this inode is not
3194 a symlink this option has no effect, but if it is a
3195 symlinks dar saves the file the symlink points to
3196 and not the symlink itself as dar does by default.
3197 In particular, if the pointed to inode is a direc‐
3198 tory dar recurses in that directory. You can also
3199 pass this list as argument to the DAR_IG‐
3200 NORED_AS_SYMLINK environment instead of using --ig‐
3201 nored-as-symlink (which takes precedence over the
3202 environment variable).
3203 -'\'', --modified-data-detection=any-inode-change, --modified-data-de‐
3205 tection=mtime-and-size
3206 Before release 2.6.0, during a differential/incre‐
3207 mental backup if any part of a file's inode meta‐
3208 data changed (ownership, permission, ...) even if
3209 the mtime (last modification time) and file size
3210 stood the same, dar had no choice than resaving the
3211 whole file for backup to record the metadata
3212 changes. This lead to a waste of backup time and
3213 space if in fact and for example only the ownership
3214 had been modified. You can still keep this histori‐
3215 cal behavior by invoking the --modified-data-detec‐
3216 tion=any-inode-change option. Since release 2.6.0
3217 a new entry status ("inode-only") has been added.
3218 Dar can now re-save only metadata when the inode
3219 change does not concern the data. To know whether
3220 the data has changed or not, by default (no --modi‐
3221 fied-data-detection option given) dar looks at
3222 mtime and at file's size only. Specifying --modi‐
3223 fied-data-detection=mtime-and-size (which is the
3224 default behavior) can be used to revert the action
3225 of --modified-data-detection=any-inode-change for
3226 example when playing with included files (DCF
3227 files): the latest met takes precedence.
3228 -T, --kdf-param <integer>[:<hash algo>]
3230 At the difference of the listing context (see be‐
3231 low), in the context of archive creation, merging
3232 and isolation, -T option let you define the itera‐
3233 tion count used to derive the archive key from the
3234 passphrase you provided (archive encryption con‐
3235 text) and the hash algorithm used for that deriva‐
3236 tion. -T has another older meaning when doing ar‐
3237 chive listing, but due to the lack of free charac‐
3238 ter to create a new CLI option, there was no other
3239 choice than recycling an existing option not used
3240 in the context of archive creation/merging/isola‐
3241 tion. The consequence is that the -T option must
3242 appear after the -+/-c/-C options for the opera‐
3243 tional context to be known at the time the -T op‐
3244 tion is met and its --kdf-param meaning to be taken
3245 into account. As --kdf-param is an alias to -T,
3246 this long form of this option must also be found
3247 after the use of either -c, -C or -+ option.
3248 Without --kdf-param the KDF fonction uses 200,000 iterations for
3250 md5, sha1 and sha512 (PBKDF2 from PKCS#5 v2) but only 10,000 for
3251 argon2. If libargon2 is present, this is the default hash algo‐
3252 rithm, else sha1 is used with PBKDF2. Valid parameters are
3253 "sha1", "sha512", "md5" and "argon2" for the hash algorithms and
3254 a value greater than 1 for the iteration count. However it is
3255 advise to use a value equal or greater to the default values
3256 mentionned previously. The suffixes described for -s option are
3257 also available here (k, M, G, T, P, ...) however pay attention
3258 to the -aSI/-abinary mode which default to binary, in which case
3259 "-T 1k" is equivalent to "-T 1024". Example of use: --kdf-param
3260 20k:argon2
3261 RESTORATION SPECIFIC OPTIONS (to use with -x)
3263 -k[{ignored|only}], --deleted[={ignore|only}]
3265 Without argument or with the "ignore" argument,
3266 this option leads dar at restoration time to not
3267 delete files that have been deleted since the
3268 backup of reference (file overwriting can still oc‐
3269 cur). By default, files that have been destroyed
3270 since the backup of reference are deleted during
3271 restoration, but a warning is issued before pro‐
3272 ceeding, except if -w is used. If -n is used, no
3273 file will be deleted (nor overwritten), thus -k is
3274 useless when using -n. If -/ option is used, this
3275 option without argument is ignored! With the "only"
3276 argument, this option only consider files marked as
3277 to be removed in the archive to restore, no file
3278 are restored but some file are removed. When -konly
3279 (or --deleted=only) is used, the -/ option is ig‐
3280 nored (at the opposition of the "--deleted=ignore"
3281 option which is ignored when the -/ is used). Of
3282 course "--deleted=ignore" and "--deleted=only" are
3283 mutually exclusive, because if both of them were
3284 available at the same time dar would do nothing at
3285 all.
3286 -r, --recent only restore files that are absent or more recent
3288 than those present in filesystem. If -/ option is
3289 used, this option is ignored!
3290 -f, --flat do not restore directory structure. All files will
3292 be restored in the directory given to -R, if two
3293 files of the same name have to be restored, the
3294 usual scheme for warning (-w option) and overwrit‐
3295 ing (-n option) is used. No rename scheme is
3296 planned actually. When this option is set, dar does
3297 not remove files that have been stored as deleted
3298 since last backup. (-f implicitly implies -k).
3299 -ae, --alter=erase_ea
3301 [DEPRECATED use -/ instead] Drop all existing EA of
3302 files present in filesystem that will have to be
3303 restored. This way, the restored files will have
3304 the exact set of EA they had at the time of the
3305 backup. If this option is not given, a file to re‐
3306 store will have its EA overwritten by those present
3307 in the backup and if some extra EAs are present
3308 they will remain untouched. See the Note concerning
3309 Extended Attributes (EA) above for a detailed ex‐
3310 planation about this behavior. If -/ option is
3311 used, this option is ignored!
3312 -D, --empty-dir At restoration time, if -D is not specified (de‐
3314 fault) any file and directory is restored in regard
3315 to the filtering mechanism specified (see -I, -X,
3316 -P, -g, -[ and -] options). But if -D option is
3317 provided the restoration skips directory trees that
3318 do not contain saved files. This avoid having a
3319 huge empty tree with a few restored files espe‐
3320 cially when restoring a differential archive in an
3321 empty place. Note: This feature cannot work when
3322 --sequential-read is used, as it is not possible to
3323 know whether a directory contains or not some saved
3324 files at the time the directory inode is read from
3325 the archive in sequential reading mode.
3326 -2, --dirty-behavior { ignore | no-warn }
3328 At restoration time, if a file in the archive is
3329 flagged as "dirty" (meaning that it had changed at
3330 the time it was saved), user is asked for confirma‐
3331 tion before restoring it. Specifying "ignore" will
3332 skip those dirty files, while "no-warn" will re‐
3333 store them without user confirmation. This feature
3334 is incompatible with sequential reading mode, in
3335 this mode dar cannot know whether a file is dirty
3336 before having restored it. In consequences, in
3337 --sequential-read, once a file has been restored,
3338 if it is found to be dirty it will be removed un‐
3339 less dirty-behavior is set to "no-warn".
3340 -/, --overwriting-policy <policy>
3342 Overwriting policy can be used for archive restora‐
3343 tion to define when and how file overwriting can
3344 occur. See above the description of this option.
3345 -A, --ref [[<URL>]<path>]/<basename>
3347 The --ref option can be used with an isolated cata‐
3348 logue to rescue an archive that has a corruption in
3349 the catalogue part, see GENERAL OPTIONS above for
3350 more details.
3351 -au, --alter=unix-sockets
3353 Do not restore unix-sockets. By default saved unix
3354 sockets are recreated at restoration time.
3355 -ap, --alter=place Since version 2.7.1 libdar stores the filesystem
3357 root path (given -R option) used when creating a
3358 backup, this is the known as the 'in-place' path.
3359 At restoration time by default, dar uses the pro‐
3360 vided -R option or if not specified uses the cur‐
3361 rent directory as root directory for the restora‐
3362 tion operation. Using -ap option lead dar to read
3363 the in-place path from the backup and restore the
3364 data using this path instead. This option is thus
3365 exclusive with -R option and may lead dar to report
3366 an error if the archive has not stored any in-place
3367 path (older archive format or backup resulting of
3368 the merging of two backups having different in-
3369 place path).
3370 TESTING AND DIFFERENCE SPECIFIC OPTIONS (to use with -t or -d)
3372 -ado-not-compare-symlink-mtime, --alter=do-not-compare-symlink-mtime
3374 With this option set, when comparing a symlink, no
3375 message shows when symlink in archive and symlink
3376 on filesystem do only differ by their mtime. See
3377 also -O option.
3378 -ap, --alter=place is also available as described just above for
3380 restoration options.
3381 No other specific option, but all general options are available except
3383 for example -w which is useless, as testing and comparing only read
3384 data. -A option is available as described in GENERAL OPTIONS to backup
3385 of internal catalogue of the archive (assuming you have a previously
3386 isolated catalogue available).
3387 Doing a difference in sequential read mode is possible but hard linked
3389 inodes can only be compared to the filesystem the first time they are
3390 met, next hard links to this same inode cannot obtain the corresponding
3391 data because skipping backward in sequential read mode is forbidden. In
3392 that situation, the hard links are reported as skipped, meaning that
3393 data comparison could not be performed.
3394 LISTING OPTIONS (to use with -l)
3396 -T, --list-format=<normal | tree | xml | slicing>
3398 By default, listing provides a tar-like output (the
3399 'normal' output). You can however get a tree-like
3400 output, an XML structured output or an output fo‐
3401 cusing on slice(s) where each file's data, EA and
3402 FSA is located in. The option --tree-format is an
3403 alias to --list-format=tree (backward compatibil‐
3404 ity). Note that the files doc/dar-catalog-*.dtd de‐
3405 fine the format of the XML output listing (This
3406 file is also installed under $PREFIX/share/doc)
3407 the -Tslicing option can also be used with isolated
3409 catalogue generated with dar 2.5.0 or above, as
3410 isolated catalogues now contain a copy of the slic‐
3411 ing layout of the archive of reference. However, if
3412 the archive of reference has been re-sliced (using
3413 dar_xform) after the isolated catalogue has been
3414 built, the slicing information would not be cor‐
3415 rect. For that corner case, you can use the -s and
3416 -S options with -Tslicing to specify what are the
3417 new slice sizes of the archive of reference. Last,
3418 -Tslicing and --sequential-read options are not
3419 compatible except for isolated catalogues.
3420 -as, --alter=saved list only saved files
3422 -alist-ea, --alter=list-ea
3424 list Extended Attributes name for each file that
3425 has some.
3426 -ay, --alter=byte, --alter=bytes
3428 by default files size is displayed to occupy the
3429 shortest number of characters by using the largest
3430 unit possible (KiB, MiB, GiB, and so on). With this
3431 option instead, the size is displayed with maximum
3432 precision using the exact number of bytes used for
3433 each file.
3434 -I, -X, -P, -g, -[, -]
3436 can be used to filter file to list base on their
3437 name or path.
3438 -aheader displays the header (when --sequential-read is
3440 used) or the trailer of the archive and then stops.
3441 This archive header/trailer is always in clear text
3442 even when the archive is ciphered. This option is
3443 here to let you access to these fields without pro‐
3444 viding the encryption key.
3445 From the general options it seems only -vm and -b stay useful here.
3447 Note that -vm displays an archive summary first, where a detailed of
3448 information about the archive can be obtained. If you want to display
3449 only this summary use -q with -l option.
3450 displayed fields
3452 [Data] possible values are [ ] or [Saved] or [InRef]
3454 or [DIRTY] or [Inode] or [Delta]. [ ] means
3455 that the data has not been saved because there is
3456 no change since backup of reference. [Saved] means
3457 that the data has been saved completely, and thus
3458 this archive is able to restore the file without
3459 other help. [InRef] was used in archive generated
3460 by dar version 2.3.x and before when isolating a
3461 catalogue from an archive, and means that the file
3462 was saved in the reference archive. [DIRTY] means
3463 that data is saved (like [Saved]) but has changed
3464 at the time dar was reading it for backup, leading
3465 dar to possibly store the file in a state it never
3466 had. [Inode] means only permission ownership and
3467 ctime data changed since the archive of reference
3468 was done is recorded in the archive, the data did
3469 not changed according to the --comparison-field set
3470 or not set. Last [Delta] means the file's data is
3471 saved as a binary delta (or delta patch), which is
3472 much shorter than the full data as what is done
3473 with [Saved]. It also means that you can only re‐
3474 store the file if it exists on filesystem in the
3475 state it had when the archive of reference was
3476 done, for the patch to be possible to apply on it.
3477 This is the case for example if you just restored
3478 this file from the archive of reference.
3479 [D] possible values are [-], [ ] or [D]. [D] means that
3481 delta signature associate with this file is present
3482 in the archive. [ ] means that the file has no as‐
3483 sociated delta signature and thus binary diff will
3484 not be possible for it. [-] is used for non plain
3485 files inodes for which delta signature is not ap‐
3486 plicable.
3487 [EA] possible values are " " (empty string) or [ ]
3489 or [InRef], [Saved] or [Suppr]. It Shows whether
3490 Extended Attributes are present and saved
3491 ([Saved]), are present but not saved ([ ])
3492 which means there is no change since backup of ref‐
3493 erence, if there is no EA saved for this file
3494 (empty string) or if some EA were present in the
3495 archive of reference but none is currently avail‐
3496 able ([Suppr]). [InRef] was used when isolating a
3497 catalogue (release 2.3.x and before) from an ar‐
3498 chive and means that the file was saved in the ref‐
3499 erence archive.
3500 [FSA] Each character represent a FSA Family:
3502 "L" is the first character (L/l/-) representing
3504 ext2/3/4 FSA family
3505 "H" is the second character (H/h/-) representing
3507 HFS+ FSA family
3508 "-" the third character is reserved for future FSA
3510 family and is always a dash for now.
3511 Uppercase means the FSA set is saved, lowercase
3513 means the FSA is present in the archive of refer‐
3514 ence and has not changed since that time. Last a
3515 dash (-) means no FSA of that family has been saved
3516 for that file.
3517 [compr] possible values are [....%] or [-----] or [ ]
3519 or [worse]. Shows if the file has been compressed
3520 ([...%]) and the compression ratio reached "(uncom‐
3521 pressed-compressed)/uncompressed", for example [
3522 33%] means that the compressed data uses only 66%
3523 of the space required to store uncompressed data
3524 (33% of space saved thanks to compression), or if
3525 the file is stored without compression ([ ] see
3526 -m, -Y and -Z options) or if the file is not sub‐
3527 ject to compression because it is not a saved regu‐
3528 lar file ([----]), or if the file takes more space
3529 compressed than its original size ([worse]), due to
3530 compression overhead. Note that 1% compression ra‐
3531 tio brings quite no data reduction, while obviously
3532 98% is a very performant compression (compressed
3533 file takes only 2% of the size required by the un‐
3534 compressed date).
3535 [S] possible values are [ ] or [X]. [X] only applies to
3537 saved plain files, and tells that the file is
3538 stored using sparse file data structure: not all
3539 data is stored, long sequence of zeros are skipped.
3540 This also means that at restoration time, if the
3541 filesystem supports it, holes will be restored. To
3542 store hole information libdar uses escape sequence
3543 (special sequence of byte), but to avoid real data
3544 to be considered as such escape sequence, a special
3545 escape sequence is used when data looks like an es‐
3546 cape sequence. So if a data contains a such escape
3547 sequence, it must be read as if it contains holes
3548 to be able to restore back the data in its original
3549 form. For that reason, in some rare circumstances
3550 (saving an dar archive inside a dar archive without
3551 compression or encryption, for example) a file
3552 without hole may be marked [X] as if it had holes
3553 and will be longer by on byte for each data se‐
3554 quence looking like an escape sequence.
3555 permission
3557 see ls man page. Note that a star (*) is prepended
3558 to the permission string if the corresponding inode
3559 is linked several times to the directory structure
3560 (hard link).
3561 user owner of the file
3563 group group owner of the file
3565 size size in byte of the file (if compression is en‐
3567 abled, the real size in the archive is "compression
3568 rate" time smaller).
3569 date the last modification date of the file. The last
3571 access time is also saved and restored, but not
3572 displayed.
3573 filename The name of the file.
3575 Extended Attributes
3577 When using -alist-ea option, for hard linked inode,
3578 the filename is followed by an integer between
3579 braces: Entries with the same number do point the
3580 the same inode.
3581 Slice(s) In -Tslice mode, each file is given the range of
3583 slices it is located in. If slice size is chosen
3584 particularly small, some slices may contain no
3585 file, EA, FSA data but only tape marks or the in‐
3586 ternal catalogue, leading the aggregation of re‐
3587 ported slices not to cover all available slices of
3588 the archive.
3589
3591 When dar has not been compiled with GNU getopt, which is not present by
3592 default on some systems like FreeBSD, you may lack the optional argu‐
3593 ments syntax. For example "-z" will create a parse error on command-
3594 line, or in -B configuration files. The solution is to explicitly give
3595 the argument. Here follows a list of explicit argument to use in place
3596 of optional ones:
3597 -z must be replaced by -z 9
3599 -w must be replaced by -w d or -w default
3601 -H must be replaced by -H 1
3603 -0 must be replaced by -0 ref
3605 -5 must be replaced by -5 ""
3607 -p must be replaced by -p 1
3609 -v must be replaced by -v all
3611 -k must be replaced by -k ignore
3613 -5 must be replaced by -5 user.libdar_no_backup
3615 -M must be replaced by -M I:/
3617 important ! When using GNU getopt(), optional arguments are available
3619 by sticking the argument to the short option: "-z" for example is
3620 available as well as "-z9". But "-z 9" is wrong, it will be read as
3621 "-z" option and "9", a command line argument (not an argument to the -z
3622 option). In the other side, when using a non GNU getopt this time, "-z"
3623 becomes an option that always requires an argument, and thus "-z 9" is
3624 read as "-z" option with "9" as argument, while "-z9" will be rejected
3625 as a unknown option, and "-z" alone will generate an error as no argu‐
3626 ment is provided. In consequences, you need a space between the option
3627 (like "-z") and its argument (like "9"), when dar does not rely on a
3628 GNU getopt() call, which also imply you to explicitly use arguments to
3629 options listed just above.
3630
3633 dar exits with the following code:
3634 0 Operation successful.
3636 1 Syntax error on command-line or DCF included file
3638 2 Error due to a hardware problem or a lack of memory.
3640 3 Detection of a condition that should never happen, and which
3642 is considered as a bug of the application.
3643 4 Code issued when the user has aborted the program answering a
3645 question from dar. This also happens when dar is not run from
3646 a terminal (for example launched from crontab) and dar has a
3647 question to the user. In that case, dar aborts the same way
3648 as if the user pressed the escape key at the question prompt.
3649 5 is returned when an error concerning the treated data has
3651 been detected. While saving, this is the case when a file
3652 could not be opened or read. While restoring, it is the case
3653 when a file could not be created or replaced. While compar‐
3654 ing, it is the case when a file in the archive does not match
3655 the one in the filesystem. While testing, it is the case when
3656 a file is corrupted in the archive.
3657 6 an error occurred while executing user command (given with -E
3659 or -F option). Mainly because the creation of a new process
3660 is not possible (process table is full) or the user command
3661 returned an error code (exit status different from zero).
3662 7 an error has occurred when calling a libdar routine. This
3664 means the caller (dar program), did not respect the specifi‐
3665 cation of the API (and this can be considered as a particular
3666 case of bug).
3667 8 the version of dar used is based on finite length integers
3669 (it has been compiled with the option --enable-mode=...).
3670 This code is returned when an integer overflow occurred. use
3671 the full version (based in the so called "infinint" class) to
3672 avoid this error.
3673 9 this code indicates an unknown error. The exception caching
3675 code to take care of new exceptions has probably been forgot‐
3676 ten to be update ... this is a minor bug you are welcome to
3677 report.
3678 10 you have tried to use a feature that has been disabled at
3680 compilation time.
3681 11 some saved files have changed while dar was reading them,
3683 this may lead the data saved for this file not correspond to
3684 a valid state for this file. For example, if the beginning
3685 and the end of the file have been modified at the same time
3686 (while dar is reading it), only the change at the end will be
3687 saved (the beginning has already been read), the resulting
3688 state of the file as recorded by dar has never existed and
3689 may cause problem to the application using it. This is known
3690 as a "dirty" file in the archive.
3691
3694 If dar receives a signal (see kill(2) man page) it will take the de‐
3695 fault behavior which most of the time will abruptly abort the program,
3696 except for the following signals:
3697 SIGINT This signal is generated by the terminal when hitting CTRL-C
3699 (with the terminal's default settings), it can also be gener‐
3700 ated with the kill command
3701 SIGTERM This signal is generated by the system when changing of run-
3703 level in particular when doing a shutdown, it can also be
3704 generated with the kill command
3705 SIGHUP Depending on the system, this signal may be sent before the
3707 SIGTERM signal at shutdown time, it can also be generated
3708 with the kill command
3709 SIGQUIT This signal is generated by the terminal when hitting CTRL-\
3711 (with the terminal's default settings), it can also be gener‐
3712 ated with the kill command
3713 SIGUSR1 This signal can be generated by the kill command
3715 SIGUSR2 This signal can be generated by the kill command
3717 For those previous signals, two behavior exit. For SIGHUP, SIGINT,
3720 SIGQUIT, SIGTERM and SIGUSR1, a delayed termination is done: the backup
3721 or isolation operation is stopped, the catalogue is appended to the ar‐
3722 chive and the archive is properly completed with the correct terminator
3723 string, this way the generated archive is usable, and can be used as
3724 reference for a differential backup at a later time. Note that if an
3725 on-fly isolation had been asked, it will *not* be performed, and no
3726 user command will be launched even if dar has been configured for (-E
3727 option). For SIGUSR2 instead a fast termination is done: in case of
3728 backup or isolation, the archive is not completed at all, only memory
3729 and mutex are released properly.
3730 For both type of termination and other operations than backup or isola‐
3732 tion, dar's behavior is the same: For restoration, all opened directo‐
3733 ries are closed and permissions are set back to their original values
3734 (if they had to be changed for restoration). For listing, comparison,
3735 testing, the program aborts immediately.
3736 Another point, when using one of the previous signals, dar will return
3738 with the exist status 4 meaning that the user has aborted the opera‐
3739 tion. Note that answering "no" to a question from dar may also lead dar
3740 to exit this way. last, If before the end of the program the same sig‐
3741 nal is received a second time, dar will abort immediately.
3742
3745 $HOME/.darrc and /etc/darrc if present are read for configuration op‐
3746 tion. They share the same syntax as file given to -B option. If
3747 $HOME/.darrc is not present and only in that case, /etc/darrc is con‐
3748 sulted. You can still launch /etc/darrc from .darrc using a statement
3749 like -B /etc/darrc. None of these file need to be present, but if they
3750 are they are parsed AFTER any option on the command line and AFTER in‐
3751 cluded files from the command line (files given to the -B option).
3752 NOTE: if $HOME is not defined $HOME/.darrc default to /.darrc (at the
3753 root of the filesystem).
3754 Else you can see conditional syntax below, and -N option above that
3756 leads dar to ignore the /etc/darrc and $HOME/.darrc files.
3757
3760 configuration files (-B option, $HOME/.darrc and /etc/darrc) usually
3761 contain a simple list of command-line arguments, split or not over sev‐
3762 eral lines, and eventually mixed with comments (see -B option for
3763 more). But, you can also use make-like targets to ask for a particular
3764 set of commands to be used in certain conditions.
3765 A condition takes the form of reserved word immediately followed by a
3767 colon ':'. This word + colon must stand alone on its line, eventually
3768 with spaces or tabs beside it. The available conditions are:
3769 extract: all options listed after this condition get used if
3771 previously on command line or file the -x command
3772 has been used
3773 create: all options listed after this condition get used if
3775 previously on command line or file (-B option) the
3776 -c command has been used
3777 list: (or listing:) if -l command has been used
3779 test: if -t command has been used
3781 diff: if -d command has been used
3783 isolate: if -C command has been used
3785 merge: if -+ command has been used
3787 repair: if -y command has been used
3789 reference: if -A option has been used (except when -A is used
3791 for the snapshot feature or in conjunction with
3792 -af)
3793 auxiliary: if -@ option has been used
3795 all: in any case
3797 default: if no -c, -d, -x, -t, -C, -l or -+ option has been
3799 used at this point of the parsing.
3800 The condition stops when the next condition starts, or at End of File.
3802 The commands inserted before any condition are equivalent to those in‐
3803 serted after the "all:" condition. Remark : -c -d -x -t -C and -l are
3804 mutual exclusive, only one of them can be used while calling dar.
3805 Here is an example of conditional syntax
3807 create:
3809 # upon creation exclude the
3810 # following files from compression
3811 -Z "*.mp3" -Z "*.mpg"
3812 all:
3814 -b
3815 -p
3816 default:
3818 # this will get read if not
3819 # command has been set yet
3820 -V
3821 # thus by default dar shows its version
3822 all:
3824 -v
3825 # for any command we also ask to be verbose
3826 # this is added to the previous all: condition
3827 Last point, you may have several time the same condition (several all:
3829 ) for example. They will be concatenated together.
3830
3833 User targets are arbitrary words found on command line, that do not
3834 start by a dash ('-'). On most system they should be placed after com‐
3835 mand and options. They are collected from command-line first, then
3836 comes the parsing of command and optional arguments. Their use is to
3837 extend conditional syntax described just above by having a set of op‐
3838 tions activated by the user just adding a single word on command-line.
3839 Of course user targets must not be equal to one of the reserved words
3840 of the conditional syntax (extract, create, ... all, default). A valid
3841 target is a word (thus without space) composed of lowercase or upper‐
3842 case letters (case is sensitive) with eventually digits, dashes '-' or
3843 underscores '_' characters.
3844 Let's see an example of use:
3846 first a DCF file named 'example.dcf' that will be given on command
3848 line:
3849 # normal set of files considered for backup
3851 create:
3853 -R /
3854 -P proc
3855 -P sys
3856 -P mnt
3857 -D
3858 # if the "home" user target is applied on command line the fol‐
3860 lowing command get added
3861 home:
3863 -g home
3864 # if the "verbose" user target is used, we will have some more
3866 verbosity ...
3867 verbose:
3869 -v
3870 -vs
3871 Then we could run dar in the following ways:
3873 dar -c test -B example.dcf
3875 in that case only the command in the "create:" sec‐
3876 tion of example.dcf would be used.
3877 dar -c test -B example.dcf verbose
3879 here over the "create:" target the commands under
3880 the "verbose:" target (-v and -vs) would be also
3881 used
3882 dar -c test -B example.dcf verbose home
3884 last we use two user targets "verbose:" and "home:"
3885 in addition the the "create:" target of the usual
3886 conditional syntax.
3887 Note that if the last option *may* receive an argument, the first user
3889 target that follows it will be assumed an argument to that option. To
3890 avoid this, either change the order of options on command line for the
3891 last option been an option that never or always uses an argument (for
3892 example -b never has an argument while -s always has one). Or separate
3893 the options from the user targets by the -- word. And of course you can
3894 also use the explicit argument of the last option (see EXPLICIT OP‐
3895 TIONAL ARGUMENT section, above).
3896 Second point: It is allowed to have user targets inside a DCF file.
3898 Note however that targets are collected in a first phase, which leads
3899 some part of the file to be hidden (because the corresponding condi‐
3900 tional syntax or user target is not present). Then, the remaining part
3901 of the file is then parsed and actions for each option found is taken.
3902 At that time, new user targets found are just recorded, but they do not
3903 modify the current DCF file layout, in particular, hidden part of the
3904 file stay hidden even if the corresponding user target is read in this
3905 same file. Next DCF parsing (which may be triggered by a second -B op‐
3906 tion on the command line, or by a -B option inside the current parsed
3907 DCF file) will thus be done with the additional targets found in that
3908 first DCF file, so in a way you may have user targets that activate
3909 other user targets, but they will be activated in starting the next -B
3910 file. Here follows an examples of two DCF files, first.dcf and sec‐
3911 ond.dcf:
3912 # cat first.dcf
3914 target3:
3915 -K toto
3916 target1:
3918 target2
3919 -B second.dcf
3920 target3
3921 target2:
3923 #never reached
3924 -s 10k
3925 # cat second.dcf
3927 target2:
3928 -v
3929 target3:
3930 -b
3931 In that example, target1 activates both target2 and target3, but at the
3933 time of the parsing of first.dcf, neither target2 nor target3 were yet
3934 activated thus '-K toto' and '-s 10k' will never be given to dar (un‐
3935 less activated beside target1 before first.dcf get parsed), however
3936 when comes the time to parse second.dcf, target2 *and* target3 are ac‐
3937 tivated, thus both '-v' and '-b' will be passed to dar, even if 'tar‐
3938 get3' is located after '-B second.dcf' in the file first.dcf
3939
3943 DAR_DCF_PATH
3944 if set, dar looks for Dar Configuration File (DCF files, see
3945 -B option) that do not have an fully qualified path in the
3946 directories listed in DAR_DCF_PATH environment variable. This
3947 variable receives a colon (:) separated list of paths and
3948 look in each of them in turn, up to the first file found un‐
3949 der the requested name.
3950 DAR_DUC_PATH
3952 if set, dar looks for Dar User Command (DUC files, see -E,
3953 -F, -~, -= options) that do not have a fully qualified path
3954 in the directories listed in DAR_DUC_PATH. This variable re‐
3955 ceives a colon (:) separated list of paths and looks in each
3956 of them in turn, up to the first file found under the re‐
3957 quested name.
3958 DAR_SFTP_KNOWNHOSTS_FILE
3960 if set, dar will not use the $HOME/.ssh/known_hosts file to
3961 check sftp remote server authenticity but the file given as
3962 value for this environment variable. Note that setting this
3963 variable to an empty string completely disable host valida‐
3964 tion, which is not recommended. Dar, the command line inter‐
3965 face program for disk archive relies on libdar for archive
3966 format management which relies on libcurl for network trans‐
3967 fer which in turn relies on libssh2 for all that concerns
3968 ssh/sftp protocol. In the known_hosts file, libssh2 does not
3969 support recent lines like those with "ecdsa-sha2-nistp256" in
3970 second argument before its release 1.9.0 (you will also need
3971 curl/libcurl 7.69.1 or more recent), in these old versions
3972 you only have support for "ssh-rsa" lines. Check libssh2 and
3973 libcurl documentations and literature for more details about
3974 that limitation. The workaround, if you have not yet libssh2
3975 1.9.0 or more recent, is to disable known hosts validation or
3976 set up a restricted known hosts file without any "ecdsa*" en‐
3977 try and have DAR_SFTP_KNOWNHOSTS_FILE pointing to it.
3978 DAR_SFTP_PUBLIC_KEYFILE
3980 by default dar will fetch the public key file in
3981 $HOME/.ssh/id_rsa.pub file. If you use the former id_dsa.pub
3982 or more recent key types you need to set this environment
3983 variable to point to the appropriated filename
3984 DAR_SFTP_PRIVATE_KEYFILE
3986 by default dar will fetch the public key file in
3987 $HOME/.ssh/id_rsa file. If you use the former id_dsa.pub or
3988 more recent key types you need to set this environment vari‐
3989 able to point to the appropriated filename
3990 DAR_IGNORED_AS_SYMLINK
3992 receive a colon separated list of absolute paths, which if
3993 they are symlinks are not saved as symlink but as the inode
3994 they point to. For more details see the --ignored-as-symlink
3995 option above.
3996 GNUPGHOME for asymmetric encryption and signature, the keyring used is
3998 $HOME/.gnupg by default. You can change this default by set‐
3999 ting GNUPGHOME to the directory containing the keyring. For
4000 example, if you are running dar as root and want to use your
4001 unprivileged account keyring use the following:
4002 export GNUPGHOME=~myaccount/.gnupg
4004 dar -K gnupg:...@...,...@... --sign:...@... etc.
4006
4009 dar fully supports the cap_chown capability, but by design, dar only
4010 uses this capability to restore files at their original ownership. Dar
4011 will thus not use this capability to access files and directories the
4012 caller would normally not have access to. In other words, it should be
4013 ok to set the cap_chown capability to the dar executable (setcap
4014 cap_chown+p dar). Calling dar from a process having the cap_chown in
4015 the inheritable set would lead the system to grant this capability to
4016 the dar process while other users would not be granted this capability
4017 and would not be able to modify ownership of files at restoration time.
4018 This can be used for the system account that has the role of restoring
4019 data upon user requests, without giving root privilege to this restora‐
4020 tion process.
4021
4024 You can find some more examples of use in the tutorial, mini-howto,
4025 sample scripts, and other related documentation. All these are avail‐
4026 able in dar's source package, and are also installed beside dar in the
4027 <--prefix>/share/dar directory. This documentation is also available
4028 on-line at http://dar.linux.free.fr/doc/index.html
4029
4032 dar_xform(1), dar_slave(1), dar_manager(1), dar_cp(1), dar_split(1),
4033 TUTORIAL and NOTES included in the source package and also available at
4034 http://dar.linux.free.fr/doc/index.html
4035
4038 dar saves and restores atime, mtime, birthtime but cannot restore ctime
4039 (last inode change), there does not seems to be a standard call to do
4040 that under UNIX. An up to date list of known limitation is at
4041 http://dar.linux.free.fr/doc/Limitations.html
4042
4045 http://sourceforge.net/p/dar/bugs/
4046
4049 http://dar.linux.free.fr/
4050 Denis Corbin
4051 France
4052 Europe
40533rd Berkeley Distribution November 29th, 2022 DAR(1)