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