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