DAR(1) General Commands Manual DAR(1)
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
DESCRIPTIONdar 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
USAGE MADE OF STDIN/STDOUT/STDERR BY DAR
What message type you get on stdout or stderr, how input are
fetched from the terminal
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 OPTIONSCOMMANDS:
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 repositorysyntax 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 transfers (for that you need
to use the --alter=file-authentication option described below),
or for SFTP transfers you can rely on public key authentication
(you also have to use --alter=file-authentication in that case
to avoid a password being asked interactively).
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 and -qcrypto (see
below), 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)
-qcrypto, --quiet=crypto
Disable the warning that shows when reading a
ciphered backup about the impossibility to detect a
wrong key
-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.
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. This feature is
available for archive creation (-c option) and
archive restoration from a dar_manager database (see
-aefd option). In any case it must be placed before
-A option to have an effect.
For archive creation, 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>.
For archive restoration from a dar_manager database,
the given date defines the latest state into which to
restore the data and EA. Without this option, the
most recent availabe state is restored.
the <date> is passed to -A option (which must follow
-af option) and is expected to be a date in the two
following possible formats:
- a number of second since Jan 1st, 1970
- a date with the following structure
[[[year/]month/]day-]hour:minute[:second]
Here are some examples of date:
"-af -A 91836383927108078""-af -A 2005/11/19-19:38:48" Which is 38 past
7 PM and 48 seconds, the 19th of November 2005
"-af -A 20:20" Which is 20 minutes past 8 PM
of the current day
"-af -A 2-00:08" Which is 8 minutes past noon,
the second day of the current month
"-af -A 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). See also -ap 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>[:<eols>]
Files listed in the listing file are included for the
operation. No wildcard expression is interpreted in
the listing file. <eols> is expected to be a comma
separated list of End Of Line Sequences. If no <eols>
is specified, lines in the listing file must be
separated by either '\n' or '\r\n' sequence of
character, which is equivalent to provide
<listing_file>:'\n','\r\n'. You can provide as many
sequences as you want, but the longuest match will
always be preferred if two sequences share the same
beginning. If your filename contains a colon (:) you
must add an eols or the default one
(<filename_with_colon>:'\n','\r\n'). If your eols
must contain a comma (,) or a backslash (\) you
should escape them with a backslash: '\,' and '\\'.
Quotes around eols may be necessary to avoid the
shell interfering with them. Since release 2.8.0 the
limit on the line size has been removed, you can use
arbitrary long line if you need to. Note that this
option applies to any files and directories 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 paths as well, but only for
operations that have an 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 files you want to backup. You can thus
generate a listing file with the 'find / -print >
somefile' command and give the 'somefile' generated
file 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>[:eols]
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 selectionin 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
corresponds 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
'aes:'). 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 or keyid (keyid since
2.7.0) is given in a comma separated list. This
random key has the maximum length the cipher
algorithms supports, this to maximize security. Once
encrypted it is placed at the beginning (unless -at
option is used) and at the end of the generated
archive. At reading time, only the listed user(s)
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 key-ring 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
key-ring. Example: using "--key
gnupg::bob@nowhere.org,joe@somewhere.com" will
generate an aes256 encrypted archive which passphrase
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 aes256 one could use
"--key gnupg:bf:bob@nowhere.org,joe@somewhere.com".
More generally with GPG, note that users have the
duty to validate/certify that a given key-pair is
really owned by the physical person you expect it to
have: this must be done checking key fingerprint by
secure mean (face to face, phone call if you trust
this mean enough not to be intercepted and deep
faked, other already trusted communication mean...).
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 (SFTP or FTP) repository when no password
is provided, instead of interactively asking for a
password dar will check the ˜/.netrc file for
credentials when relying on FTP protocol. If instead
SFTP protocol is used, this option leads dar to first
try to connect using public key authentication
instead of password authentication. If the key could
not be loaded, a passphrase for that key will be
asked 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.
P true only if the 'in place' entry is a binary
patch.
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", "sha512" and
"whirlpool". By default no hash file is generated.
The hash file generated is named based on the name of
the slice with the .md5, .sha1, .sha512 or .whirlpool
extension added to it at the end. These hash files
can be processes by md5sum, sha1sum, sha512sum and
rhash (for whirlpool algorithm) 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 just
before proceeding to the backup of that file and a
second time right after it has 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. This
option can be used several times on command-line.
-> --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
options (but for a different purpose), 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. This option can be
used several times on command-line.
-=, --backup-hook-execute <string>
for files covered by the mask provided thanks to the
-< and -> options, the given string is executed just
before the backup of that file starts and right after
it has completed. Pay attention: when the action
applies to a directory, it does not apply to any file
and subdirectory located inside this directory.
Several macros 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.
For example, this feature let one dump a database
just before its backup starts, and remove the dumped
file(s) once the backup of that part has completed.
Note: when a directory is selected for this feature,
the user command is run before starting to backup any
file located in that directory and subdirectories,
with the context "start" (see %c above). It is also
run, as expected, after all files in that directory
and subdirectories have been saved, with this time
the context "end". But, between these two executions,
even if a file do match the backup-hook masks (thus,
this file is located inside this directory), no
command will be executed for it! It is assumed that
when a directory has been asked for a backup-hook to
be executed, this hook (or user command) is preparing
all data located in that directory.
For performance reasons due to the creation of a
shell process to intepret the user command-line and
subsequently the execution of the user command itself
(and this once before and once after a file to
backup), it not advise to use this feature for a
large number of files under backup (or worth, all of
them). The purpose of this feature is to prepare the
backup of some particular structures that need
coherence between files in order to be saved
properly. If all data under backup is concerned by
such coherent structure, better act before and after
running the dar command itself (for example
stopping/suspending and restarting/resuming the
concerned service/process). If many of such
structures are under backup or are nested in each
others, saving them independently (eventually using
this backup-hook feature for some or all of them) and
merging the resulting dar backups afterward or
feeding a dar_manager database with them, are also
options to consider.
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).
root2
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.
root3
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 --deltasig:root2:1:1:RS_DEFAULT_BLOCK_LEN:64*DEFAULT_BLOCK_LEN , 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
-anru, --alter=never-resave-uncompressed
At creation time or when re-compressing data at
merging time (thus when option -ak is not used), by
default dar tries to re-save file uncompressed if the
compression result takes more space than the
uncompressed original data. This has the drawback to
lead dar to skip back the archive about to be
created, the advantage is to not waste storage space.
This option let you disable this feature: dar will
then not skip back and will keep files compressed
even if their compressed data takes more space as
what they would take uncompressed.
-arep, --alter=repair
For isolation operation only, this option make dar
able to isolate a catalog from a truncated backup.
This option transparently implies --sequential-read
and --alter=force-first-slice to be able to read the
content of the truncated archive. The isolated
catalog can then be used to read the archive in
direct mode for better efficienty (see -A option used
with -x/-l/-t commands) which avoids repairing which
saves time (and non-rewritable media) if the volume
of data is huge.
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 ExtendedAttributes (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).
-affs, --alter=force-first-slice
This option first purpose was at restoration time
when using an isolated catalogue. In that context dar
still needs to read the archive format from the
backup to restore. In sequential read mode, this
information is always fetched from the beginning of
the archive, but in direct access mode it may be
fetched reading the end of the last slice (default
behavior) or reading at the beginning of the first
slice (when -affs is set). The objective is to avoid
fetching the last slice when using very large
backups. One can define a first slice (see -S option)
of for example 1 kB while other slices (-s option)
can be specified arbitrarily large. With the help of
an isolated catalogue based on this archive and the
first (small) slice, reading some data from this
large backup then only needs the few (big) slices
where the data is located, not more.
-aefd, --alter=extract-from-database
In this mode of data restoration, the argument given
to -x option should point to a dar_manager database.
This is almost equivalent to use dar_manager's -r
option at the difference that there is only one
process and all dar options given on command line are
available to each backup/archive referred in the
database that will be used for this restoration.
Dar_manager was designed to restore few files then
has been extended to a directory tree, but passing
the fileset scope to restore between process is not
that efficient. With -aefd option better performance
is provided to restore the whole dataset referred
from a set of full, incremental and/or differential
backups referred in a dar_manager database. See also
"-af -A <date>" option to limit the restoration to
the status data had before a given date.
with -aefd restoration mode, it is possible to
restore in the state at a given date by mean of -af
and -A options. By default, the most recent state
available is restored for all entries. File filtering
mechanism can also be used to restore only certain
files and directories, instead of all that were
present at the latest or given date state.
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.
-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.
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.
-affs, --alter=force-first-slice
this option also applies to testing and difference
operations (see details above).
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.
-afdd, --alter=fully-detailed-dates
show the sub-second fraction value of dates,
according to the time precision that was available in
the system where the backup was created.
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.
USAGE MADE OF STDIN/STDOUT/STDERR BY DAR
Dar as any Unix command-line tool is created by a shell with a standard
input (stdin), a standard output (stdout) and a standard error (stderr)
to interact with the user.
On the other side, Dar has a non-interactive output and a interactive
output. The objective is to have in-band messages that show the current
process steps (normal messages that goes to the non-interactive output)
and out-of-band messages that can influence the global process or give
diagnostic on the dar current operation fate (the interactive output and
its associated input).
At startup
in the very early phase, before dar has interpreted the
argc/argv arguments it has received from the shell (those
options and commands you pass to dar), both outputs are bounded
to stderr, because dar may be set to read an archive on stdin
(--sequential-read option or dar used with dar_slave) or to
output an archive on stdout ("-c -" option for example). A very
basic lookup in performed on the argv arguments list toward the
presence of a -Q option. Right after that, if no controlling
terminal is found (and unless -Q option has been found earlier)
a warning message is send to the non-interactive output (stderr
at that time) and all questions will assume negative answer.
Else, a new file-descriptor is open on this controlling
terminal and will be used to fetch the future answers from the
user when interaction will be needed, preserving stdin this
way.
During command-line parsing
Once the command line option parsing has completed, if no
archive or backup is expected to be output on stdout (no -i and
-o options, as well as no "-c -" "-C -" or "-+ -"
configuration requested, for example), the non-interactive-
output is changed from stderr to stdout, else it stays on
stderr.
Running phase
Thus, during the archive or backup processing, any information
message goes to the non-interactive output (either stderr or
stdout as described above) while questions to the user to the
interactive output, that's to say on stderr. If a controlling
terminal has been found the user answer is fetch from this
terminal through the additional file-descriptor opened at
startup phase (stdin is kept either for dar_slave or
sequential-read mode or is not used at all).
Exception phase
In case an exception (= an error) that could not be handled by
dar succeeds, both outputs are set back to stderr and the error
message embedded in the exception is displayed before dar
terminates.
EXIT CODESdar 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_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.
DAR_SECURED_MEMORY_SIZE_BYTES
let the user specify the amount of secured dar/libdar should
allocate. The provided value must be integer number defining
the secured memory size in byte. By default 262144 bytes are
allocated.
CAPABILITIESdar 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.htmlSEE ALSOdar_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.htmlKNOWN 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.htmlKNOWN BUGShttps://github.com/Edrusb/DAR/issuesAUTHORhttp://dar.linux.free.fr/
Denis Corbin
France
Europe
3rd Berkeley Distribution May 1st, 2026 DAR(1)