NAME¶

dar - creates, tests, lists, extracts, compares, merges, isolates, repairs dar archives

SYNOPSIS¶

dar [-c | -t | -l | -x | -d | -+ | -C | -y] [[<URL>]<path>/]<basename> [<options>] [<user targets>]

dar -h

dar -V

DESCRIPTION¶

dar is a full featured backup tool, aimed for local and remote disks (floppy, CD-R(W), DVD-R(W), zip, jazz, hard-disks, usb keys, etc.) cloud storage (by mean of ftp or sftp protocols) and also adapted to tapes.

dar can store a backup in several files (called "slices" in the following) of a given size, eventually pausing or running a user command/script before starting the next slice. This can allow for example, the burning of the last generated slice on a DVD-R(W), Blue-ray Disk, or changing of usb key before continuing on the next one. Like its grand-brother, the great "tar" command, dar may also use compression, at the difference that compression is used inside the archive to be able to have compressed slices of the defined size.

But the most important feature of dar is its ability to make differential, incremental and decremental backups. In other words, backups that contain only new files or files that have changed from a backup of reference. Binary delta is available but not activated by default: in combination with differential and incremental backups, it leads not only to not save a file that has not changed (thing dar does without binary delta), but also to only save an rsync patch of any modified file, which lead to even smaller backups.

Moreover with differential backup, dar also stores files that have been deleted since the backup of reference. Thus, when restoring, first a full backup, then additional differential backups, at each restoration you get the exact state of the filesystem at the time the differential backup was made. dar is the first backup program I know that can also remove files during restoration! By the way, in this document, "archive" and "backup" are used interchangeably, the difference is the purpose you build them for.

Unlike the tar command, dar has not to read a whole archive nor to stick together the different parts (the slices) to access its contents: dar archives contain a table of contents (aka "catalogue") located at the end, so dar can seek into the archive to read only the required data to restore files, thing which is much faster than what tar is used to do. The "catalogue" can be copied out of the archive (operation called isolation) to be used as reference for further backup and as backup of the internal catalogue in case of archive corruption.

Dar can also use a sequential reading mode, in which dar acts like tar, just reading byte by byte the whole archive to know its contents and eventually extracting file at each step. In other words, the archive contents is located at both locations, a first time all along the archive used for tar-like behavior suitable for sequential access media (tapes) and a second time at the end for faster access, suitable for random access media (disks). However note that tar archive and dar archive are not compatible. Note also that the sequential reading mode let you extract data from a partially written archive (those that failed to complete due to a lack of disk space for example) and since release 2.6.0 such truncated archive can be repaired to become a normal archive (the "catalogue" is rebuilt from inlined information).

Dar is able to save and restore to a cloud storage by mean of ftp or sftp network protocols. It can also leverage ssh protocol using dar_slave and dar_xform two auxiliary programs provided beside dar.

Dar format is quite robust against corruption: Only the file where the corruption took place in the archive will not be possible to restore. To have the possibility to repair a corrupted archive dar can work with par2 seamlessly just specifying "par2" on command-line (see /etc/darrc). Last a "relax" reading mode is available which let dar to either ignore some incoherence in archive structure, use internal redundant information to overcome data corruption or in last resort asking the user on what to do when some archive structure information is missing (-al option). This relax mode can be used with both sequential and direct access read modes. Note that you should rather use Parchive to protect your data rather than just relying on the "relax" mode, which has to be seen as a the last chance solution.

dar takes care of POSIX Extended Attributes (EA in short) that are used in particular under Linux to carry File Access Control List (FACL) as well as security attributes for SELinux, and also under MacOS X EA they are used to store file forks. EA also have room for user to add any key / value pair to any file, this is known as user EA. These attributes are not specific to any particular filesystem, they exist the same way under ext3/4, HFS+ and any other filesystem.

dar also takes care of Filesystem Specific Attributes (FSA in short) which are, as you can guess, specific to one or several filesystem(s). For example the Birth date of a file exists for HFS+ and NTFS but not for ext2/3/4 filesystem. The immutable attribute exists for ext2/3/4 but not for NTFS while the nodump files does not exists for NTFS but exists for HFS+, ext2/3/4 and many other Unix filesystems.

Sparse files (files with holes that system reports using several hundred gigabytes while they effectively use a few kilobytes on disk) are also well managed by dar: they are detected, stored and restored to filesystem properly.

Last, dar is also able to properly save and restore hard-links

WARNING¶

This document is to be considered as a full reference of dar/libdar features. It is however not adapted to discover dar, for that purpose some tutorials are provided in dar documentation. Once you have apprehended the basic dar usages you are welcome to read further this document to see all other features you may find useful for your needs.

DOCUMENT STRUCTURE¶

The rest of this document is organized that way:

COMMANDS AND OPTIONS¶

COMMANDS:

Only eight commands define what action will be done by dar: Archive creation, archive extraction, archive listing, archive testing, archive comparison with filesystem, catalogue isolation, archive merging and archive repairing. These commands are described here below.

Once defined, a large set of options can be used to modify the way the command is performed. These options are described just after the commands chapter.

Important note: Not all systems actually support long options (Solaris, FreeBSD, ...). For example --create will not be available on these systems, and you will have to use -c instead. In the same way, not all systems do support optional arguments (FreeBSD without GNU getopt for example), you then need to explicitly give the argument, for example in place of "-z" you will need to give "-z 9", see "EXPLICIT OPTIONAL ARGUMENTS" paragraph near the end of this document for details on that point.

A slice is just a simple file which name is composed of a "basename" followed by a dot, then a number, again a dot and the extension (dar) to form the filename of that slice. On the command line you will never have to give the full file name of a slice, just the basename. The number between the dots is the slice number, which starts from 1 and may be arbitrary large (as large as your system can support the corresponding filename). For example "my_first_archive.42.dar" is the 42th slice of the archive which basename is "my_first_archive".

-c, --create [[<URL>]<path>/]<basename>

creates a backup with the name based on <basename>. All the slices will be created in the directory <path> if specified, details about the <URL> syntax is explained below at Remote repository syntax paragraph. Without <path> nor <URL> the current directory is used. If the destination filesystem is too small to contain all the slices of the backup, the -p option (pausing before starting new slices) might be of interest. Else, in the case the filesystem is full, dar will suspend the operation, asking for the user to make free space, then continue its operation. To make free space, the only thing you cannot do is to touch the slice being written. If the filename is "-" *and* no slicing is asked for (no -s option) the archive is produced on the standard output allowing the user to send the resulting archive through a pipe (or into a tape device directly or using the dar_split command).

-x, --extract [[<URL>]<path>/]<basename>

extracts files from the given backup. Slices are expected to be in the current directory or in the directory given by <path> (see also Remote repository syntax below). It is also possible to use symbolic links to gather slices that are not in the same directory. Path may also point to a removable device (floppy, CD, USB key, etc.), in this case, to be able to mount/unmount the device, you must not launch dar from that directory. In other words, the current directory must not on the removable media you plan to unmount (see tutorial for details). The basename may be set to "-", in direct access mode (the default historical mode), you will then need dar_slave to work with dar (see -i and -o options, as well as dar_slave man page). However in sequential read mode (--sequential-read is used on command-line), dar will read the archive from standard input (see also -i option), this can eventually be used in combination with dar_split.

-l, --list [[<URL>]<path>/]<basename>

lists the contents of the given backup (see also Remote repository syntax below) dar will only require the last slice of the archive in direct access mode. If however sequential mode is used, dar will read the overall archive, from the first slice to the last one. "-" can be used as basename, the behavior is the same as with -x option (read just above).

-t, --test [[<URL>]<path>/]<basename>

checks the backup integrity. Even without compression, dar is able to detect at least one error per file in the archive, thanks to a variable length CRC recorded per file data, file EA and file FSA in the catalogue. Archive structure (slice header, archive header, catalogue) is also protected by CRC to be able to detect any kind of archive corruption. Same remark here, "-" may be used as basename (see -x option above for details).

-d, --diff [[<URL>]<path>/]<basename>

compares saved files in the backup with those on the filesystem. <basename> may also be "-" (see -x option above for details). Note that the target for this operation is to be seen as a step further than archive testing, where in addition to archive coherence, the archive contents is verified to be the same as what is found on the filesystem. But if new files are present on the filesystem, dar ignores them. If you want to check for changes since a archive has been made, better use dry-run differential backup.

-C, --isolate [[<URL>]<path>/]<basename>

isolate a catalogue from its archive (that's to say make a copy of the internal catalogue to its own archive container). The argument is the basename of the file to create which will contain the catalogue's copy. The -A option is mandatory here to give the name of the archive to copy the catalogue from, this archive is not modified at all. Slicing is available (-s -S -p -b etc.). If the filename is "-" *and* no slice is asked (no -s option) the isolated catalogue is produced on the standard output, allowing the user to send the resulting archive through a pipe. Note that there is quite no difference in concept between an isolated catalogue and an archive. Thus you can do all operations on an isolated catalogue, in particular take it in place of the original backup as reference for a differential archive, archive testing, archive comparison. Note however that for comparison (-d option) as data is not present in the isolated catalogue, dar relies on embedded CRC rather than comparing data byte by byte (what is done with a plain archive), and no comparison can be performed concerning EA or FSA even if each of them have their own CRC in the catalogue because different ordering as provided by the OS of the items composing EA and FSA may lead the CRC to be different while the EA or FSA are exactly the same, so CRC here is used only to detect archive corruption. Since release 2.4.0 you can use an isolated catalogue to rescue a corrupted internal catalogue of the archive it has been based on (see -A option).

-+, --merge [[<URL>]<path>/]<basename>

create a subset archive from one or two existing archives (the resulting archive name is the argument to this command). The dar file selection mechanism (see GENERAL OPTIONS) let the user decide which files will be present in the resulting archive and which one will be ignored. This option thus let the user merge two archives in a single one (with a filtering mechanism that accepts all files), as well as this option let the user create a smaller archive which data is taken from one or two archives of reference. Note that at no time the contents of the archives of reference is extracted to real files and directories: this is an archive to archive transfer, thus you may lack support for Extended Attribute while you will be able to fully manipulate files with their Extended Attributes from one archive to the resulting one. If the basename is "-" *and* no slice is asked (no -s option), the archive is produced on standard output allowing the user to send the resulting archive through a pipe. The first mandatory archive of reference is provided thanks to the -A option, while the second "auxiliary" (and optional) archive of reference is provided thanks to the -@ option. When a tie contention occurs (same file names from both archive have to be merged), the overwriting policy (-/ option) is used to define the one to keep in the resulting archive. By default, archive data selected for merging is uncompressed, and re-compressed. Thus the merging operation can be used to change compression algorithm of given archive as well as change its encryption. But, for better performance it is also possible thanks to the -ak option (see below the -ak option for usage restrictions) to merge files keeping them compressed, thus no decompression/re-compression is performed at all, which make the operation faster. Last it is not possible to merge two isolated catalogues.

-y, --add-missing-catalogue [[<URL>]<path>/]<basename>

create a "repaired" archive based on the archive given with -A option. The repairing only concerns the case where an archive has been interrupted and dar could not cleanly end the archive creation process (lack of disk space, power outage, and so on). This operation consists in reading the tape marks in sequential reading mode to gather the content of the archive and once its end is reached, to recreate the missing table of content (aka catalogue) located at the end of the archive. Note that the damaged archive is not modified but a repaired copy is built beside it. Why not just appending the catalogue to the archive? Because first it was simpler to implement allowing to reuse routines of the merging operation, second by precaution for dar to not mess an existing archive due to a bug and last, it would not be compatible with archive signing and gpg encryption under certain conditions (several recipients or the archive is signed and you are not the one who signed it).

-h, --help

displays help usage.

-V, --version

displays version information.

Remote repository syntax for [<URL>]<path>

GENERAL OPTIONS:

-v, --verbose

For backward compatibility, this is an alias to "-vt -vm" (both options set).

-vs, --verbose=skipped

Display files skipped because of file filtering exclusion specified by the user

-vt, --verbose=treated

Display treated files because of file filtering inclusion specified by the user or no file filtering specified at all. For each file a message is displayed *before* the file is treated. This option is not available for archive isolation and is useless for archive listing as it is always set, unless -q is used.

-vd, --verbose=dir

Display the directory under process. The messages shows *before* entering a directory. You can have a less verbose output than -vt while are still able to follow what's dar is doing. Note that -vt and -vd are mutually exclusive.

-vm, --verbose=messages

Display detailed messages about what dar is currently performing but not related to currently treated or skipped files and directories

-vf, --verbose=finished

Issues a summary *after* each treated directory containing the amount of data backed up in that directory as well as the average compression ratio. This option is only available for archive creation.

-va, --verbose=all

is equivalent to -vm -vs -vt, see also -Q and -q options below. Note: When using dar from a script better use dar's exit status to know which way the operation has ended (seen EXIT CODES at the end of this document).

-vmasks, --verbose=masks

Display raw information about the masks set by dar and passed to libdar

-avc, --alter=verbose-libcurl

activate verbose output from libcurl (remote repositories context). This is to be considered as a debug option relative to remote connection problems.

-q, --quiet

Suppress the final statistics report. If no verbose output is asked beside this option, nothing is displayed if the operation succeeds. When using dar from a script better use dar's exit status to know which way the operation has ended (seen EXIT CODES at the end of this document)

-b, --beep

makes the terminal ring when user action is required (like for example the creation of a new slice using the -p option)

-B, --batch <filename>

In the file which name is given in argument to this option, You can put any option or argument as used on command line, that will be parsed as if they were in place of the "-B <filename>" option. This way you can overcome the command line size limitation. Commands in the file may be disposed on several lines, and -B option can also be used inside files, leading a file to include other files. But an error occurs in case of loop (a file that includes itself directly or not) and DAR aborts immediately. Comments are allowed, and must start by a hash `#' character on each line. Note that for a line to be considered as a comment the hash character must be the first character of the line (space or tab can still precede the hash). See Conditional Syntax below for a richer syntax in this type of configuration files known as DCF file (Dar Configuration File). See also the environment variable DAR_DCF_PATH in the ENVIRONMENT section at the end of this document.

Note that you can use quotes simple (´arg´) double ("arg") and back-quotes (`arg`) inside such file, but they need to be balanced (have an ending one). To use such character without the meaning of a quote, for example as an apostrophe, you need to escape it using a back-slack ("That\'s an example"). Of course to add a single back-slash as a normal character in the file you will have to double it ("c:\\windows" for example)

-N, --noconf

Do not try to read neither ~/.darrc nor /etc/darrc configuration files. See files section below.

-Q

Do not display an initial warning on stderr when not launched from a terminal (when launched from a cronjob for example). This means that all questions to the user will be answered by 'no', which most of the time will abort the program. Please note that this option cannot be used in a configuration file (-B option). Since version 2.2.2, giving this option also forces the non-interactive mode, even if dar is launched from a terminal. This makes it possible for dar to run in the background. When you do, it's recommended to also redirect stdout and/or stderr to files: dar -Q ... &> /dev/null &

-n, --no-overwrite

do not allow overwriting

If an overwriting policy is specified (see -/ option) -n option do only apply to slices overwriting, the overwriting of files during restoration or merging is handled by the overwriting policy. Without overwriting policy, -n applies to restored files as well as generated slices.

-w, --no-warn

Do not warn before overwriting (applied for slice overwriting and for overwriting decision make by the overwriting policy). By default overwriting is allowed but a warning is issued before proceeding. This option may receive 'a' as argument (see just below):

-wa, --no-warn=all

This implies the -w option, and means that over avoiding warning for file overwriting, DAR also avoids signaling a file about to be removed when its type is not the expected one. File are removed when they have been recorded as deleted since the archive of reference. At restoration of the differential archive, if a file of the given name exists, it is remove, but if the type does not match the file that was present at the time of the archive of reference (directory, plain file, fifo, socket, char or block device, etc.), a warning is normally issued to prevent the accidental removal of data that was not saved in the backup of reference. (See also -k option)

-A, --ref [[<URL>]<path>]/<basename>

Depending on the context, it specifies the archive to use as reference, which is mandatory for archive isolation (-C option) and merging operation (-+ option). Else it specifies the rescue catalogue to use when restoring (-x command), testing (-t command) or comparing (-d command) an archive. All slices of the reference backup are expected to be on the same directory given by <path> or the current directory by default. Usually only the last slice is required to extract the catalogue of reference. If necessary the use of symbolic links is also possible here to gather slices that do not reside in the same directory. You can also point <path> to a USB key, DVD-R(W) or any other mounted directory, because dar will pause and ask the user for required slices if they are not present. The argument to -A may be of four types:

-af, --alter=fixed-date

Modify the -A option behavior, making it receiving a <date> as argument in place of the [<path>]/<basename> default argument. The <date> is used to define which file to save: file which modification is newer or equal to <date>, and which to consider unchanged: those older than <date>. This option has only a meaning when creating an archive (-c option) and must be placed before -A option to have an effect.

-@, --aux [[<URL>]<path>]/<basename>, --on-fly-isolate [<path>]/<basename>

specifies an auxiliary archive of reference (merging context) or the name of the on-fly isolated catalogue (creation context). This option is thus only available with -+ option (merging) and -c option (archive creation). Note that --aux and --on-fly-isolate are really aliases to the same option, this is the context of use (archive creation or merging) which lead it to behave a way or another.

-R, --fs-root <path>

The path points to the directory tree containing all the files that will be enrolled in the operation (backup, restoration or comparison). By default the current directory is used. All other paths used in -P or -g options on the command line are and must be relative to this path (or to current directory if -R is not present). Note that -R is useless for testing (-t option) isolation (-C option) and merging (-+ option)

-X, --exclude <mask>

The mask is a string with wildcards (like * and ? see glob(7) for details) which is applied to filenames which are not directories. If a given file matches the mask, it is excluded from the operation. By default (no -X on the command line), no file is excluded from the operation. -X may be present several times on the command line, in that case a file will not be considered for the given operation if it matches at least one -X mask. See also -ar and -am options.

-I, --include <mask>

The mask is applied to filenames which are not directories (see glob(7) for details on wildcard characters). If a given file matches the mask and does not match any mask given with -X, the file is selected for the operation. By default (no -I and no -X on the command line), all files are included for the operation. -I may be present several times on the command line, in that case all files that match one of the -I mask will be considered for the given operation, if they do not also match one of the -X mask. See also -ar and -am options.

-P, --prune <path>

Do not consider file or directory sub-tree given by the path. -P may be present several time on the command line. The difference with -X is that the mask is not applied only to the filename, but also includes the path. Moreover it applies also to directories (-X does not). By default (no -P on the command-line), no sub-tree or file is excluded from the operation, and the whole directory tree (as indicated by -R option) is considered. Note that <path> may contains wildcards like * or ? see glob(7) or regex(7) man page for more information as well as -ar option to use regex instread of glob expressions.

-g, --go-into <path>

Files or directory to only take in account, as opposed to -P. -g may be used several time on command-line. Same thing here, the difference with -I is that the mask is applied to the path+filename and also concerns directories. By default all files under the -R directory are considered. Else, if one or more -g option is given, just those are selected (if they do not match any -P option). All paths given this way must be relative to the -R directory, which defaults to current directory. Warning, -g option cannot receive wildcards, these would not be interpreted.

-[, --include-from-file <listing_file>

Files listed in the listing file are included for the operation. No wildcard expression is interpreted in the listing file, the null character is not allowed and the carriage return is used to separate file names (one file name per line) each line must not exceed 20479 bytes. Note that this option applies to any files and directory exactly as -g does, with an important difference however: -g option only uses relative paths to the root directory (the directory given with the -R option), while -[ can use absolute path as well but only for operations that have a fs_root argument (archive creation, comparison, extraction, and so on, but not for archive listing, testing and merging). Another difference is when the argument is a directory -g will include all the subdirectories under that directory, while when the same entry is found in a listing file given to -[ option, only that directory will be included, no subdirectory or subfile would be enrolled in the backup. With -[ you need to list the exact set of file you want to backup. You can thus generate a listing file with the 'find / -print > somefile' command and give 'somefile' as argument to -[ option. Note that however, dar will never save files out of the -R given root directory tree, even if some are listed in the 'somefile' file.

-], --exclude-from-file <listing_file>

Files listed in the listing file are excluded from the operation. If a directory is listed in the file, all its contents is excluded. This option is the opposite of -[ and acts the same was as -P option does (in particular it is compared to the whole path+filename and applies to files and directories). As for -[ option, -] listing file can contain absolute paths, but wildcards are not expanded, neither.

File selection in brief:

As seen above, -I -X -P, -g, -[ and -] options are used to select the files to operate on. -I and -X only use the name of files and do not apply to directories, while -P, -g -[ and -] use the filename *and* the path, they *do* apply to directories.

since version 2.2.0 two modes of interpretation of these options exist. The normal original method and the ordered method:

-u, --exclude-ea <mask>

Do not consider the Extended Attributes (EA) that are matched by the given mask. By default, no EA are excluded, if the support for EA has been activated at compilation time. This option can be used multiple times.

-U, --include-ea <mask>

Do only consider the EA that match the given mask. By default, all EA are included if no -u or -U option is present and if the support for EA has been activated at compilation time. This option can be used multiple times. See also the -am and -ae options, they also apply to -U and -u options and read below the Note concerning EA.

Note concerning Extended Attributes (EA)

-4 --fsa-scope <family>[,<family>[, ...]

Reduce the scope of Filesystem Specific Attribute (FSA) to be considered for the operation. FSA are grouped by family. Current available families are:

-am, --alter=mask

set the ordered mode for mask. This affects the way -I and -X options are interpreted, as well as -g, -P, -[ and -] options, -Z and -Y options and -U and -u options. It can take any place on the command-line and can be placed only once. See the file selection in brief paragraph above for a detailed explanation of this option. It has also an incidence on the --backup-hook-exclude and --backup-hook-include options.

-an, --alter=no-case

set the filters in case insensitive mode. This concerns only masks specified after this option (see also -acase option below). This changes the behavior of -I, -X, -g, -P, -Z, -Y, -u and -U options.

Warning: case insensitivity requires interpreting filenames which depends on the locale with which dar is run (defined by the LANG environment variable). For example if you create files with LANG set to fr_FR.UTF-8 and use non plain ASCII characters in filename, there is chances that these non ASCII characters will be stored over several bytes in that filename: so called "wide characters". If then you run dar with LANG set to another value like ru_RU.koi8r, there is much chances that these wide characters do not correspond to the same letter or worse, that they do not match any valid wide character for that locale. A filename is always a sequence of bytes and always saved as such, but using --alter=no-case implies interpreting that sequence in a way that depends on the given locale (as defined by the LANG environment variable). As such, dar cannot know if a given file has to be read with fr_FR.UTF-8 locale or with it_IT.iso88591 or ru_RU.koi8r and so on, because this information is not stored in filenames. In consequence, if different locales are used on your system and you are doing a system wide backup, using --alter=no-case option may lead dar to detect invalid wide character, in that case it falls back to a byte by byte case sensitivity comparison (ASCII characters), which may not be what you would expect at first sight: Most of the time, an upper case wide character (stored on several bytes) does not match the equivalent lower case wide character (several bytes too), when case sensitivity comparison is performed byte by byte.

-acase, --alter=case

set back to case sensitive mode for filters. All following masks are case sensitive, up to end of parsing or up to the next -an option. This changes the behavior of -I, -X, -g, -P, -Z, -Y, -u and -U options.

-ar, --alter=regex

set the filters to be interpreted as regular expressions (man regex(7) ) instead of the default glob expression (man glob(7) ) This modifies the -I, -X, -g, -P, -Z, -Y, -u and -U options that follows up to an eventual -ag option (see just below). Note that for -P option, the given mask matches the relative path part of the files path: Let's take an example, assuming you have provided /usr/local to the -R option, the mask "^foo$" will replaced internally by "^/usr/local/foo$" while the mask "foo$" will be replaced internally by "^/usr/local/.*foo$".

-ag, --alter=glob

This option returns to glob expressions mode (which is the default) after an -ar option has been used, this applies to any -I, -X, -g, -P, -Z, -Y, -u and -U options that follow up to an eventual new -ar option (see just above).

-i, --input <path>

is available when reading from pipe (basename is "-" for -x, -l, -t, -d or for -A when -c, -C or -+ is used). When reading from pipe, standard input is used, but with this option, the file <path> (usually a named pipe) is used instead. This option is to receive output from dar_slave program (see doc/usage_notes.html for examples of use). Note that when --sequential-read is used, dar uses a single pipe and does no more rely on dar_slave, -i option can be used to tell dar which named pipe to read the archive from, instead of the standard input.

-o, --output <path>

is available when reading from pipe (basename is "-" for -x, -l, -t, -d or for -A when -c, -C or -+ is used). When reading from pipe, standard output is used to send request to dar_slave, but with this option, the file <path> (usually a named pipe) is used instead. When standard output is used, all messages goes to standard error (not only interactive messages). See doc/usage_notes.html for examples of use. This option is not to be used in --sequential-read mode.

-O, --comparison-field[=<flag>]

When comparing with the archive of reference (-c -A) during a differential backup, when extracting (-x) or when comparing (-d) do only considers certain fields. The available flags are:

When no flag is provided to this option, -O option acts as if the "ignore-owner" flag was set, which is the behavior in older releases (< 2.3.0). Note also that for backward compatibility, --ignore-owner option still exists and since version 2.3.0 is just an alias to the --comparison-field=ignore-owner option. Of course if this option is not used, all fields are used for comparison or restoration.

-H[num], --hour[=num]

if -H is used, two dates are considered equal if they differ from a integer number of hours, and that number is less than or equal to [num]. If not specified, num defaults to 1. This is used when making a differential backup, to compare last_modification date of inodes, at restoration or merging time if overwriting policy is based on file's data or EA being more recent and last, when comparing an archive with a filesystem (-d option). This is to workaround some filesystems (like Samba filesystem) that seems to change the dates of files after having gone from or to daylight saving time (winter/summer time). Note that -H option has influence on the overwriting policy (see -/ option) only if it is found before on command-line or in an included file (using -B option).

-E, --execute <string>

the string is a user command-line to be launched between slices. For reading an archive (thus using -t, -d, -l or -x commands), the given string is executed before the slice is read or even asked, for writing an archive instead (thus using -c, -C or -+ commands), the given string is executed once the slice has been completed. Some substitution macros can be used in the string:

Several -E option can be given, given commands will then be called in the order they appear on the command line and -B included files. Note that having '-E script1 -E script2' is totally equivalent to '-E "script1 ; script2"'. In other words if script1 fails, script2 fill still be executed and dar will only be notified of the exit status of the last -E option. Exit status of previous -E given commands will be ignored. If this does not match your need, consider using a single -aduc option (see below). More generally you can use any shell construction in the argument to -E, including parenthesis, || and &&. Such files given to -E option are known as DUC files (Dar User Command). See also the environment variable DAR_DUC_PATH in the ENVIRONMENT section at the end of this document.

-aduc, --alter=duc

As described above for -E option, several -E/-F/-~ options (aka DUC commands) are combined using the shell ";" operator, which ignores the exit status of the first commands and only reports to dar the exit status of the last command, leading all commands to always being executed. --aduc option combines the different DUC commands using the shell "&&" operator, which execute the next command if and only if the previous command succeeded. In other words, dar get notified of an error in any given DUC command but due to an error not all DUC commands may be executed.

--aduc modifies the way the next DUC file is sticked to the previous command, in other words:

-F, --ref-execute <string>

same as -E but is applied between slices of the reference archive (-A option). --execute-ref is a synonym.

-~, --aux-execute <string>

same as -E and -F but is applied between slices of the auxiliary archive (-@ option).

-K, --key [[<algo>]:]<string>

-K, --key gnupg:[<algo>]:keyid/email[,keyid/email[...]]

-J, --ref-key [[<algo>]:]<string>

same meaning/use as -K option's first syntax, but the given key is used to decrypt the archive of reference (given with -A option). --key-ref is a synonym. Note that for archives generated using dar release 2.5.0 and above this option is no more necessary, unless you want to give the passphrase on command-line (not recommended) or in DCF file (which file would be set with restricted access permissions and/or ACL).

-$, --aux-key [[<algo>]:]<string>

same as -J but for the auxiliary archive of reference (given with -@ option). Here too, this option is no more necessary to read archives generated by dar release 2.5.0 and above.

-#, --crypto-block <size>

to be able to randomly access data in an archive, it is not encrypted globally but block by block. You can define the encryption block size thanks to this argument which default to 10240 bytes. Note that the syntax used for -s option is also available here (k, M, G, etc.). Note also that crypto-block is stored as a 32 bits integer thus value larger than 4GB will cause an error. Note last, that the block size given here must be provided when reading this resulting archive, using the -* option if the archive is the archive of reference (given to -A option) using -% options if the archive is the auxiliary archive of reference (given to -@ option) or using this -# option if it is the subject of the operation (listing, comparing, testing that archive). If the value is not the default and the given value is not correct in regard to the value given at archive creation time, the archive will not be possible to decrypt, it is thus safer to keep the default value (and not using at all the -#, -*, -% options).

-*, --ref-crypto-block <size>

same as --crypto-block but to read the archive of reference (-A option). --crypto-block-ref is a synonym.

-%, --aux-crypto-block <size>

same as --crypto-block but to read the auxiliary archive of reference (-@ option).

-e, --dry-run

Do not perform any action (backup, restoration or merging), displays all messages as if it was for real ("dry run" action). The --empty option is a synonym.

-aSI, --alter=SI[-unit[s]]

when using k M G T E Z Y prefixes to define a size, use the SI meaning: multiple of 10^3 (a Mega is 1,000,000).

-abinary, --alter=binary[-unit[s]]

when using k M G T E Z Y prefixes to define a size, use the historical computer science meaning: multiple of 2^10 (a Mega is 1,048,576).

The --alter=SI and --alter=binary options can be used several times on the command line. They affect all prefixes which follow, even those found in files included by the -B option, up to the next --alter=binary or --alter=SI occurrence. Note that if in a file included by the -B option, an --alter=binary or --alter=SI is encountered, it affects all the following prefixes, even those outside the included files. For example, when running with the parameters "-B some.dcf -s 1K", 1K may be equal to 1000 or 1024, depending on --alter=binary or --alter=SI being present in the some.dcf file. By default (before any --alter=SI/binary option is reached), binary interpretation of prefixes is done, for compatibility with older versions.

-ac, --alter=ctime

When reading a filesystem (during a backup or comparison), restores the atime of all files to what it was before the file was read. This makes it appear as if it had not been read at all. However, because there is no system call to let applications changing the ctime (last inode change) of a file, setting back the atime results in the ctime being changed (hence the alter=ctime). Some recent unix system allow an application to get 'furtive read mode' to the filesystem (see below). On older systems, however, for most users, having the atimes of the files changed shouldn't be a problem, since they can be changed by any other program (running by any user!) as well (like the content-index program Beagle). Ctimes on the other hand, are the only way for security software to detect if files on your system have been replaced (by so called root-kits mostly). This means, that should you run dar with -ac, security software which uses ctimes to check, will mark every file on your system as compromised after the backup. In short, this means this option should only be used by people who know what they are doing. It's the opinion of this writer that any software susceptible to atime changes is flaky or even broken (because of the afore mentioned reasons why atimes can change). But, that doesn't take away that there are programs who rely on atimes remaining the same, like Leafnode NNTP caching software. Therefore this option exists.

-aa, --alter=atime

When specifying -aa (by opposition to -ac), the atime of every read file and directory is updated, and the ctime remains the same. In other words, Dar itself does nothing with atimes and ctimes, it only let the system do its job to update atimes when files are accessed for reading. This is in accordance with what atimes and ctimes were meant to represent. This is Dar's default (since version 2.4.0), unless 'furtive read mode' (see below) is supported by your system and dar has been compiled with this support activated.

Furtive read mode is a mode in which neither atime nor ctime are modified while dar reads each file and directory. This provides also better performances as nothing has to be wrote back to disk. A known Unix kernel that supports this feature is Linux 2.6.8 and above (support must also be present in the standard C library of the system for dar to be able to activate this feature at compilation time). When this feature is activated, it becomes the default behavior of dar for super user ; for other users the default is -aa. If however as root user, you do not want to use "furtive read mode" (while it has been activated at compilation time), you can specify either -aa or -ac option.

-at, --alter=tape-marks

For archive creation and merging, the default behavior (since release 2.4.0) is to add escape sequences (aka tape marks) followed by inode information all along the archive. If -at is given, dar will not add this information to the archive, resulting in a slightly smaller archive and faster backup. When reading an archive, the default behavior is to ignore these escape sequences and rather rely on the catalogue located at the end of the archive. If instead --sequential-read is given on command-line (see below), dar will avoid using the catalogue at the end of the archive and will rely on these escape sequences to know the contents of the archive, which will lead to a sequential reading of the archive, operation suitable for tape media. Note that it is not recommended to disable escape sequences (aka tape marks) by using -at option except if you are more concerned by the resulting size and execution speed of your backup (in particular if you have a lot of small files) than by the possibility to recover your data in case of corrupted or partially written archive. Without escape sequences, dar cannot sequential read an archive, which is the only way beside using an isolated catalogue to use an archive that has a corrupted catalogue or has no catalogue at all, thing that happens if a system crash occurred during the archive creation or due to lack of disk space to complete the archive.

-0, --sequential-read

Change dar's behavior when reading an archive. By default, the traditional way is used, which relies on the table of contents (aka "the catalogue") located at the end of the archive. With the --sequential-read option instead, dar will rely on escape sequences that are inserted all along the archive with each file's inode information. This will lead to a sequential reading of the archive, operation suitable for tape medium. However, this feature is only available for archive format starting revision "08" (i.e.: since release 2.4.0) and if -at option has no been used during archive creation or merging. This option is available for archive testing (-t), comparison (-d), restoration (-x), listing (-l) and to read the archive of reference (-A option) for isolation (-C) and archive creation (-c). The sequential reading of an archive is always much slower than the usual reading method, so you should not use this option unless you really need it.

-9, --min-digits <num>[,<num ref>[,<num aux>]]

By default slice number contained in filename do not have any padded zeros, which, when sorting a directory contents alphabetically leads to read all the slices starting by '1', then by '2'. for example, slice 1, 10, 11, 12, 13, ... 2, 20, 21, 23, ... etc. While dar is absolutely not perturbed by this display problem, some user shall like to have the slices sorted by order. For that reason, the --min-digits option lets you ask dar to prepend enough zeros in the slice number for it be as wide as the argument passed to --min-digits. For example, if you provide 3 for that number, dar will store the slice number as 001, 002, 003, ... 999. Well, next slice will be 1000, thus it will break again the alphabetical sorting order. You are thus advised to use a number large enough to convert the number of slice you expect to use. Before release 2.7.0, when reading an archive, you were also requested to provide this same argument else dar was unable finding the slice. Since 2.7.0 dar auto-detects the mi-digits value to use, unless there is a mix of archive of the same basename with different min-digits. In such conflicting context, you must bypass the min-digits auto-detection mechanism and specify which min-digits value to retain in order to read the archive, eventually followed by a comma and the number of digits to use to read the archive of reference (given to -A option), eventually followed by a comma and the number of digits to use for the auxiliary archive of reference (given to -@ option).

--pipe-fd <num>

will read further arguments from the file-descriptor <num>. The arguments read through this file-descriptor must follow a TLV (Type/Length/Value) list format. This option is not intended for human use, but for other programs launching dar like dar_manager. This feature has been added to overcome the command line length limit.

-al, --alter=lax

When reading an archive, dar will try to workaround data corruption of slice header, archive header and catalogue. This option is to be used as last resort solution when facing media corruption. It is rather and still strongly encourage to test archives before relying on them as well as using Parchive to do parity data of each slice to be able to recover data corruption in a much more effective manner and with much more chance of success. Dar also has the possibility to backup a catalogue using an isolated catalogue, but this does not face slice header corruption or even saved file's data corruption (dar will detect but will not correct such event).

-G, --multi-thread { <num> | <crypto>,<compression> }

When libdar is compiled against libthreadar, it can make use of several threads. If the argument is two numbers separated by a comma the first defines the number of worker threads to cipher/decipher, the second the number of threads to compress/decompress. If the argument is a single number (-G <n>) it is equivalent to giving this number as the number of compression threads and giving 2 for the ciphering threads (-G 2,<n>). The use of multi-threading at archive creation time leads to rely on per block compression rather than the legacy streaming compression and if the block-size is not specified (see -z option for details) it defaults to 240 KiB. Not providing any -G option, is equivalent to providing -G 2,1 when libthreadar is available else -G 1,1. Note that if an archive has been created with streaming compression, the decompression cannot use multi-threads, the deciphering can always use multiple threads.

-j, --network-retry-delay <seconds>

When a temporary network error occurs (lack of connectivity, server unavailable, and so on), dar does not give up, it waits some time then retries the failed operation. This option is available to change the default retry time which is 3 seconds. If set to zero, libdar will not wait but rather ask the user whether to retry or abort in case of network error.

-afile-auth, --alter=file-authentication

With this option, When reading or writing an archive to a remote repository when no password is provided, instead of interactively asking for a password dar will first check the ~/.netrc file for credentials when relying on FTP protocol and also for SFTP protocol (libcurl allows that, which is unusual but somehow useful). If no password could be found in ~/.netrc, in second time and for SFTP only, dar will try to connect using public key authentication. Public key authentication is tried without this option, but it is useful here to avoid having password requested interactively.

-ab, --alter=blind-to-signatures

do not check whether an encrypted archive with public key that has also been signed have correct signatures.

SAVING, ISOLATION, MERGING AND REPAIRING SPECIFIC OPTIONS (to use with -c, -C or -+)

-z, --compression={ [algo] | level | algo:level | algo:level:block-size }

add compression within slices. If -z is not specified, no compression is performed, but if -z is specified without algorithm gzip will be assumed.

Valid usage of -z option is for example: -z, -z9, -zlzo, -zgzip, -zbzip2, -zlzo:6, -zbzip2:2, -zgzip:1, -zxz:6, -zlz4::10k -z::12000 -zbzip2:8:10k and so on. Usage for long option is the same: --compression, --compression=9, --compression=lzo, --compression=gzip, --compression=bzip2, --compression=lzo:6, --compression=bzip2:2, --compression=gzip:1 --compression=xz:9 and so on.

About lzo compression, the compression levels of dar and lzop program do not match. If you want to get the behavior of compression level 1 of lzop, use the lzop-1 algorithm in place of lzo with dar/libdar. If you want to get the behavior of lzop compression level 3, use the lzop-3 algorithm in place of the lzo algorithm. Lzop compression levels 2, 4, 5 and 6 are the same as level 3. last, there is no difference about compression level 7, 8 and 9 between dar and lzop. The lzop-1 and lzop-3 algorithms do not make use of any compression level (compression level is ignored with these algorithms).

-s, --slice <number>

Size of the slices in bytes. If the number is appended by k (or K), M, G, T, P, E, Z, Y, R or Q the size is in kilobytes, megabytes, gigabytes, terabytes, petabytes, exabytes, zettabytes, yottabytes, ronnabytes or quettabytes respectively. Example: "20M" means 20 megabytes, by default, it is the same as giving 20971520 as argument (see also -aSI and -abinary options). If -s is not present the backup will be written to a single slice whatever the size of the backup may be (assuming your operating system can support arbitrarily large files).

-S, --first-slice <number>

-S gives the size of the first slice which may be chosen independently of the size of following slices (either bigger or smaller). This option needs -s option and by default of -S option, the size of the first slice is the same as the one of the following slices.

-p [<integer>], --pause[=<integer>]

pauses before writing to a new slice (this requires -s). By default there is no pause, all slices are written in the same directory, up to the end of the backup or until the filesystem is full. In this later case, the user is informed of the lack of disk space and dar stops for user action. As soon as some disk space is available, the user can continue the backup. The optional integer that this option can receive tells dar to only pause every 'n' slice. Giving 3 for 'n' will make dar pause only after slices 3, 6, 9 and so on. If this integer is not specified, the behavior is as if '1' was given as argument which makes dar pause after each slice.

-D, --empty-dir

At backup time only, when excluding directories either explicitly using -P or -] options, or implicitly by giving a -g or -[ options (a directory is excluded if it does not match mask given with -g options or -[ options) dar does not store anything about these. But with -D option, dar stores them as empty directories. This can be useful, if excluding a mount point (like /proc or /dev/pts). At restoration time, dar will then recreate these directories (if necessary). This option has no meaning with -C and is ignored in that case. Independently of that, -D can also be used at restoration time, but it activates a slightly different feature (see RESTORATION SPECIFIC OPTIONS below).

-Z, --exclude-compression <mask>

Filenames covered by this mask are not compressed. It is only useful in conjunction with -z option. By default, all files are compressed (if compression is used). This option can be used several times, in that case a file that matches one of the -Z mask will not be compressed. Argument given to -Z must not be include any path, just the filename (eventually/probably using wildcards). This option used while merging or repairing allow one to change the compression of files.

-Y, --include-compression <mask>

Filenames covered by this mask (and not covered masks given to -Z option(s)) are the only to be compressed. It is only available with -z option. By default all files are compressed. This option can be used several times, in that case all files that match one of the -Y will be compressed, if they do not also match on of the -Z masks. The ordered method here applies too when activated (with -am option), it works exactly the same as -I and -X options, but apply to file compression, not file selection. In other word, it matches only on the file name, not on the path of files. This option used while merging or repairing allow one to change the compression of files.

-m, --mincompr <number>

files which size is below this value will not be compressed. If -m is not specified it is equivalent to giving -m 100 as argument. If you want to compress all files whatever their size is you thus need to type -m 0 on the command line. The size unit is the byte (octet) and the same number extensions as those used with -s or -S are available here, if you want to specify the size in kilobyte, megabyte, gigabyte etc.

-1, --sparse-file-min-size <number>

Define the minimum length of zeroed bytes to replace by "holes". By default, this feature is activated with a value of 15 bytes. To completely disable it, set the size to zero. Disabling this feature will bring some noticeable speed improvement but will probably make the archive slightly bigger (depending on the nature of the data). Sparse files are files that contain so called holes. On a filesystem, the portion of zeroed bytes is not stored on disk, thus an arbitrary large file with huge portion of zeros may only require a few bytes of disk storage. While dar cannot detect how is allocated a given file because it makes a filesystem abstraction (it does not know the implementation of any particular filesystem, where from its portability), when it finds a sequence of zeroed bytes larger than the given threshold it can assume that it is in presence of a hole. Doing so, it does not store the given zeroed bytes into the archive, but place a tag beside the saved data to record the size of the hole and thus where to place the next non zeroed bytes. This makes dar archive disk space requirement much smaller when a sparse files is met. At restoration time, dar will restore holes writing normal data and seeking over the hole to write down the normal data after each hole. If the underlying file system supports sparse files, this will restore the holes. Note that there is no difference for applications whether a file is sparse or not, thus dar may well transform normal files into sparse files and vice-versa, only the disk requirement will change. Last point, if dar can reduce disk requirement for archive with holes as small as 15 bytes (smaller value works but the overhead cost more than what is required to store the zeroed bytes normally), it may not be the same at restoration, because filesystem allocation unit is usually several kilobytes (a page), however restored file will never be larger than it could be without holes. The only drawback of this feature is the additional CPU cycle it requires.

-ak, --alter=keep-compressed

During merging and repairing operation, keep files compressed, this has several restrictions : -z, -Z, -Y, -m are ignored, if two archives have to be merged, both must use the same compression algorithm or one of them must not use compression at all (this last restriction will probably disappear in a next version). The advantage of this option is a greater speed of execution (compression is usually CPU intensive).

-ah, --alter=holes-recheck

For merging and repairing, the sparse file detection mechanism is disabled by default. However if you want to activate it (assuming you have an old archive you want to convert the current archive format taking care of sparse files), you need to use -ah option to reactivate the sparse file detection mechanism. Then for merging and repairing --sparse-file-min-size can be used as described above for archive creation. In addition, you can have files stored as sparse file in the archive of reference be stored as normal files in the merged archive using -ah and passing to --sparse-file-min-size an value larger than all file sizes, for example as of today in year 2018, passing -ah --sparse-file-min-size 1E (1E for one exabyte) should be large enough.

--nodump

do not save files which have the 'd' flag set (see chattr(1) lsattr(1) ext2 commands). This option may not be available if the system dar has been compiled on did not provide support for ext2 flags. Note that this option does nothing with -+ option (merging) as no filesystem is used for that operation.

-5, --exclude-by-ea[=<extended attribute name>]

exclude inodes from backup that have been set with the EA given in argument. If not argument is given to that option the default EA used to exclude files from backup is "user.libdar_no_backup". To set this attribute to a given file, use the following command: "setfattr -n user.libdar_no_backup <filename>", to remove it: "setfattr -x user.libdar_no_backup <filename>". Last, to check the presence this EA: "getfattr <filename>"

-M, --mount-points={ I:<path to fs> | X:<path to fs> }

If the argument is of the I:<path to fs> form, the filesystem to which this path points to is considered for the backup operation, that's to say, other file filtering mechanism will be applied and some or all files of that filesystem will be saved for backup. While with the X:<path to fs> form, no file in that filesystem will even be considered for backup. both X: and I: forms must be provided with an absolute path. -M option can be used several times on the command-line. If only I: forms are used, the filesystem based filtering mechanism behaves as a white list (only those listed paths are included). If only X: form is used, the filesystem based filtering mechanism behaves as a black list (everything is considered except those listed paths). Last, while a mix of I: and X: forms are used, filsystems that will be considered for backup will be those given with an I: form and not also given with an X: form. Note that this is filesystem based filtering, not path based: If for example a filesystem is mounted under /var directory and you specify I:/var/log all /var filesystem will be considered for backup. If you rather want to only save what is in /var/log use the -P/-g/-X/-I/-[/-] options that realise the file filtering by name and path+name. You cannot exclude the filesystem which contains the path given to -R option. The use of -M option with argument erases any previous configuration done with -M option without argument (see below), and vice versa. By default (no -M option specified), no filtering based on filesystem is performed, in other worlds all files are considered for other file filtering mechanism (in particular -P/-g/-X/-I/-[/-] options) and eventually backed up.

example of use:
-MI:/var -MX:/var/spool
--mount-points=I:/var --mount-point=X:/var/spool

-M, --no-mount-points

This is the legacy form of the option described just above, that existed before release 2.7.0. When -M option is provided without argument, only files located on the filesystem pointed to by the path given to -R option will be considered for backup. Subdirectory that are mounting points for other filesystems will not be saved (or saved empty if -D option is used). This option is useless and ignored for merging operation. The use of -M without option lead dar to ignore any previous -M I:<path> and -M X:<path> options that could have been given on command-line or -B included file so far.

-, , --cache-directory-tagging

don't save contents of directories that use the Cache Directory Tagging Standard. See http://www.brynosaurus.com/cachedir/spec.html for details. (this option is useless with -+ option)

-/ , --overwriting-policy <policy>

This option let the user define when or how file overwriting can occur at restoration or archive merging time. It does no apply to slice overwriting which are driven by the -n option, it does instead apply to file during extraction and files inside archives when merging two of them. When considering overwriting, a file is said to be 'in place' while an other is known as 'new' or 'to be added'. At restoration time, the 'in place' is the one that is present in filesystem while the 'to be added' is the one from the archive. At merging time, the 'in place' is the one of the '-A' archive of reference while the 'to be added' is the one from the auxiliary '-@' archive or reference. This option does not apply to archive repairing.

-^, --slice-mode perm[:user[:group]]

defines the permission and ownership to use for created slices. By default, dar creates slices with read and write available for anyone letting the umask variable disable some privileges according to user's preferences. If you need some more restricted permissions, you can provide the permission as an octal value (thus beginning by a zero), like 0600 to only grant read and write access to the user. Be careful not to avoid dar writing to its own slices, if for example you provide permission such as 0400. Note also that the umask is always applied thus specifying -^ 0777 will not grant word wide read-write access unless your umask is 0000.

-_, --retry-on-change count[:max-byte]

When a file has changed at the time it was read for backup, you can ask dar to retry saving it again. By default a file can be re-saved up to 3 times (this is the 'count' field), you can set it to zero to disable this feature. In option the overall maximum amount of byte allowed to be wasted due to retry changing file's backup can be given after a colon character (:), this is the 'max-byte' field. By default (no --retry-on-change option specified) a limit of 1 wasted byte is allowed which is the mininum. Specifying zero for max-byte set no limit on the amount of wasted bytes (same as if no 'max-byte' was specified), each changing file is then saved up to 'count' times if necessary.

-ad, --alter=decremental

This flag is to be used only when merging two archives. Instead of the usual merging where each files of both archives are added to the resulting archive with eventually a tie using the overwriting policy (see -/ option), here the merging builds an archive which corresponds to the decremental backup done based on two full backups. the -A backup is expected to receive the older archive while the -@ is expected to point to the more recent one. If this option is used, the eventually overwriting policy is ignored and replaced internally by -/ "{E&R&~R&(A|!H)}[S*] P* ; {(e&~e&r&~r)|(!e&!~e)}[*s] *p". Additionally, files found in the newer archive that do not existed in the older are replaced by a 'detruit' entry, which marks them to be remove at restoration time. For more information about decremental backups read the usage_notes.html file in the documentation. Note that decremental backup is not compatible with delta binary.

-asecu, --alter=secu

This option disable the ctime check done by default during an differential backup: If the ctime of an plain file has changed since the archive of reference was done while all other values stay unchanged (inode type, ownership, permission, last modification date), dar issues a "SECURITY WARNING", as this may be the sign of the presence of a rootkit. You should use the -asecu option to disable this type of warning globally, if you are doing a differential backup of a just restored data (a differential backup with the archive used for restoration taken as reference). Effectively in that situation, as it is not possible to restore ctime, the restored data's ctime will have changed while other parameters will be unchanged for all restored files, leading dar to issue a warning for all restored files. This security check is disabled (implicitly) if dar is run with -ac option. Last, if a file has only its EA changed since the archive of reference was done (new EA, removed EA, modified EA), the security warning will show (false positive).

-., --user-comment "<message>"

This option let the user add an arbitrary message into the archive header. Warning! this message is always stored in clear text, even if the archive is encrypted. You can see the message inserted in an archive displaying the archive summary (dar -l <archive> -q). Some macro can be used inside the <message>:

-3, --hash <algo>

With this option set, when creating, isolating, merging or repairing an archive, beside each generated slices an on-fly hash file of the slice is created using the specified algorithm. Available algorithm are "md5", "sha1" and "sha512". By default no hash file is generated. The hash file generated is named based on the name of the slice with the .md5, .sha1 or .sha512 extension added to it at the end. These hash files can be processes by md5sum, sha1sum and sha512sum usual commands (md5sum -c <hash file>) to verify that the slice has not been corrupted. Note that the result is different than generating the hash file using md5sum or sha1sum once the slice is created, in particular if the media is faulty: calling md5sum or sha1sum on the written slice will make you compute the hash result on a possibly already corrupted file, thus the corruption will not be seen when testing the file against the hash at a later time. Note also that the creation of a hash file is not available when producing the archive on a pipe ("dar -c -").

-7, --sign email[,email[,...email]]

When creating, isolating, merging or repairing an archive with public key encryption (read -K option) it is also possible to sign it with one or more of your private key(s). At the difference of the hash feature above, only the randomly generated key used to cipher the archive, key that is dropped at the beginning and at the end of the archive, is signed. If the archive is modified at some place, that part will not be possible to decipher, but signature verification will stay quick and valid, unless the part that has been tempered is the key inside the archive in which case signature check will report a failure and archive will not be readable at all. If the signature is valid and the archive could be extracted without error, the whole archive could be assumed to be signed by the gnupg key owners, but read below the security note. See also GNUPGHOME in the ENVIRONMENT section at the end of this document.

-<, --backup-hook-include <mask>

The mask is applied to path+filename during backup operation only. If a given file matches the mask, a user command (see -= option below) will be run before proceeding to the backup and once the backup will be completed. See also -> option below. IMPORTANT: if using the short option, you need to enclose it between quotes: '-<' for the shell not to interpret the < as a redirection.

-> --backup-hook-exclude <mask>

The mask is applied to path+filename during backup operation only. If a given file matches the mask, even if it matches a mask given after -< option, no user command will be executed before and after its backup. The -< and -> options act like -g and -P, they can receive wildcard expression and thus have their comportment driven by the --alter=globe and --alter=regex expressions seen above, as well as the --alter=mask option. Last the --alter=case and --alter=no-case modify also the way case sensitivity is considered for these masks. By default, no -> or -< option, no file get selected for backup hook. IMPORTANT: if using the short option, you need to enclose it between quotes: '->' for the shell not to interpret the > as a redirection.

-=, --backup-hook-execute <string>

for files covered by the mask provided thanks to the -< and -> options, the given string is executed before the backup of that file starts and once it has completed. Several macro can be used that are substituted at run time:

-ai, --alter=ignore-unknown-inode-type

When dar meets an inode type it is not aware about (some times ago, it was the case for Door inode on Solaris for example, Door inodes are handled by dar since release 2.4.0), it issues a warning about its inability to handle such inode. This warning occurs even if that entry is filtered out by mean of -X, -I, -P, -g, -[ or -] options, as soon as some other entry in that same directory has to be considered for backup, leading dar to read that directory contents and failing on that unknown inode type (filtering is done based on the result of directory listing). This option is to avoid dar issuing such warning in that situation.

-8, --delta sig

This option can be used for archive backup, isolation and merging. Important: read also the best practice paragraph below

-8, --delta sig:<function>:<multiplier>[:<divisor>[:<min>[:<max>]]]

this variant of '--delta sig' option let you specify the block length used to build delta signatures. Larger values reduce CPU load required to build delta signature, but also lead to less accuracy when computing delta binary, which means larger delta patch and more data saved when a file has changed. The block len is calculated following the formula: block_len = function(filesize)*multiplier/divisor If this calculated value is lower than "min", it is set to min. If the calculated value is greater than "max" it is set to max unless max is set to zero in which case the value is kept as is. Of course "divisor" cannot be null. The available functions are:

-{, --include-delta-sig <mask>

-}, --exclude-delta-sig <mask>

Files matching the given mask will never have their delta signatures calculated, may --delta sig option be specified or not. See also --include-delta-sig option above and --delta-sig-min-size below.

-6, --delta-sig-min-size <number>

For archive merging, isolation and creation, when dar has to (re-)calculate delta signatures, this option modifies the minimum file size (in bytes) below which dar never calculates delta signatures. This option acts independently from --include-delta-sig and --exclude-delta-sig , however it cannot re-activate delta signature recalculation by itself while merging/isolating an archive, it requires either --exclude-delta-sig or --include-delta-sig option to be active in that situation. For archive backup instead, it does not require --exclude-delta-sig nor --include-delta-sig to act, but only need --delta sig option to be set. By default, this minimum size is 10 kio. The same option suffixes (k for kilo, M for mega, G for giga, T, ...) as the ones available with --slice option can be used here too. Using zero as argument gives the same result as not specifying this option at all (default size).

-8, --delta no-patch

In the context of differential backup, this option leads dar to never consider files for delta binary even if delta signatures are present. By default delta binary (rsync-like) operation is performed when a file has changed since the archive of reference was made *and* if a delta signature could be found in the archive of reference for that file (or in the isolated catalogue used as reference for the incremental/differential backup). If no delta signature could be found or if --delta no-patch is used, the normal behavior is done, which consist of saving that whole file in the archive. Note that if the archive of reference is read in sequential mode, the --delta no patch is required, dar will refuse to execute the operation: sequential read and binary delta are not compatible, because reading in sequential mode an archive does not let skipping backward to fetch the delta signature necessary to setup a delta patch.

Binary delta options usage and best practices:

-az, --alter=zeroing-negative-dates

dar/libdar saves dates as a number of seconds since the beginning of year 1970, the well known "Unix time" (plus a positive fraction for sub-second time-stamping). Some systems may return a negative number as the Unix time of a given file (files having dates before 1970), in that situation by default and since release 2.5.12 dar pauses and asks the user whether to assume the date as being zero. But with -az option, dar/libdar automatically assumes such negative dates to be zero and just issue a warning about the problem met.

-\, --ignored-as-symlink <absolute path>[:<absolute path>[:...]]

When dar reaches an inode which is part of this provided colon-separated list, if this inode is not a symlink this option has no effect, but if it is a symlinks dar saves the file the symlink points to and not the symlink itself as dar does by default. In particular, if the pointed to inode is a directory dar recurses in that directory. You can also pass this list as argument to the DAR_IGNORED_AS_SYMLINK environment instead of using --ignored-as-symlink (which takes precedence over the environment variable).

-'\'', --modified-data-detection=any-inode-change, --modified-data-detection=mtime-and-size

Before release 2.6.0, during a differential/incremental backup if any part of a file's inode metadata changed (ownership, permission, ...) even if the mtime (last modification time) and file size stood the same, dar had no choice than resaving the whole file for backup to record the metadata changes. This lead to a waste of backup time and space if in fact and for example only the ownership had been modified. You can still keep this historical behavior by invoking the --modified-data-detection=any-inode-change option. Since release 2.6.0 a new entry status ("inode-only") has been added. Dar can now re-save only metadata when the inode change does not concern the data. To know whether the data has changed or not, by default (no --modified-data-detection option given) dar looks at mtime and at file's size only. Specifying --modified-data-detection=mtime-and-size (which is the default behavior) can be used to revert the action of --modified-data-detection=any-inode-change for example when playing with included files (DCF files): the latest met takes precedence.

-T, --kdf-param <integer>[:<hash algo>]

At the difference of the listing context (see below), in the context of archive creation, merging and isolation, -T option let you define the iteration count used to derive the archive key from the passphrase you provided (archive encryption context) and the hash algorithm used for that derivation. -T has another older meaning when doing archive listing, but due to the lack of free character to create a new CLI option, there was no other choice than recycling an existing option not used in the context of archive creation/merging/isolation. The consequence is that the -T option must appear after the -+/-c/-C options for the operational context to be known at the time the -T option is met and its --kdf-param meaning to be taken into account. As --kdf-param is an alias to -T, this long form of this option must also be found after the use of either -c, -C or -+ option.

RESTORATION SPECIFIC OPTIONS (to use with -x)

-k[{ignored|only}], --deleted[={ignore|only}]

Without argument or with the "ignore" argument, this option leads dar at restoration time to not delete files that have been deleted since the backup of reference (file overwriting can still occur). By default, files that have been destroyed since the backup of reference are deleted during restoration, but a warning is issued before proceeding, except if -w is used. If -n is used, no file will be deleted (nor overwritten), thus -k is useless when using -n. If -/ option is used, this option without argument is ignored! With the "only" argument, this option only consider files marked as to be removed in the archive to restore, no file are restored but some file are removed. When -konly (or --deleted=only) is used, the -/ option is ignored (at the opposition of the "--deleted=ignore" option which is ignored when the -/ is used). Of course "--deleted=ignore" and "--deleted=only" are mutually exclusive, because if both of them were available at the same time dar would do nothing at all.

-r, --recent

only restore files that are absent or more recent than those present in filesystem. If -/ option is used, this option is ignored!

-f, --flat

do not restore directory structure. All files will be restored in the directory given to -R, if two files of the same name have to be restored, the usual scheme for warning (-w option) and overwriting (-n option) is used. No rename scheme is planned actually. When this option is set, dar does not remove files that have been stored as deleted since last backup. (-f implicitly implies -k).

-ae, --alter=erase_ea

[DEPRECATED use -/ instead] Drop all existing EA of files present in filesystem that will have to be restored. This way, the restored files will have the exact set of EA they had at the time of the backup. If this option is not given, a file to restore will have its EA overwritten by those present in the backup and if some extra EAs are present they will remain untouched. See the Note concerning Extended Attributes (EA) above for a detailed explanation about this behavior. If -/ option is used, this option is ignored!

-D, --empty-dir

At restoration time, if -D is not specified (default) any file and directory is restored in regard to the filtering mechanism specified (see -I, -X, -P, -g, -[ and -] options). But if -D option is provided the restoration skips directory trees that do not contain saved files. This avoid having a huge empty tree with a few restored files especially when restoring a differential archive in an empty place. Note: This feature cannot work when --sequential-read is used, as it is not possible to know whether a directory contains or not some saved files at the time the directory inode is read from the archive in sequential reading mode.

-2, --dirty-behavior { ignore | no-warn }

At restoration time, if a file in the archive is flagged as "dirty" (meaning that it had changed at the time it was saved), user is asked for confirmation before restoring it. Specifying "ignore" will skip those dirty files, while "no-warn" will restore them without user confirmation. This feature is incompatible with sequential reading mode, in this mode dar cannot know whether a file is dirty before having restored it. In consequences, in --sequential-read, once a file has been restored, if it is found to be dirty it will be removed unless dirty-behavior is set to "no-warn".

-/, --overwriting-policy <policy>

Overwriting policy can be used for archive restoration to define when and how file overwriting can occur. See above the description of this option.

-A, --ref [[<URL>]<path>]/<basename>

The --ref option can be used with an isolated catalogue to rescue an archive that has a corruption in the catalogue part, see GENERAL OPTIONS above for more details.

-au, --alter=unix-sockets

Do not restore unix-sockets. By default saved unix sockets are recreated at restoration time.

-ap, --alter=place

Since version 2.7.1 libdar stores the filesystem root path (given -R option) used when creating a backup, this is the known as the 'in-place' path. At restoration time by default, dar uses the provided -R option or if not specified uses the current directory as root directory for the restoration operation. Using -ap option lead dar to read the in-place path from the backup and restore the data using this path instead. This option is thus exclusive with -R option and may lead dar to report an error if the archive has not stored any in-place path (older archive format or backup resulting of the merging of two backups having different in-place path).

TESTING AND DIFFERENCE SPECIFIC OPTIONS (to use with -t or -d)

-ado-not-compare-symlink-mtime, --alter=do-not-compare-symlink-mtime

With this option set, when comparing a symlink, no message shows when symlink in archive and symlink on filesystem do only differ by their mtime. See also -O option.

-ap, --alter=place

is also available as described just above for restoration options.

No other specific option, but all general options are available except for example -w which is useless, as testing and comparing only read data. -A option is available as described in GENERAL OPTIONS to backup of internal catalogue of the archive (assuming you have a previously isolated catalogue available).

Doing a difference in sequential read mode is possible but hard linked inodes can only be compared to the filesystem the first time they are met, next hard links to this same inode cannot obtain the corresponding data because skipping backward in sequential read mode is forbidden. In that situation, the hard links are reported as skipped, meaning that data comparison could not be performed.

LISTING OPTIONS (to use with -l)

-T, --list-format=<normal | tree | xml | slicing>

-as, --alter=saved

list only saved files

-alist-ea, --alter=list-ea

list Extended Attributes name for each file that has some.

-ay, --alter=byte, --alter=bytes

by default files size is displayed to occupy the shortest number of characters by using the largest unit possible (KiB, MiB, GiB, and so on). With this option instead, the size is displayed with maximum precision using the exact number of bytes used for each file.

-I, -X, -P, -g, -[, -]

can be used to filter file to list base on their name or path.

-aheader

displays the header (when --sequential-read is used) or the trailer of the archive and then stops. This archive header/trailer is always in clear text even when the archive is ciphered. This option is here to let you access to these fields without providing the encryption key.

From the general options it seems only -vm and -b stay useful here. Note that -vm displays an archive summary first, where a detailed of information about the archive can be obtained. If you want to display only this summary use -q with -l option.

displayed

fields

EXPLICIT OPTIONAL ARGUMENTS¶

When dar has not been compiled with GNU getopt, which is not present by default on some systems like FreeBSD, you may lack the optional arguments syntax. For example "-z" will create a parse error on command-line, or in -B configuration files. The solution is to explicitly give the argument. Here follows a list of explicit argument to use in place of optional ones:

-z

must be replaced by -z 9

-w

must be replaced by -w d or -w default

-H

must be replaced by -H 1

-0

must be replaced by -0 ref

-5

must be replaced by -5 ""

-p

must be replaced by -p 1

-v

must be replaced by -v all

-k

must be replaced by -k ignore

-5

must be replaced by -5 user.libdar_no_backup

-M

must be replaced by -M I:/

important ! When using GNU getopt(), optional arguments are available by sticking the argument to the short option: "-z" for example is available as well as "-z9". But "-z 9" is wrong, it will be read as "-z" option and "9", a command line argument (not an argument to the -z option). In the other side, when using a non GNU getopt this time, "-z" becomes an option that always requires an argument, and thus "-z 9" is read as "-z" option with "9" as argument, while "-z9" will be rejected as a unknown option, and "-z" alone will generate an error as no argument is provided. In consequences, you need a space between the option (like "-z") and its argument (like "9"), when dar does not rely on a GNU getopt() call, which also imply you to explicitly use arguments to options listed just above.

EXIT CODES¶

dar exits with the following code:

0

Operation successful.

1

Syntax error on command-line or DCF included file

2

Error due to a hardware problem or a lack of memory.

3

Detection of a condition that should never happen, and which is considered as a bug of the application.

4

Code issued when the user has aborted the program answering a question from dar. This also happens when dar is not run from a terminal (for example launched from crontab) and dar has a question to the user. In that case, dar aborts the same way as if the user pressed the escape key at the question prompt.

5

is returned when an error concerning the treated data has been detected. While saving, this is the case when a file could not be opened or read. While restoring, it is the case when a file could not be created or replaced. While comparing, it is the case when a file in the archive does not match the one in the filesystem. While testing, it is the case when a file is corrupted in the archive.

6

an error occurred while executing user command (given with -E or -F option). Mainly because the creation of a new process is not possible (process table is full) or the user command returned an error code (exit status different from zero).

7

an error has occurred when calling a libdar routine. This means the caller (dar program), did not respect the specification of the API (and this can be considered as a particular case of bug).

8

the version of dar used is based on finite length integers (it has been compiled with the option --enable-mode=...). This code is returned when an integer overflow occurred. use the full version (based in the so called "infinint" class) to avoid this error.

9

this code indicates an unknown error. The exception caching code to take care of new exceptions has probably been forgotten to be update ... this is a minor bug you are welcome to report.

10

you have tried to use a feature that has been disabled at compilation time.

11

some saved files have changed while dar was reading them, this may lead the data saved for this file not correspond to a valid state for this file. For example, if the beginning and the end of the file have been modified at the same time (while dar is reading it), only the change at the end will be saved (the beginning has already been read), the resulting state of the file as recorded by dar has never existed and may cause problem to the application using it. This is known as a "dirty" file in the archive.

SIGNALS¶

If dar receives a signal (see kill(2) man page) it will take the default behavior which most of the time will abruptly abort the program, except for the following signals:

SIGINT

This signal is generated by the terminal when hitting CTRL-C (with the terminal's default settings), it can also be generated with the kill command

SIGTERM

This signal is generated by the system when changing of run-level in particular when doing a shutdown, it can also be generated with the kill command

SIGHUP

Depending on the system, this signal may be sent before the SIGTERM signal at shutdown time, it can also be generated with the kill command

SIGQUIT

This signal is generated by the terminal when hitting CTRL-\ (with the terminal's default settings), it can also be generated with the kill command

SIGUSR1

This signal can be generated by the kill command

SIGUSR2

This signal can be generated by the kill command

For those previous signals, two behavior exit. For SIGHUP, SIGINT, SIGQUIT, SIGTERM and SIGUSR1, a delayed termination is done: the backup or isolation operation is stopped, the catalogue is appended to the archive and the archive is properly completed with the correct terminator string, this way the generated archive is usable, and can be used as reference for a differential backup at a later time. Note that if an on-fly isolation had been asked, it will *not* be performed, and no user command will be launched even if dar has been configured for (-E option). For SIGUSR2 instead a fast termination is done: in case of backup or isolation, the archive is not completed at all, only memory and mutex are released properly.

For both type of termination and other operations than backup or isolation, dar's behavior is the same: For restoration, all opened directories are closed and permissions are set back to their original values (if they had to be changed for restoration). For listing, comparison, testing, the program aborts immediately.

Another point, when using one of the previous signals, dar will return with the exist status 4 meaning that the user has aborted the operation. Note that answering "no" to a question from dar may also lead dar to exit this way. last, If before the end of the program the same signal is received a second time, dar will abort immediately.

FILES¶

$HOME/.darrc and /etc/darrc if present are read for configuration option. They share the same syntax as file given to -B option. If $HOME/.darrc is not present and only in that case, /etc/darrc is consulted. You can still launch /etc/darrc from .darrc using a statement like -B /etc/darrc. None of these file need to be present, but if they are they are parsed AFTER any option on the command line and AFTER included files from the command line (files given to the -B option). NOTE: if $HOME is not defined $HOME/.darrc default to /.darrc (at the root of the filesystem).

Else you can see conditional syntax below, and -N option above that leads dar to ignore the /etc/darrc and $HOME/.darrc files.

CONDITIONAL SYNTAX¶

configuration files (-B option, $HOME/.darrc and /etc/darrc) usually contain a simple list of command-line arguments, split or not over several lines, and eventually mixed with comments (see -B option for more). But, you can also use make-like targets to ask for a particular set of commands to be used in certain conditions.

A condition takes the form of reserved word immediately followed by a colon ':'. This word + colon must stand alone on its line, eventually with spaces or tabs beside it. The available conditions are:

extract:

all options listed after this condition get used if previously on command line or file the -x command has been used

create:

all options listed after this condition get used if previously on command line or file (-B option) the -c command has been used

list: (or listing:)

if -l command has been used

test:

if -t command has been used

diff:

if -d command has been used

isolate:

if -C command has been used

merge:

if -+ command has been used

repair:

if -y command has been used

reference:

if -A option has been used (except when -A is used for the snapshot feature or in conjunction with -af)

auxiliary:

if -@ option has been used

all:

in any case

default:

if no -c, -d, -x, -t, -C, -l or -+ option has been used at this point of the parsing.

The condition stops when the next condition starts, or at End of File. The commands inserted before any condition are equivalent to those inserted after the "all:" condition. Remark : -c -d -x -t -C and -l are mutual exclusive, only one of them can be used while calling dar.

Here is an example of conditional syntax

Last point, you may have several time the same condition (several all: ) for example. They will be concatenated together.

USER TARGETS¶

User targets are arbitrary words found on command line, that do not start by a dash ('-'). On most system they should be placed after command and options. They are collected from command-line first, then comes the parsing of command and optional arguments. Their use is to extend conditional syntax described just above by having a set of options activated by the user just adding a single word on command-line. Of course user targets must not be equal to one of the reserved words of the conditional syntax (extract, create, ... all, default). A valid target is a word (thus without space) composed of lowercase or uppercase letters (case is sensitive) with eventually digits, dashes '-' or underscores '_' characters.

Let's see an example of use:

first a DCF file named 'example.dcf' that will be given on command line:

Then we could run dar in the following ways:

dar -c test -B example.dcf

in that case only the command in the "create:" section of example.dcf would be used.

dar -c test -B example.dcf verbose

here over the "create:" target the commands under the "verbose:" target (-v and -vs) would be also used

dar -c test -B example.dcf verbose home

last we use two user targets "verbose:" and "home:" in addition the the "create:" target of the usual conditional syntax.

Note that if the last option *may* receive an argument, the first user target that follows it will be assumed an argument to that option. To avoid this, either change the order of options on command line for the last option been an option that never or always uses an argument (for example -b never has an argument while -s always has one). Or separate the options from the user targets by the -- word. And of course you can also use the explicit argument of the last option (see EXPLICIT OPTIONAL ARGUMENT section, above).

Second point: It is allowed to have user targets inside a DCF file. Note however that targets are collected in a first phase, which leads some part of the file to be hidden (because the corresponding conditional syntax or user target is not present). Then, the remaining part of the file is then parsed and actions for each option found is taken. At that time, new user targets found are just recorded, but they do not modify the current DCF file layout, in particular, hidden part of the file stay hidden even if the corresponding user target is read in this same file. Next DCF parsing (which may be triggered by a second -B option on the command line, or by a -B option inside the current parsed DCF file) will thus be done with the additional targets found in that first DCF file, so in a way you may have user targets that activate other user targets, but they will be activated in starting the next -B file. Here follows an examples of two DCF files, first.dcf and second.dcf:

ENVIRONMENT¶

DAR_DCF_PATH

if set, dar looks for Dar Configuration File (DCF files, see -B option) that do not have an fully qualified path in the directories listed in DAR_DCF_PATH environment variable. This variable receives a colon (:) separated list of paths and look in each of them in turn, up to the first file found under the requested name.

DAR_DUC_PATH

if set, dar looks for Dar User Command (DUC files, see -E, -F, -~, -= options) that do not have a fully qualified path in the directories listed in DAR_DUC_PATH. This variable receives a colon (:) separated list of paths and looks in each of them in turn, up to the first file found under the requested name.

DAR_SFTP_KNOWNHOSTS_FILE

if set, dar will not use the $HOME/.ssh/known_hosts file to check sftp remote server authenticity but the file given as value for this environment variable. Note that setting this variable to an empty string completely disable host validation, which is not recommended. Dar, the command line interface program for disk archive relies on libdar for archive format management which relies on libcurl for network transfer which in turn relies on libssh2 for all that concerns ssh/sftp protocol. In the known_hosts file, libssh2 does not support recent lines like those with "ecdsa-sha2-nistp256" in second argument before its release 1.9.0 (you will also need curl/libcurl 7.69.1 or more recent), in these old versions you only have support for "ssh-rsa" lines. Check libssh2 and libcurl documentations and literature for more details about that limitation. The workaround, if you have not yet libssh2 1.9.0 or more recent, is to disable known hosts validation or set up a restricted known hosts file without any "ecdsa*" entry and have DAR_SFTP_KNOWNHOSTS_FILE pointing to it.

DAR_SFTP_PUBLIC_KEYFILE

by default dar will fetch the public key file in $HOME/.ssh/id_rsa.pub file. If you use the former id_dsa.pub or more recent key types you need to set this environment variable to point to the appropriated filename

DAR_SFTP_PRIVATE_KEYFILE

by default dar will fetch the public key file in $HOME/.ssh/id_rsa file. If you use the former id_dsa.pub or more recent key types you need to set this environment variable to point to the appropriated filename

DAR_IGNORED_AS_SYMLINK

receive a colon separated list of absolute paths, which if they are symlinks are not saved as symlink but as the inode they point to. For more details see the --ignored-as-symlink option above.

GNUPGHOME

for asymmetric encryption and signature, the keyring used is $HOME/.gnupg by default. You can change this default by setting GNUPGHOME to the directory containing the keyring. For example, if you are running dar as root and want to use your unprivileged account keyring use the following:

CAPABILITIES¶

dar fully supports the cap_chown capability, but by design, dar only uses this capability to restore files at their original ownership. Dar will thus not use this capability to access files and directories the caller would normally not have access to. In other words, it should be ok to set the cap_chown capability to the dar executable (setcap cap_chown+p dar). Calling dar from a process having the cap_chown in the inheritable set would lead the system to grant this capability to the dar process while other users would not be granted this capability and would not be able to modify ownership of files at restoration time. This can be used for the system account that has the role of restoring data upon user requests, without giving root privilege to this restoration process.

EXAMPLES¶

You can find some more examples of use in the tutorial, mini-howto, sample scripts, and other related documentation. All these are available in dar's source package, and are also installed beside dar in the <--prefix>/share/dar directory. This documentation is also available on-line at http://dar.linux.free.fr/doc/index.html

SEE ALSO¶

dar_xform(1), dar_slave(1), dar_manager(1), dar_cp(1), dar_split(1), TUTORIAL and NOTES included in the source package and also available at http://dar.linux.free.fr/doc/index.html

KNOWN LIMITATIONS¶

dar saves and restores atime, mtime, birthtime but cannot restore ctime (last inode change), there does not seems to be a standard call to do that under UNIX. An up to date list of known limitation is at http://dar.linux.free.fr/doc/Limitations.html

KNOWN BUGS¶

http://sourceforge.net/p/dar/bugs/

AUTHOR¶

http://dar.linux.free.fr/
Denis Corbin
France
Europe