Provided by: dar-static_2.7.16-1_amd64 
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
The eight actions you can performs with dar
GENERAL OPTIONS
A set of options common to all actions
SAVING, ISOLATING, MERGING AND REPAIRING SPECIFIC OPTIONS
A set of options that are specific to the operation of backup, catalogue isolation and
archive merging
RESTORATION SPECIFIC OPTIONS
A set of options that are specific to the restoration operation
TESTING AND DIFFERENCE SPECIFIC OPTIONS
A set of options that are specific to the operation of archive testing and archive comparison
with a filesystem
LISTING OPTIONS
A set of options that are specific to archive listing operation
EXPLICIT OPTIONAL ARGUMENTS
Some system do not allow optional arguments to options, this chapter explain how to overcome
this restriction
EXIT CODES
List of values dar returns at end of execution. This chapter should be read if you intend to
create scripts relying on dar
SIGNALS
details the signal and their action on a running dar process
FILES
List configuration files that dar checks for
CONDITIONAL SYNTAX
Over command line, command and options can be passed to dar thanks to a plain file (known as
DCF file). This plain file can also contain a specific syntax that will let you pass an
option to dar only under certain situation/condition. This chapter describes this simple
syntax and the different available conditions.
USER TARGETS
User can add their own conditions known as user targets. This chapter describes what they are
and how to use them
ENVIRONMENT
Dar may rely on environment variables to look for DCF files and DUC files, SFTP private and
public key and so on.
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).
During the repairing operation, the repaired archive may have a different slicing (-s and -S
options), a different encryption (-K and associated options, including gpg encryption and
signing), a different repository slices permissions and ownership (--slice-mode option), user
comment (--user-comment), generated hash (--hash) and min digits in slice number (--min-digits),
but compression cannot be changed and tape marks cannot be removed (you can do it once repair has
completed using the merging operation). Last, file filtering is not allowed during archive
repairing.
-h, --help displays help usage.
-V, --version displays version information.
Remote repository syntax for [<URL>]<path>
for all commands described above as well as some options detailed below (-A and -@ options), the
<path> optional argument can be a Unix path like /var/tmp when the archive is located on the host
dar runs on. But it can also make use of <URL> to define the remote host the archive is to be read
or written to. "<URL><path>" follows the usual syntax:
proto://[login[:password]@]hostname[:port]/path
proto
is either ftp or sftp
login
is optional, if not provided it defaults to anonymous. If the login string comports an @ it
need to be escaped by \\ (a pair of backshashes) to avoid libdar considering it the hostname
starting part. Example: login is me@here.com host is www.example.org gives:
sftp://me\\@here.com@www.example.org/some/file. You may also need to escape the same way any
other special characters like for example colon (:) slash (/) if they are part of the login
string.
password
if login is provided, the associated password may be given after a colon (:) but this exposes
the secret password to other users of the current system having access the table of process
(using top, ps, /proc or other ways). If the login is given without password, the password will
be asked interactively by dar at run time, which is much more secure. Alternatives are either
to rely on ~/.netrc for FTP and also SFTP (!) transfers for that you need to use the
--alter=file-authentication option (see below), or for SFTP only on public key authentication
(you can also use --alter=file-authentication in that case to avoid a password being asked
interactively). Note that passphrase support for sftp key is not (yet) supported.
hostname
is the name or IP address of the host to connect to. For sftp the server's public key is
checked against the ~/.ssh/known_hosts file (or the file pointed to by then environment
variable DAR_SFTP_KNOWNHOST_FILE, see more details about that variable at the bottom of this
man page), the host must be known and the public key received from the network must match the
one in that file, else dar aborts. If thus you want to operate with a new sftp server, first
use ssh of sftp commands to do the usual fingerprint verifications which updates the
known_hosts file accordingly, then run dar/libdar toward this sftp server.
port
if not provided, dar will use the default/standard port in regard to the protocol specified in
the "proto" field
path
a unix path where resides the archive to read from the remote repository or where to write the
archive to in that remote repository. The given path is absolute, in regard to the remote root
filesystem available for the given account though the requested protocol. See also --network-
retry-delay option below.
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:
- An existing archive basename, which will be taken as reference
- a dash ("-") in direct access mode (default mode, when --sequential-read is
not used) it may imply the use of -o and -i options, this allows the archive
of reference to be read from a pair of pipes with dar_slave at the other ends.
Dar_slave can be run through ssh on a remote host for example. Note that this
type of argument ("-") is only available when -A is used for isolation (-C
option) and merging (-+ options). In sequential mode (--sequential-read is
used), the archive of reference is read from standard input or from the named
pipe specified by -i option. -o option has no use in sequential mode. Note
that merging operation (-+ option) cannot read archive of reference in
sequential mode.
- a plus sign ("+") which makes the reference be the current directory status.
This argument is only available for archive creation (-c option). In other
word, no file's data will be saved, just the current status of the inodes will
be recorded in the catalogue. This feature is known as the "snapshot" backup.
A snapshot backup can be used as reference later on to detect or save only the
files that have changed since the snapshot was made.
- a <date>, if -af option has been placed before -A on the command-line or in
a included file (see -B option). For more about that feature see -af option
below. This form is only available for archive creation (-c option).
During backup operation (-c option) the archive of reference, given thanks to the -A
option, is used for comparison with existing files on the filesystem. Dar will then
backup only files that have changed since the archive of reference was done. If no -A
option is given, the backup operation is a full backup. With -A option if the archive
of reference is a full backup some call it a differential backup, while if the
archive of reference is differential backup, some call this type of backup an
incremental backup. For dar there is no difference in structure between incremental
and differential backup, both are usually designed globally as "differential" backup
in the documentation.
During merging operation (-+ option), the contents of the -A given archive will been
taken eventually with the contents of the -@ auxiliary archive if specified (see
below), to form a new archive from files of this or these archives. Note that you can
filter out files from the operation and setup subset of the original archive(s).
During Catalogue isolation (-C option), dar will create the isolated catalogue from
the one given with -A option.
During testing, diff or extraction, (-t, -d or -x options respectively), the table of
contents (the catalogue) will be read from the archive given with -A instead of using
the internal catalogue of the archive. The archive given for rescue must has been
previously isolated from this same archive (else the contents will not match and dar
will refuse to proceed to this operation). This acts as a backup solution to the case
of corruption inside an archive's catalogue, while the best way is still to use
Parchive to protect your data against media error.
-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.
<date> must be a date in the two following possible formats:
- a number of second since Jan 1st, 1970
- a date in the following form [[[year/]month/]day-]hour:minute[:second]
Here are some examples of date:
91836383927108078
1 2005/11/19-19:38:48 Which is 38 past 7 PM and 48 seconds, the 19th of
November 2005
20:20 Which is 8 PM of the current day
2-00:08 Which is 8 past noon, the second day of the current month
2/2-14:59 Which is 1 to 3 PM, the 2nd of February in the current year
Note that the provided date is relative to the system timezone which is overridden if
the TZ environment variable is set (see tzselect(1) for more details)
-@, --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.
In a merging context, over -A option which is mandatory, you may give a second
archive of reference thanks to the -@ option. This allows you to merge two archives
into a single one. See also -$ option (encryption) -~ option (command execution) and
-% (crypto block size) for other options concerning auxiliary archive of reference.
They are the respective equivalent of -J, -F and -* options relative to archive given
thanks to -A option.
In a backup context -@ option let the user specify the archive name for an on-fly
isolation. With on-fly isolation, you can also use -$ option (to define encryption
algorithm and passphrase), -~ option (to execute a command once the on-fly isolated
catalogue is completed) and -% option (crypto block size). On-fly isolated catalogue
is always bzip2 if possible else gzip else lzo compressed (using compression level 9)
else not compressed, and it is also always a single sliced archive. Due to command-
line exiguity, it is not possible to change compression algo nor slice size for the
on-fly isolation. If you need a more complicated isolation, either look for a GUI
over libdar, or do a normal (= not an on-fly) isolation operation (By the way it is
possible to isolate an already isolated catalogue, this is equivalent to doing a
copy, but you can change encryption, compression or slicing, for example), you can
also use dar_xform on an isolated catalogue if you only want to change slices size
(this is faster as no decompression/re-compression nor encryption/decryption is
necessary). Using the merging operation on an isolated catalogue instead of isolating
the isolated catalogue, leads the resulting archive to not be able to be used as a
rescue for internal catalogue of the original archive. --aux-ref is a synonym to
--aux.
-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:
the normal method is the default and is the one that has been presented above:
A directory is elected for operation if no -P or -] option excludes it. If at least one -g or
-[ option is given on command line, one -g or -[ option must cover it, else it is not elected
for operation. If a directory is not selected, no recursion is done in it (the directory is
pruned). For non directories files, the same is true (P, -g, -[ and -] do apply) and a second
test must also be satisfied: no -X option must exclude the filename, and if at least one -I
option is given, one must match the given filename (using or not wildcards).
the ordered method (when -am option is given on command-line):
The ordered method takes care of the order of presence between -X and -I in one hand and of
-P, -g, -[ and -] in the other hand (note that it has also the same action concerning EA
selection when using -u and -U options, but that's no more file selection). In the ordered
method the last argument take precedence over all the previous ones, let's take an example:
-X "*.mp?" -I "*.mp3" -I "toto*"
Here dar will include all files except file of name "*.mp?" (those ending with "mpX"
where X is any character), but it will however include those ending with ".mp3". It will
also include files which name begin by "toto" whatever they end with. This way,
"toto.mp2" will be saved (while it matches "*.mp?" it also begins by "toto") as well as
"toto.txt" as well as "joe.mp3" (while it matches "*.mp?" it also ends by "mp3"). But
will not be saved "joe.mp2" (because it does not begin by "toto", nor ends by "mp3", and
match "*.mp?" mask). As we see the last option (-I or -X) overcomes the previous one.
-P, -g, -[ and -] act together the same but as seen above they do not only act on
filename, but on the whole path+filename. Note that (-g, -P, -[, -]) and (-X , -I) are
independent concerning their relative order. You can mix -X -I -g -P -] -[ in any order,
what will be important is the relative positions of -X options compared to -I options,
and the relative positions of -g -[ -] and -P options between them.
In logical terms, if <prev_mask> is the mask generated by all previous mask on the command line,
-I <mask> generates the new following mask: <prev_mask> or <mask> . While -X <mask> generates the
new following mask: <prev_mask> and not <mask>. This is recursive each time you add a -I or -X
option. Things work the same with -P, -g, -[ and -] options.
This ends the file selection explication let's continue with other options.
-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)
Support for EA must be activated at compilation time (the configure script tries to do so if your
system has all the required support for that). Thus you can get two binaries of dar (of the same
version), one supporting EA and another which does not (dar -V to see whether EA support is
activated). The archives they produce are the same and can be read by each other. The only
difference is that the binary without EA support is not able to save or restore EAs, but is still
able to test them and list their presence.
In the following when we will speak about Extended Attribute (EA) or EA entry, we will only
consider a particular Extended Attribute key and its value. By opposition, the set of all EA
associated to a file will be designated by "EA set".
Since version 2.3.x the name of EA entries include the namespace for dar be able to consider any
type of EA (not only "system" and "user" as previously). Thus the two previous options -u and -U
have changed and now take an argument which is a mask applied to EA entry names written in the
following form namespace.name where "namespace" is for example "user". Note that the mask may or
may not include the dot (.) and may match arbitrary part of the EA namespace+name, just remind
that masks will be applied to the "namespace.name" global string.
the -am flag here also enables the ordered method, for EA selection too. The ordered versus normal
method have been explained above in the file selection note, with some examples using -X and -I.
Here this is the same with -U and -u, (just replace -X by -u and -I by -U, the corresponding mask
will apply to Extended Attribute selection in place of file selection).
Another point, independently of the -am option the -ae option can be used at restoration time
only. If set, when a file is about to be overwritten, all EA will be first erased before restoring
those selected for restoration in the archive (according to the -U and -u options given). If not
set, the EA of the existing file will be overwritten, those extra EA that are not in the archive
or are not selected for restoration in regard to the -u and -U options will be preserved. If you
have not used any -u/-U option at backup time and want to restore from a set of full/differential
backups the EA exactly as they were, you have to use -ae for dar removes the EA before overwriting
their set of EA as stored in the archive. Without -ae option dar will simply add EA to existing
ones, thus get a different set of EA for a give file than those recorded at the time of the
backup.
Last point the -acase and -an options alters the case sensitivity of the -U and -u masks that
follow them on the command-line/included files as they do for -I, -X, -P, -g, -[ and -] as well.
Very last point ;-), if -ac option is used during backup dar set back the atime after having read
each file (see -aa/-ac options), this has as side effect to modify the ctime date of each file.
But ctime change is used by dar to detect EA changes. In brief, the next time you backup a file
that had to be read (thus which contents changed), its EA will be saved even if they had not
changed. To avoid this side effect, don't use the -ac option if not necessary.
This ends the Extended Attribute selection explication let's continue with other options.
-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:
extX this family takes care of Linux ext2/3/4 flag attributes set by chattr(1) and
read by lsattr(1). Dar only considers flags that are possible to set or clear by
users (or privileged user): append-only, compressed, no_dump (Yes, dar can save
files having the nodump flag set and restore then afterward with that flag
set!), immutable, data-journaling, secure-deletion, no-tail-merging,
undeletable, noatime-update, synchronous-directory, synchronous-update, top-of-
directory-hierarchy. Note that "extx" and "ext" are aliases for this FSA family.
In spite of its name, this family of attributes is not limited to ext2/3/4
filesystems.
HFS+
this family takes care of Mac OS X HFS+ birth date of files, in addition of
commonly found dates like atime (last access time), ctime (last meta data
change) and mtime (last data change).
none "none" is not a FSA family but can be used alone to ignore all FSA families.
By default no restriction is done and FSA of all families are considered at
restoration time, but if a family has not been activated at compilation time a
warning is issued for each file that cannot have its FSA restored completely (unless
this family is excluded from the scope thanks to the -4 option). At backup time, if
an FSA family has not been activated at compilation time, no warning is issued and
FSA of that family are ignored. Still at backup time, you can also ignore FSA that
have compilation time support by excluding them from the operation thanks to this -4
option.
Example of use: --fsa-scope extX,HFS+
-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:
ignore-owner all fields are considered except ownership.
This is useful when dar is used by a non-privileged user. It will not
consider a file has changed just because of a uid or gid mismatch and
at restoration dar will not even try to set the file ownership.
mtime only inode type and last modification date is considered as well as
inode specific attributes like file size for plain files. Ownership is
ignored, permission is ignored. During comparison, difference on
ownership or permission is ignored and at restoration time dar will
not try to set the inode permission and ownership.
inode-type Only the inode type is considered. Ownership, permission and dates are
ignored. Inode specific attributes are still considered (like file
size for plain files). Thus comparison will ignore differences for
ownership, permission, and dates and at restoration dar will not try
to set the ownership, permission and dates.
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:
%% will be replaced by %
%p will be replaced by the slice path
%b will be replaced by the slice basename
%n will be replaced by the slice number (to be read or just written). For
reading, dar often needs the last slice, but initially it does not know its
number. If it cannot be found in the current directory, the user command-
line is then called with %n equal to 0. This is a convenient way to inform
the user command to provide the last slice. If after executing the string
the requested slice is still not present, dar asks the user (as usually)
with a message on the terminal. Once the last slice is found, the user
command-line is called a second time, with %n equal to the value of the
last slice number.
%N is the slice number with the leading zero as defined by --min-digits
option. If this option is not used, %N is equivalent to %n.
%e will be replaced by the slice extension (always substituted by "dar")
%c will be replaced by the context. Actually three possible values exist:
"init", "operation" and "last_slice". When reading an archive for (testing,
extraction, diff, listing, or while reading the archive of reference, see
below the -F option), the "init" context takes place from the beginning up
to the time the catalogue is retrieved. On a multiple slice archive this
correspond to the last slice request. After, that point comes the
"operation" context. While creating an archive, the context is always
"operation" except when the last slice has been created, in which case the
context is set to "last_slice".
%u will be replaced by the full URL of path where the slice is stored
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:
dar --aduc -E script1 -E script2 ...
leads libdar to call a shell with the following line "script1 && script2"
dar -E script1 -script2 --aduc -E script3 ...
leads libdar to call a shell with the following line "script1 ; script2 && script3". In other
words if you want to avoid the ";" use --aduc before any -E/-F/-~ option.
-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[...]]
In the first syntax, encrypt/decrypt the archive using the <algo> cipher with the
<string> as pass phrase. An encrypted archive can only be read if the same pass
phrase is given (symmetric encryption). Available ciphers are "blowfish" (alias
"bf"), "aes", "twofish", "serpent" and "camellia" for strong encryption and
"scrambling" (alias "scram") for a very weak encryption. By default if no <algo> or
no ':' is given, the aes256 cipher is assumed (default was blowfish up to 2.5.x). If
your password contains a colon ':' you need to specify the cipher to use (or at least
use the initial ':' which is equivalent to 'bf:'). If the <string> is empty the pass
phrase will be asked at execution time. Thus, the smallest argument that -K can
receive is ':' which means aes256 cipher with the pass phrase asked at execution
time.
Note that giving the passphrase as argument to -K (or -J or '-$' see below) may let
other users learn pass phrase (thanks to the ps, or top program for examples). It is
thus wise to either use an empty pass which will make dar ask the pass phrase when
needed, or use -K (or -J option) from a Dar Command File (see -B option), assuming it
has the appropriated permission to avoid other users reading it. For those paranoids
that are really concerned about security of their passwords, having a password read
from a DCF is not that secure, because while the file gets parsed, dar makes use of
"unsecured" memory (memory than can be swapped to disk under heavy memory load
conditions). It is only when the passphrase has been identified that locked memory
(aka secure memory) is used to store the parsed passphrase. So, the most secure way
to transmit a passphrase to dar, then to libdar, then to libgcrypt, is having dar
asking passphrase at execution time, dar then makes use of secured (locked) memory
from the beginning.
since archive format 9 (archive generated by release 2.5.0 and following) at reading
time, it is not necessary to provide the encryption algorithm used, just the
passphrase is required, dar will figure out which encryption algorithm had been used
at archive creation time. You can either omit -K in which case dar will ask for the
passphrase at execution time, or you can use -K <string> in a DCF file as explained
above (avoid using -K directly on command-line).
The second syntax starts with the word "gnupg" followed by a colon ':' . In that
situation, the same set or symmetric encryption algorithms as described above is
available after the colon, but the passphrase is not given by the user but randomly
chosen by libdar and encrypted using the public key of the target users which email
okkeyid (since 2.7.0) is given in a comma separated list. This random key (see also
--key-length below), once encrypted is placed at the beginning and at the end of the
generated archive. At reading time only the listed user will be able to read that
archive thanks to their respective private key. This feature implies that each user
(the archive creator as well as the target users) have their GnuPG keyring set
properly. In particular, the archive creator must have validated the public keys of
the target users, and the target users must own the corresponding private key in
their keyring. Example: using "--key gnupg::bob@nowhere.org,joe@somewhere.com" will
generate an aes256 encrypted archive which passprhase randomly chosen by libdar will
be encrypted with the public keys of bob@nowhere.org and joe@somewhere.com. To use
blowfish in place of ars256 one could use "--key
gnupg:bf:bob@nowhere.org,joe@somewhere.com". Note that no check is done about the
trust you have set in GPG keyring that a particular public key is owned by the
phyical person you expect. See also --sign option below.
Note that if you have set a passphrase on your private key, dar will ask it
dynamically, which requires dar to be run from a terminal. No other way has been
provided to transmit a private key's passphrase to libdar. In consequence if you want
to use dar/libdar in scripts and make use of public key algorithm you should avoid
setting a passphrase to the private key you want to use. See also GNUPGHOME in the
ENVIRONMENT section at the end of this document.
Obvious but important! To read a gnupg encrypted archive, you need your private key
(not only the passphrase to activate it, if set). Thus if you plan to make backup of
your system and encrypt the backup using gnupg, you should have a copy of this
private key available out of the archive (usb key, floppy, CD/DVD, ...) in order to
be able to restore your backup!
-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 -y)
-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.
algo:
the following values are available "gzip", "bzip2", "lzo", "xz", "zstd" or "lz4".
level:
The compression level (an integer from 1 to 9 except for zstd which ranges from 1 to 22) is
optional, and is 9 by default. Be careful when using xz algorithm better specify a compression
ratio less than or equal to 6 to avoid important memory requirements. A ratio of 1 means less
compression and faster processing, while at the opposite a ratio of 9 gives the best
compression but longest processing time.
block-size:
if set to zero (which is also the default value), you will get the legacy (and performant)
"streaming compression" mode that was the only available up to release 2.7.0. Since then, the
"block compression" mode gives the ability to leverage multi-threading (see -G option) by
compressing per block and giving different blocks to different threads. The larger the block
is, the better the compression ratio will be (it tends to be as good as the one of the
streaming compression mode, when block size increases), but files smaller than a block size can
only be processed by a single thread. The memory requirement also increases by the product of
the block size times the number of threads. Last, a too small block-size will cost more CPU
cycles (the multi-threading management overhead will become important compared to the effective
compression processing) and independently, short blocks gives poor compression rates. It is
thus advised to use values at least greater than 50 ~ 100 KiB (you can use the k,M,G,...
suffixes described for the -s option). If the block-size is not specified and given -G option
leads to a number of compression threads greater or equal to 2, a block-size of 240 KiB is
used. If you want the legacy streaming compression, do not use -G option (or use it specifying
only 1 compression thread) and do not set the compression block size (or set it to zero).
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.
As soon as you use -/ option -n only applies only to slice overwriting and the -r, -k
and -ae options are ignored (restoration specific options).
The given <policy> argument is composed of actions and eventually of conditional
expressions. Actions do define how to solve overwriting conflict about file's data on
one side and file's Attributes (Extended and Filesystem Specific) on the other side.
An action is thus a couple of action for Data and for EA+FSA. Actions for Data are
represented by uppercase letters, while action for EA+FSA are defined by lowercase
letters. Both actions are independent of each other:
P means 'Preserve'. When merging two archives, the data of the resulting archive
will be taken from the 'in place' file. While when extracting, the data of the
inode in filesystem will be preserved (thus no overwriting will occur for the
data).
O means 'Overwrite'. When merging two archives, the data of the resulting archive
will be taken from the 'to be added' file. While when extracting, the data of
the inode in filesystem will be overwritten by data from the archive.
S means 'mark Saved and preserve'. When merging two archives, the data of the
resulting archive will be marked as already saved in the archive of reference
(making thus a differential archive, even if none of the original archive were
differential archives). All data will be dropped in the resulting archive, but
the last modification date [aka mtime] (used to detect change in file's data)
will be taken from the 'in place' file. This action does not apply when
extracting files, it is thus considered equal to "Preserve" (P) in that
situation.
T means 'mark Saved and overwrite'. When merging two archives, the data of the
resulting archive will be marked as already saved (same as 'S' action): all data
will be dropped in the resulting archive, however the last modification date
[aka mtime] (used to detect changes in a file's data) will be taken from the 'to
be added' file. This action does not apply when extracting files, it is thus
considered equal to "Overwrite" (O) in that situation.
R means 'Remove'. When merging two archives, the resulting archive will not
contain any entry corresponding to the file that were in conflict. This also
implies that no EA will be stored for that particular entry as the entry will no
more exist in the resulting archive (as if it had never yet existed). When
extracting files, this will lead to file's suppression.
p means 'Preserve', same as 'P' (but lowercase letter) preserve the whole EA set
and FSA. When merging two archives, the Attributes set of the resulting file
will be the ones of the 'in place' file (whatever is the overwriting action
taken for its data). While when extracting files to filesystem, the Attributes
of the file in filesystem will not be changed (whatever is the overwriting
action taken for its data, unless the file is removed using the 'R' policy,
which would remove the inode and thus also any Attributes it had).
o means 'Overwrite', same as 'O' (but lowercase letter) overwrite the whole EA set
and FSA. When merging two archives, the Attributes set of the resulting file
will be taken from the 'to be added' file. While when extracting files, the
Attributes set of the file in the filesystem will have its Attributes erased and
replaced by those of the file in the archive (still independent of what
overwriting action is taken for file's data).
s means 'mark Saved and preserve', same as 'S' (but lowercase letter) for EA and
FSA instead of data. When merging two archives, the EA and FSA of the resulting
file are marked as already saved in the archive of reference, thus they are
dropped but the date of last inode change [aka ctime] (used to detect changes in
file's EA and FSA) will be taken from the 'in place' file. This action does not
apply when extracting files, it is thus considered equivalent to "Preserve" (p)
in that situation.
t means 'mark Saved and overwrite', same as 'T' (but lowercase letter) for EA and
FSA instead of data. When merging two archives, the EA and FSA of the resulting
file are marked as already saved in the archive of reference, thus they are
dropped but the date of last inode change [aka ctime] (use to track changes in
EA) will be taken from the 'to be added' file. This action does not apply when
extracting files, it is thus considered an equivalent to "Overwrite" (o) in that
situation.
m means 'merge Attributes and preserve'. The resulting file in the merged archive
will have Attribute entries from both the 'in place' and the 'to be added'
files. If both files share a same Attribute entry (same FSA or for EA the same
key for a given association) the one of the 'in place' file is kept (where from
the 'preserve' notion). When extracting a file, the file in the filesystem will
have its EA and FSA set enriched by the ones of the file in the archive that do
not exist on filesystem, but its already existing Attributes will stay
untouched.
n means 'merge Attributes and overwrite'. The resulting file in the merged archive
will have Attribute entries from both the 'in place' and the 'to be added'
files. If both files share a same Attribute entry (same FSA or for EA the same
key for a given association) the one of the 'to be added' file will be kept
(where from the 'overwrite' notion). When extracting file, the file in the
filesystem will have its Attributes set enriched by ones of the file in the
archive with some of them possibly been overwritten.
r means 'remove', same as 'R' but for the Attribute set (thus all EA and FSA
entries) of a given file ('r' is lowercase letter here). The file of the
resulting archive during merging operation will not own any EA nor any FSA, even
if the 'in place' and/or the 'to be added' files did have some. For file
extraction, this means that the file in the filesystem will loose all its EA
set. The FSA cannot be 'removed' from a filesystem and may not always have a
default value, thus this action does not modify FSA at all in case of archive
extraction. But in case of merging the FSA are removed as previously described.
As for all the previous tests, this Attribute operation is independent of the
operation chosen for file's data (uppercase letters).
d means 'delete'. When a same EA or FSA entry is found both in the 'in place' and
'to be added' files, such entry will be absent in the resulting archive. In
other words, when merging, the EA set and FSA will only contain EA and FSA
entries specific to the 'in place' and those specific to the 'to be added' file.
Entries in common will not be present. When extracting a file from an archive,
the file on filesystem will have its EA set enriched by entries of the 'to be
added' file that are new to the 'in place' file. The other EA entries (which are
thus present in both archive and filesystem) will be removed from the set, which
the other FSA will stay untouched (FSA cannot be "removed" from a filesystem,
nor they always have a default value).
* is valid for both EA and data. It tells that the action is not yet defined at
this step of the evaluation and that further evaluation is required (see the
'chain' operator below).
A means 'Ask for user decision'. This uppercase letter concerns Data overwriting.
An application interaction let the user define the action for each file in
conflict. Note, that this action if used alone may become very boring or
painful. The idea is to use it in conditional statements (which are described
below) to have dar ask for only non obvious cases.
a means 'Ask for user decision'. This lowercase letter is the equivalent for EA
and FSA of the 'A' action. It is intended to be used in the same conditional
statements described below.
An action is thus a couple of letters, the first being uppercase (for file's data)
the second being lowercase (for file's EA and FSA). When -/ option is not given, the
action is equivalent to '-/ Pp', making dar proceed to file, EA and FSA preservation.
Before release 2.4.0 (June 2011), only -n and -w options were available to define the
overwriting policy and the default behavior was to warn and wait for confirmation
before overwriting, which behavior can be set by the '-/ Oo' policy. It seems the
default behavior changed to '-/ Pp' at that time and nobody complained or noticed the
difference until 2023, so this default behavior will not be reverted, as nobody
complained for more than 12 years about that. Here follows some examples of actions,
all these are done for any entry found in conflict during archive merging or archive
extraction, we will see further how to define conditional actions.
-/ Rr
will lead dar to remove any file from filesystem that ought to be restored(!).
Note the action for EA/FSA is useless, the EA and FSA will always be erased as
well as data using 'R'. Thus '-/ Rp' would lead to the same result.
-/ Po
will keep data of the 'in place' file and EA and FSA set from the 'to be added'
file.
-/ Ss
Using this option when merging an archive with itself (used both as archive of
reference (-A option) and auxiliary archive of reference (-@ option) ) will
provide the same action as an archive isolation of the archive of reference, but
using twice more memory (so keep using the isolation operation as before! Here
this is just an illustration of the possibility)
As seem previously -u and -U options can be used to filter which EA entry to consider
and which to ignore. The question here is to explain how this filtering mechanism
interacts with the different policies we just presented above. For files that are not
in conflict (found only as 'in place' or as 'to be added'), only the EA entries
matching the EA filter are kept. For files in conflict, the overwriting policy is
evaluated first, then the filtering mechanism is applied *after* it. Thus for
example, using the following [ -/ "Po" -u "*test" ], when merging two archives, only
EA ending with "test" will be retained, and when a conflict takes place, this "*test"
ending EA will be taken from the 'to be added' file if it has some EA of that type,
its other EA entry will be ignored as well as any EA entry of the 'in place' file
even those ending by "test". At restoration in using the same options, file without
conflict will get restored but only EA entry ending with "test" will be restored, and
for file with conflict (already present in filesystem), EA set of file in filesystem
will be removed and replaced the EA entries of the file in archive that ends by
"test", if some exist.
the situation is similar with FSA family scope and overwriting policy. Only FSA of a
family present in the scope will be retained, the overwriting policy acts first then
the FSA scope is applied. Note however that any FSA present on filesystem and
excluded from the FSA scope are not touched.
Well, now let's see how to bring some more fun using conditional statements in all
these actions. The structure to use is the following:
{<condition>}[<action if condition is true>]
This syntax let you place an action (as the ones we saw just above) inside the
brackets '[' and ']' (for example [Pp]) that will take effect only if the
evaluation of the <condition> is true. Stated that a such statement is a new
type of action, you may have guessed that you may use it recursively:
{<condition1>}[{<condition2>}[<action>]).
Well so far it seems useless. But instead of the "if <condition> then <action> else
<action>" paradigm common to programming languages, due to the command line context
it has been chosen to instead use and implicit "OR" operator between actions. Thus
you can "stack" conditional statements this way: {<condition1>}[<action1>]
{<condition2>}[<action2>] <action3>. In this example, if <condition1> is true then
<action1> will be used, ELSE if <condition2> is true then <action2> will be used ELSE
<action3> will be used. This leads to the same possibilities as what is available
with programming languages, but with a slightly more simple syntax. Seen this, the
recursion of conditional syntax is more interesting. For readability, you are
allowed to add any space or tab in the overwriting policy, but the resulting
overwriting policy must be given as a single argument to dar, thus the use of quotes
(either simple ´arg´ or double "arg") is necessary.
The last operator we will see is the 'chain' operator. Once an expression is
evaluated, the resulting couple of action may contain an '*' (undefined action for EA
or data). Further evaluation must be done. The chain operator which is represented by
a semicolon ';' let one to separate several independent expressions that will be
evaluated in turn up to the time the couple of action is fully defined. Once an
action (for EA or for Data) is defined, it can be redefined by a subsequent
evaluation in the chain, however if the action is defined it cannot be set back to
undefined, thus '*' will never overwrite a previously defined action. If at the end
of the policy the couple of action is not fully defined, the 'preserve' action is
used ('P' or 'p' depending on which of EA or Data is left undefined). Here follow a
example of syntax:
-/ "{<condition1>}[P*] O* ; {<condition2>[*p] *o} ; Rr"
The first expression will evaluate to either P* or O*. At this step, as the
action is not completely defined, the second part of the chain is evaluated, It
will end with either *p or *o. In any case, we have after this second statement
of the chain a fully defined action for both data and EA (either Pp, Po, Op or
Oo). Thus the evaluation stops here and the "Rr" policy will never be evaluated.
We now have one last thing to see: the available conditions (what to place between
braces '{' and '}'). Conditions are defined each by a letter, eventually followed by
an argument between parenthesis. The usual logical operators are available: negation
(!), conjunction (&) disjunction (|). These characters must be escaped or quoted to
not be interpreted by the shell when used on command-line. In particular the '!'
under most shell must be quoted and escaped (-/ '{\!R}[..]..', The escape character
'\' is not necessary inside DCF files (those given to -B option) as no shell is used
to interpret these files. To these usual operators has been added a new one: the
"inversion" operator, noted '~'. Like the negation, it is an unary operator but
unlike the negation, it inverses the roles of 'in place' and 'to be added' for the
evaluation, which is slightly different from taking the negation of the result of the
evaluation. All these operators follow the usual precedence: unary operators ('!' and
'~') are evaluated first, then the conjunction '&' then the disjunction '|'. To
override this, you can use parenthesis '(' and ')' inside the condition. Over these
logical operators, the conditions are based on atomic operator that compare the 'in
place' file to the 'to be added' file. Here they follow:
I true only if the 'in place' entry is an inode. This condition does not have any
consideration toward the to be added object. Note that ~I can be used to check
the nature of the 'to be added' object. A 'detruit' entry, which record the fact
that a file has been removed since the archive of reference, is not an inode for
example, and the only type of entry that is not an inode is a 'detruit'. Thus
you can define an action on 'detruit' objects using the "!I" expression for the
'in place' entry and "!~I" for the 'to be added' entry.
D true only if the 'in place' entry is a directory. To know whether the 'to be
added' is a directory or not, one would use the "inversion" operator: ~D
F true only if the 'in place' entry is a plain file (true also if this plain file
is a 'hard link', that's it if its inode is linked several times to the
directory tree)
H true only if the 'in place' entry is an inode linked several times to the
directory tree (= hard link) it may be a plain file, a Unix socket, a pipe, char
device, a block device for example.
A same as H but the current 'in place' entry is the first link we meet pointing to
that hard linked inode.
R true if the 'in place' entry is more recent than or of same date as the 'to be
added' entry. The last modification date [aka mtime] is used for this
comparison. If the 'to be added' entry is not an inode (and thus has no mtime),
the 'in place' is considered to be more recent than the 'to be added' entry.
Same thing if the 'in place' entry is not an inode (and has no mtime available
for comparison), it is here too assumed to be more recent.
R(<date>)
true if the 'in place' entry is more recent than or of the same date as the
fixed <date> given in argument. No consideration is done toward the 'to be
added' element. The <date> format is the same as the one used with -af option.
If an entry has no mtime (it is not an inode for example) it is assumed an
virtual mtime of zero.
B true only if both 'in place' and 'to be added' are plain file (hard linked or
not) and if the 'in place' file's data is larger or equal to the 'to be added'
file's data. If one or both entry are not plain files (or hard link to plain
file) and thus the file size comparison is not possible, the 'in place' entry is
assumed to be 'bigger' than the 'to be added' entry.
S true only if the 'in place' data is saved in the archive (not marked as
unchanged nor marked as only inode metadata changed, since the archive of
reference). Note that while extracting files from an archive, the 'in place'
file is the one in the filesystem, which always has its data 'saved' (from
libdar point of view). The 'inversion' of this atomic operator ~S may still be
interesting in the context of restoration.
Y true only if the 'in place' data is saved but dirty (plain file having its data
changed at the time it was read for backup). Note, that restoring in sequential
read mode, it is not possible to known whether a file is dirty (it is possible
to know it once having read its data, but sequential reading does not allows
then to skip forward to get the dirty state of the file and skip backward to
eventually restore that file, depending on the overwriting policy result).
X true only if the 'in place' data is a sparse file
T true only if the 'in place' and 'to be added' entries are of same type (plain
file, Unix socket, named pipe, block device, char device, symlink, directory,
'detruit' (which stands for file deleted since the archive of reference was
done), and so on). Note that the number of links to inode (i.e. whether this is
a hard links or not) is not taken into account.
L true only if the 'in place' entry has delta signature associated with it.
E true only if 'in place' and 'to be added' are of the same type and have the same
inode data information: uid, gid, permission, modification date are taken into
account, atime and ctime are ignored in this comparison. If both are plain
files, the file sizes must be the same for this condition to succeed. For char
and block devices, both major and minor numbers must match. Last, for symlink,
the target (the file path they point to) must be the same.
e true if the 'in place' entry has EA (may they be saved or just recorded as
existing).
r true if the 'in place' entry has more recent or equal dated EA to the 'to be
added' entry. If 'to be added' has no EA or is even not an inode, true is
returned. If 'in place' has no EA or is even not an inode, true is returned
unless 'to be added' has some EA. The comparison is done on ctime dates.
r(<date>)
true if the 'in place' entry has more recent or equal dated EA to the fixed
<date> given in argument. No consideration is done toward the 'to be added'
element. The <date> format is the same as the one used with -af option. If an
entry has no date (ctime date) (when it is not an inode for example) it is
assumed an virtual ctime of value zero.
m true only if 'in place' has more or equal number of EA entry in its set of EA
than 'to be added' has. If an entry has not EA or is not even an inode, it is
assumed it has zero entry. The comparison is done on this number. Note that the
number of EA entry is not the size used to store these entries. For example, the
EA entry "user.test" counts for 1, whatever is the length of the value
associated to it.
b true if the 'in place' entry has bigger EA set or equal size EA set than the 'to
be added' entry. If an entry has no EA or is even not an inode, it is assumed
that it has a zero byte length EA set. The comparison is done on this number in
that case. Note that the comparison is done on the bytes used to store the whole
EA set associated to a given file.
s true if the 'in place' entry is an inode (or a hard linked inode) and has its EA
saved in the archive of reference, not only marked present but unchanged since
last backup. This test does not take the 'to be added' entry into account.
Well, you've seen that uppercase letter are kept when comparison is based on the
inode or data while lowercase letter is used for atomics based on EA. Now that we
have completed our tour of this feature let's see some examples:
-/ Pp
as seen previously this is what does -n option for files when no overwriting
policy is defined, which avoids any overwriting for Data as well as for EA.
-/ "{!T}[Pp] {R}[{r}[Pp]Po] {r}[Op] Oo"
Space and tabs are allowed to ease readability. Here the policy stands for: If
files in conflicts are not of the same type then keep Data and EA of the entry
'in place'. Else if 'in place' has a more recent data then if 'in place' has
more recent EA then keep both its Data and EA, else keep only its Data and
overwrite its EA. Else (if 'in place' has not the more recent data), if it has
the more recent EA then overwrite the data but keep its EA, else overwrite both
its data and EA. This policy tends to preserve the most recent data or EA, but
it does not take into account the fact that EA or Data is effectively saved into
the archive of just marked as unchanged since the archive of reference.
-/ "{!T}[{~D}[Oo] Pp]"
If entries are not of the same type, if the 'to be added' entry is a directory
then we keep it and overwrite the 'in place' entry, else we keep the 'in place'
entry. If entry are of same type, the policy does not provide any action, thus
the default action is used: "Pp". You can change this default action easily
using a chain operator:
-/ "{!T}[{~D}[Oo] Pp] ; Aa"
In this case instead, if entry are of the same type, the user will be asked what
to.
-/ "{!T|!I}[{R}[Pp] Oo] {I&~I}[{S}[{~S}[{R}[P*] O*] P*] {~S}[O*] {R}[P*] O* ;
{s}[{~s}[{r}[*p] *o] *p] {~s}[*o] ] {r}[*p] *o"
Well this may seems a bit too complex but just see it as an illustration of what
is possible to do: If both 'in place' and 'to be added' are not of the same type
we keep data and EA of the most recent file (last modification date). Else, both
are of the same type. If both are inode we evaluate a two expressions chain
(expressions are separated by a semicolon ';') we will see in detail further.
Else if they are of same type but are not inode we take the EA and data of the
most recent entry (this is the last 10 chars of the string). Well, now let's see
the case of inode: The first expression in the chain sets the action for data
and keep the action for EA undefined. While the seconds, is the exact equivalent
but instead it leaves the action for data undefined '*' and set the action for
EA. These two expressions follow the same principle: If both entries are saved
(by opposition to be marked as unchanged since the archive of reference) in the
archives, the most recent EA/Data is kept, else, the one of the inode that is
saved is kept, but if none is saved in the archive the most recent entry
(mtime/ctime) is kept.
-^, --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.
A file is considered as changed when the last modification time has changed between
the time the file has been opened for backup and the time it has been completely
read. In some situation it is not possible to replace the already saved data for a
file (writing archive to a pipe for example), in that situation only, a second copy
of the file is added just after the first previous try which leads that previous try
to becomes inaccessible, however it holds some place in the archive, where from the
designation of "wasted bytes". You can remove all wasted bytes from an archive using
the merging/filtering feature: dar -+ new_arch -A old_arch -ak.
Note: since release 2.5.0, in normal condition no byte is wasted when a file changed
at the time it was read for backup, except when doing a backup to pipe (using '-c -'
option), except if the beginning of the modified file is located in a previous slice
and except if slice hashing or strong encryption is used.
-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>:
%c is replaced by the command line used. Note that for security, any option related
to archive encryption is removed (-K, -J, -$, -#, -*, -%). The command included
from a DCF file (see -B option) are never added by this macro. As a consequence,
if you do not want to see --user-comment stored in user comments you can add the
--user-comment definition in an included file like ~/.darrc for example.
%d this is the current date and time
%u this is the uid under which dar has been run
%g this is the gid under which dar has been run
%h the hostname on which the archive has been created
%% the % character.
-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.
A summary information about the signature information is displayed while listing an
archive in summary mode "dar -l <archive> -q". For any operation involving a signed
archive, a short message only shows if the archive is signed an one or more signature
check failed, no message is displayed in case of successful signature check. This
warning may be disabled using the --alter=blind-to-signatures command.
-<, --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:
%% will be replaced by a literal %
%p will be replaced by the full path under backup
%f will be replaced by the filename (without the path)
%u will be replaced by the UID of the file
%g will be replaced by the GID of the file
%t will be replaced by a letter corresponding to the type of inode: 'f' for
plain file, 'l' for symlink, 'd' for directory, 'c' for char devices, 'b'
for block devices, 's' for sockets, 'p' for pipes, 'o' for doors.
%c and most interesting, %c (c for context), will be replaced by "start" or by
"end" when the command is executed before or after the backup respectively.
This way, one can dump a database in a directory just before it is about to be backed up, and clean it up
once the backup has completed. Note that the masks seen above that drive the execution of this command
can be applied to a directory or a plain file for example. When a directory is selected for this feature,
the command is logically ran before starting (with the context "start") to backup any file located in
that directory or in a subdirectory of it, and once all files in that directory or subdirectories have
been saved, the command is ran a second time (with the context "end"). During that time, if any file do
match the backup-hook masks, no command will be executed for these. It is assumed that when a directory
has been asked for a backup-hook to be executed this hook (or user command) is prepare for backup all
data located in that directory. The environment variable DAR_DUC_PATH also applies to these user commands
(see -E above, or the ENVIRONMENT paragraph below).
-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
Called during a backup operation it leads dar to create delta signature for each
file: If the file is new or has changed, a signature is computed and stored beside
the file's data, which increases the archive size. If the file is not new and has not
changed (differential backup context) if an delta signature is found in the archive
of reference (or isolated catalogue), this signature is copied to the resulting
archive, but not the file's data. If the reference archive does not hold delta
signature, a new delta signature is computed based on the current data found on
filesystem for that file and then stored in the resulting archive. But in any case,
without --delta sig the resulting archive will hold no delta signature. Note that
delta signature transfer is not possible when the archive of reference is read in
sequential mode (still here for backup operation), thus delta signature is disabled
when the archive of reference is read in sequential mode.
For isolation and merging operations, the behavior is slightly different: --delta sig
option let dar transfer existing delta signatures from the original archive to the
isolated/merged one but does not lead dar to compute delta signatures for files that
do not have one, unless one of the --include-delta-sig or --exclude-delta-sig option
is specified; in that case the delta signatures are transfered/dropped and if not
present calculated accordingly to these mask options. However note that it is not
possible to calculate delta signature for unsaved files in the archive of reference
(because the archive of reference does not hold their data) as well as for fully
saved files when merging is performed keeping files compressed (see -ak option).
Another restriction while merging concernes sparse files, it is not possible to
calculate binary signature for file stored as sparse files, but if sparse file
detection mechanism is activated at merging time, delta signature can be calculated
for sparse files too even if it is missing in the reference archive. In short: if you
want recalculation of delta signature while merging, do not keep file compressed (do
not use -ak option) and if you want to avoid having sparse files excluded from the
delta signature recalcutation, activate sparse file detection (use -ah option). Delta
signature transfer is not possible for on-fly isolation, you need to do normal
archive isolation to obtain an isolated catalogue with delta signatures.
-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:
fixed
always returns 1, in other terms, the block size is independent from the file
size to build delta signature for
linear
returns the filesize. here, you will most of the time use 1 for multiplier and
increase divisor to at least 10 for it makes sense
log2 returns the upper rounded power of 2 closest to the file size (base 2
logarithm).
square2
returns the approximated value of the square root of the file size. Note that
for better performance and as accuracy is not important here, this function is
implemented as exp2(log2(filesize)/2) where exp2 and log2 are based on the
integer left and right bit shift operations.
square3
returns the approximated value of the cube root of filesize, implemented as
exp2(log2(filesize)/3)
All numerical fields can receive multiplier suffix (k, M, ...) for more details about these
suffixes, see -s option description. If not specified, "max" defaults to zero (no maximum value
defined). If not specified "min" defaults to RS_DEFAULT_BLOCK_LEN (see below for details on this
symbol). If not specified "divisor" defaults to 1. Using "--delta sig" without additional fields
is equivalent to using --delta sig:fixed:RS_DEFAULT_BLOCK_LEN up to dar/libdar version 2.7.10.
Starting release 2.7.11, the default is equivalent to use --delta
sig:square2:1:1:RS_DEFAULT_BLOCK_LEN:128k , which is _almost_ what is used by rsync command line
tool (rsync use rather 700 bytes as minimum block size), where "RS_DEFAULT_BLOCK_LEN" is taken
from librsync and is today equal to 2048 bytes (which may well change in the future by the way if
librsync maintainers decide to do so).
-{, --include-delta-sig <mask>
By default when --delta sig is provided, delta signatures are computed for all files
enrolled in the backup operation (see also --delta-sig-min-size option). This option
and --exclude-delta-sig allow restricting the files for which delta signature have to
be calculated in that situation. The mask applies to the whole path, the same way as
-P/-g options do.
For merging or isolation operations, when --delta sig is used no delta signature is
computed only existing ones are transferred as is without restriction. To change that
behavior and thus either drop or add delta signature to files that did not have one
in the archive of reference, specify an combination of --include-delta-sig or
--exclude-delta-sig with --delta sig. This option as well as --exclude-delta-sig can
be used several times on command-line but are useless/ignored without --delta sig.
See also -am, -ag and -ar options.
-}, --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:
First it must be understood that binary delta has advantages (less storage requirement) and
drawbacks: data corruption has a wider impact on the ability to restore a given file, restoration
of incrementally backed up file may ask much more than one archive to be used. To limit the impact
of the first drawback, dar binary delta is done per file, not globally on the total amount of
saved data. You are also strongly encouraged to protect your backups with parity data using par2
(see dar_par.dcf file in the examples section of the documentation). Adding par2 data will
increase storage requirement by a little, but usually much less than the amount gained using
binary delta. Last drawback, binary delta relies on checksum (contained in the delta signature)
and not on the real data to build the binary delta. There is chances that two different files
provide the same checksum, even if the chances are very low, probability is not null. The
consequence is that using binary delta the risk exists that the restored data do not match the
original data and this will not be noticed by the librsync library on which libdar relies for that
feature. Dar adds a second level of checksum, to detect data corruption inside the archive and to
check that the file the delta patch is about to be applied is the expected base file, this reduces
the risk of "collision" but does not remove it completely. After these warnings, let's now see the
best practices about binary delta:
Once a full backup has been done using --delta sig, any differential backup made based on this
archive will use binary diff for file having a delta signature present in the full backup. If you
always make differential (not incremental) backups based on such full backup you have nothing more
specific to do in regard to binary delta, dar will handle it transparently. In particular you do
not need to invoke --delta sig at subsequent backup, this saves space in differential archives as
well as CPU cycles.
However, When doing incremental (not differential) backups this time, if you want to have dar
using binary delta at each subsequent incremental backup, delta signatures must be present in the
successive incremental backups. This is done by using --delta sig option for each new incremental
backup created.
If you were used to use isolated catalogues before release 2.6.0 you can add --delta sig option
while isolating a catalogue from an archive containing delta signatures. Such isolated catalogue
will be much larger than what it can be without this option but it can be used as reference for a
new differential/incremental backup letting dar relying on binary delta. Isolated catalogue
generated without --delta sig do not contain delta signature and cannot lead to binary delta
operation when used as reference for an incremental or decremental backup.
Another way of doing differential backup is to make a normal full backup without --delta sig
option, and only add delta signatures at archive isolation time using --delta sig --include-delta-
sig "*" options. Binary delta signature will then be calculated based on the saved files. Then,
using the resulting isolated catalogue as reference dar will be able to proceed to binary delta
for the differential backup. If this works pretty well for differential backup (or the first
incremental backup) which is based on a full backup, for incremental backup this is less adapted
as a file that has not changed since the archive of reference was made does not hold any data and
calculating the delta signature is not possible. The first method explained two paragraphs above
is better as the incremental backup fetches the already calculated delta signature from the
reference to keep it in the resulting incremental backup, so even without data, binary delta is
still possible.
Isolated catalogue using the --delta sig option, can still be used as backup of the internal
catalogue they have been isolated from. However, as they hold their own delta signatures, such
isolated catalogue can only have access to its own ones, not to those of the archive of reference.
In particular when testing an archive (-t option), using -A option to rescue the archive internal
catalogue using an isolated catalogue containing delta signatures, dar will not be able to check
that there is no corruption in the delta signatures fields of the archive under test. For that
type of testing either use the internal catalogue of the archive or rescue it using an isolated
catalogue built without --delta sig option.
-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, isolation and repair, -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/-y 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.
Without --kdf-param the KDF fonction uses 200,000 iterations for md5, sha1 and sha512 (PBKDF2 from
PKCS#5 v2) but only 10,000 for argon2. If libargon2 is present, this is the default hash
algorithm, else sha1 is used with PBKDF2. Valid parameters are "sha1", "sha512", "md5" and
"argon2" for the hash algorithms and a value greater than 1 for the iteration count. However it is
advise to use a value equal or greater to the default values mentionned previously. The suffixes
described for -s option are also available here (k, M, G, T, P, ...) however pay attention to the
-aSI/-abinary mode which default to binary, in which case "-T 1k" is equivalent to "-T 1024".
Example of use: --kdf-param 20k:argon2
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>
By default, listing provides a tar-like output (the 'normal' output). You can however
get a tree-like output, an XML structured output or an output focusing on slice(s)
where each file's data, EA and FSA is located in. The option --tree-format is an
alias to --list-format=tree (backward compatibility). Note that the files doc/dar-
catalog-*.dtd define the format of the XML output listing (This file is also
installed under $PREFIX/share/doc)
the -Tslicing option can also be used with isolated catalogue generated with dar
2.5.0 or above, as isolated catalogues now contain a copy of the slicing layout of
the archive of reference. However, if the archive of reference has been re-sliced
(using dar_xform) after the isolated catalogue has been built, the slicing
information would not be correct. For that corner case, you can use the -s and -S
options with -Tslicing to specify what are the new slice sizes of the archive of
reference. Last, -Tslicing and --sequential-read options are not compatible except
for isolated catalogues.
-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
[Data] possible values are [ ] or [Saved] or [InRef] or [DIRTY] or [Inode] or [Delta]. [
] means that the data has not been saved because there is no change since backup of
reference. [Saved] means that the data has been saved completely, and thus this
archive is able to restore the file without other help. [InRef] was used in archive
generated by dar version 2.3.x and before when isolating a catalogue from an archive,
and means that the file was saved in the reference archive. [DIRTY] means that data
is saved (like [Saved]) but has changed at the time dar was reading it for backup,
leading dar to possibly store the file in a state it never had. [Inode] means only
permission ownership and ctime data changed since the archive of reference was done
is recorded in the archive, the data did not changed according to the --comparison-
field set or not set. Last [Delta] means the file's data is saved as a binary delta
(or delta patch), which is much shorter than the full data as what is done with
[Saved]. It also means that you can only restore the file if it exists on filesystem
in the state it had when the archive of reference was done, for the patch to be
possible to apply on it. This is the case for example if you just restored this file
from the archive of reference.
[D] possible values are [-], [ ] or [D]. [D] means that delta signature associate with
this file is present in the archive. [ ] means that the file has no associated delta
signature and thus binary diff will not be possible for it. [-] is used for non plain
files inodes for which delta signature is not applicable.
[EA] possible values are " " (empty string) or [ ] or [InRef], [Saved] or [Suppr]. It
Shows whether Extended Attributes are present and saved ([Saved]), are present but
not saved ([ ]) which means there is no change since backup of reference, if
there is no EA saved for this file (empty string) or if some EA were present in the
archive of reference but none is currently available ([Suppr]). [InRef] was used when
isolating a catalogue (release 2.3.x and before) from an archive and means that the
file was saved in the reference archive.
[FSA] Each character represent a FSA Family:
"L" is the first character (L/l/-) representing ext2/3/4 FSA family
"H" is the second character (H/h/-) representing HFS+ FSA family
"-" the third character is reserved for future FSA family and is always a dash for
now.
Uppercase means the FSA set is saved, lowercase means the FSA is present in the
archive of reference and has not changed since that time. Last a dash (-) means no
FSA of that family has been saved for that file.
[compr] possible values are [....%] or [-----] or [ ] or [worse]. Shows if the file has
been compressed ([...%]) and the compression ratio reached "(uncompressed-
compressed)/uncompressed", for example [ 33%] means that the compressed data uses
only 66% of the space required to store uncompressed data (33% of space saved thanks
to compression), or if the file is stored without compression ([ ] see -m, -Y and
-Z options) or if the file is not subject to compression because it is not a saved
regular file ([----]), or if the file takes more space compressed than its original
size ([worse]), due to compression overhead. Note that 1% compression ratio brings
quite no data reduction, while obviously 98% is a very performant compression
(compressed file takes only 2% of the size required by the uncompressed date).
[S] possible values are [ ] or [X]. [X] only applies to saved plain files, and tells that
the file is stored using sparse file data structure: not all data is stored, long
sequence of zeros are skipped. This also means that at restoration time, if the
filesystem supports it, holes will be restored. To store hole information libdar uses
escape sequence (special sequence of byte), but to avoid real data to be considered
as such escape sequence, a special escape sequence is used when data looks like an
escape sequence. So if a data contains a such escape sequence, it must be read as if
it contains holes to be able to restore back the data in its original form. For that
reason, in some rare circumstances (saving an dar archive inside a dar archive
without compression or encryption, for example) a file without hole may be marked [X]
as if it had holes and will be longer by on byte for each data sequence looking like
an escape sequence.
permission
see ls man page. Note that a star (*) is prepended to the permission string if the
corresponding inode is linked several times to the directory structure (hard link).
user owner of the file
group group owner of the file
size size in byte of the file (if compression is enabled, the real size in the archive is
"compression rate" time smaller).
date the last modification date of the file. The last access time is also saved and
restored, but not displayed.
filename The name of the file.
Extended Attributes
When using -alist-ea option, for hard linked inode, the filename is followed by an
integer between braces: Entries with the same number do point the the same inode.
Slice(s) In -Tslice mode, each file is given the range of slices it is located in. If slice
size is chosen particularly small, some slices may contain no file, EA, FSA data but
only tape marks or the internal catalogue, leading the aggregation of reported slices
not to cover all available slices of the archive.
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
create:
# upon creation exclude the
# following files from compression
-Z "*.mp3" -Z "*.mpg"
all:
-b
-p
default:
# this will get read if not
# command has been set yet
-V
# thus by default dar shows its version
all:
-v
# for any command we also ask to be verbose
# this is added to the previous all: condition
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:
# normal set of files considered for backup
create:
-R /
-P proc
-P sys
-P mnt
-D
# if the "home" user target is applied on command line the following command get added
home:
-g home
# if the "verbose" user target is used, we will have some more verbosity ...
verbose:
-v
-vs
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:
# cat first.dcf
target3:
-K toto
target1:
target2
-B second.dcf
target3
target2:
#never reached
-s 10k
# cat second.dcf
target2:
-v
target3:
-b
In that example, target1 activates both target2 and target3, but at the time of the parsing of first.dcf,
neither target2 nor target3 were yet activated thus '-K toto' and '-s 10k' will never be given to dar
(unless activated beside target1 before first.dcf get parsed), however when comes the time to parse
second.dcf, target2 *and* target3 are activated, thus both '-v' and '-b' will be passed to dar, even if
'target3' is located after '-B second.dcf' in the file first.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:
export GNUPGHOME=~myaccount/.gnupg
dar -K gnupg:...@...,...@... --sign:...@... etc.
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
3rd Berkeley Distribution December 8th, 2024 DAR(1)