Provided by: dar_2.7.15-2_amd64 
NAME
dar - creates, tests, lists, extracts, compares, merges, isolates, repairs dar archives
SYNOPSIS
dar [-c | -t | -l | -x | -d | -+ | -C | -y] [[<URL>]<path>/]<basename> [<options>] [<user
targets>]
dar -h
dar -V
DESCRIPTION
dar is a full featured backup tool, aimed for local and remote disks (floppy, CD-R(W),
DVD-R(W), zip, jazz, hard-disks, usb keys, etc.) cloud storage (by mean of ftp or sftp
protocols) and also adapted to tapes.
dar can store a backup in several files (called "slices" in the following) of a given
size, eventually pausing or running a user command/script before starting the next slice.
This can allow for example, the burning of the last generated slice on a DVD-R(W), Blue-
ray Disk, or changing of usb key before continuing on the next one. Like its grand-
brother, the great "tar" command, dar may also use compression, at the difference that
compression is used inside the archive to be able to have compressed slices of the defined
size.
But the most important feature of dar is its ability to make differential, incremental and
decremental backups. In other words, backups that contain only new files or files that
have changed from a backup of reference. Binary delta is available but not activated by
default: in combination with differential and incremental backups, it leads not only to
not save a file that has not changed (thing dar does without binary delta), but also to
only save an rsync patch of any modified file, which lead to even smaller backups.
Moreover with differential backup, dar also stores files that have been deleted since the
backup of reference. Thus, when restoring, first a full backup, then additional
differential backups, at each restoration you get the exact state of the filesystem at the
time the differential backup was made. dar is the first backup program I know that can
also remove files during restoration! By the way, in this document, "archive" and "backup"
are used interchangeably, the difference is the purpose you build them for.
Unlike the tar command, dar has not to read a whole archive nor to stick together the
different parts (the slices) to access its contents: dar archives contain a table of
contents (aka "catalogue") located at the end, so dar can seek into the archive to read
only the required data to restore files, thing which is much faster than what tar is used
to do. The "catalogue" can be copied out of the archive (operation called isolation) to be
used as reference for further backup and as backup of the internal catalogue in case of
archive corruption.
Dar can also use a sequential reading mode, in which dar acts like tar, just reading byte
by byte the whole archive to know its contents and eventually extracting file at each
step. In other words, the archive contents is located at both locations, a first time all
along the archive used for tar-like behavior suitable for sequential access media (tapes)
and a second time at the end for faster access, suitable for random access media (disks).
However note that tar archive and dar archive are not compatible. Note also that the
sequential reading mode let you extract data from a partially written archive (those that
failed to complete due to a lack of disk space for example) and since release 2.6.0 such
truncated archive can be repaired to become a normal archive (the "catalogue" is rebuilt
from inlined information).
Dar is able to save and restore to a cloud storage by mean of ftp or sftp network
protocols. It can also leverage ssh protocol using dar_slave and dar_xform two auxiliary
programs provided beside dar.
Dar format is quite robust against corruption: Only the file where the corruption took
place in the archive will not be possible to restore. To have the possibility to repair a
corrupted archive dar can work with par2 seamlessly just specifying "par2" on command-line
(see /etc/darrc). Last a "relax" reading mode is available which let dar to either ignore
some incoherence in archive structure, use internal redundant information to overcome data
corruption or in last resort asking the user on what to do when some archive structure
information is missing (-al option). This relax mode can be used with both sequential and
direct access read modes. Note that you should rather use Parchive to protect your data
rather than just relying on the "relax" mode, which has to be seen as a the last chance
solution.
dar takes care of POSIX Extended Attributes (EA in short) that are used in particular
under Linux to carry File Access Control List (FACL) as well as security attributes for
SELinux, and also under MacOS X EA they are used to store file forks. EA also have room
for user to add any key / value pair to any file, this is known as user EA. These
attributes are not specific to any particular filesystem, they exist the same way under
ext3/4, HFS+ and any other filesystem.
dar also takes care of Filesystem Specific Attributes (FSA in short) which are, as you can
guess, specific to one or several filesystem(s). For example the Birth date of a file
exists for HFS+ and NTFS but not for ext2/3/4 filesystem. The immutable attribute exists
for ext2/3/4 but not for NTFS while the nodump files does not exists for NTFS but exists
for HFS+, ext2/3/4 and many other Unix filesystems.
Sparse files (files with holes that system reports using several hundred gigabytes while
they effectively use a few kilobytes on disk) are also well managed by dar: they are
detected, stored and restored to filesystem properly.
Last, dar is also able to properly save and restore hard-links
WARNING
This document is to be considered as a full reference of dar/libdar features. It is
however not adapted to discover dar, for that purpose some tutorials are provided in dar
documentation. Once you have apprehended the basic dar usages you are welcome to read
further this document to see all other features you may find useful for your needs.
DOCUMENT STRUCTURE
The rest of this document is organized that way:
COMMANDS
The eight actions you can performs with dar
GENERAL OPTIONS
A set of options common to all actions
SAVING, ISOLATING, MERGING AND REPAIRING SPECIFIC OPTIONS
A set of options that are specific to the operation of backup, catalogue
isolation and archive merging
RESTORATION SPECIFIC OPTIONS
A set of options that are specific to the restoration operation
TESTING AND DIFFERENCE SPECIFIC OPTIONS
A set of options that are specific to the operation of archive testing and
archive comparison with a filesystem
LISTING OPTIONS
A set of options that are specific to archive listing operation
EXPLICIT OPTIONAL ARGUMENTS
Some system do not allow optional arguments to options, this chapter explain
how to overcome this restriction
EXIT CODES
List of values dar returns at end of execution. This chapter should be read if
you intend to create scripts relying on dar
SIGNALS
details the signal and their action on a running dar process
FILES
List configuration files that dar checks for
CONDITIONAL SYNTAX
Over command line, command and options can be passed to dar thanks to a plain
file (known as DCF file). This plain file can also contain a specific syntax
that will let you pass an option to dar only under certain
situation/condition. This chapter describes this simple syntax and the
different available conditions.
USER TARGETS
User can add their own conditions known as user targets. This chapter
describes what they are and how to use them
ENVIRONMENT
Dar may rely on environment variables to look for DCF files and DUC files,
SFTP private and public key and so on.
COMMANDS AND OPTIONS
COMMANDS:
Only eight commands define what action will be done by dar: Archive creation, archive
extraction, archive listing, archive testing, archive comparison with filesystem,
catalogue isolation, archive merging and archive repairing. These commands are described
here below.
Once defined, a large set of options can be used to modify the way the command is
performed. These options are described just after the commands chapter.
Important note: Not all systems actually support long options (Solaris, FreeBSD, ...). For
example --create will not be available on these systems, and you will have to use -c
instead. In the same way, not all systems do support optional arguments (FreeBSD without
GNU getopt for example), you then need to explicitly give the argument, for example in
place of "-z" you will need to give "-z 9", see "EXPLICIT OPTIONAL ARGUMENTS" paragraph
near the end of this document for details on that point.
A slice is just a simple file which name is composed of a "basename" followed by a dot,
then a number, again a dot and the extension (dar) to form the filename of that slice. On
the command line you will never have to give the full file name of a slice, just the
basename. The number between the dots is the slice number, which starts from 1 and may be
arbitrary large (as large as your system can support the corresponding filename). For
example "my_first_archive.42.dar" is the 42th slice of the archive which basename is
"my_first_archive".
-c, --create [[<URL>]<path>/]<basename>
creates a backup with the name based on <basename>. All the slices
will be created in the directory <path> if specified, details about
the <URL> syntax is explained below at Remote repository syntax
paragraph. Without <path> nor <URL> the current directory is used. If
the destination filesystem is too small to contain all the slices of
the backup, the -p option (pausing before starting new slices) might
be of interest. Else, in the case the filesystem is full, dar will
suspend the operation, asking for the user to make free space, then
continue its operation. To make free space, the only thing you cannot
do is to touch the slice being written. If the filename is "-" *and*
no slicing is asked for (no -s option) the archive is produced on the
standard output allowing the user to send the resulting archive
through a pipe (or into a tape device directly or using the dar_split
command).
-x, --extract [[<URL>]<path>/]<basename>
extracts files from the given backup. Slices are expected to be in the
current directory or in the directory given by <path> (see also Remote
repository syntax below). It is also possible to use symbolic links to
gather slices that are not in the same directory. Path may also point
to a removable device (floppy, CD, USB key, etc.), in this case, to be
able to mount/unmount the device, you must not launch dar from that
directory. In other words, the current directory must not on the
removable media you plan to unmount (see tutorial for details). The
basename may be set to "-", in direct access mode (the default
historical mode), you will then need dar_slave to work with dar (see
-i and -o options, as well as dar_slave man page). However in
sequential read mode (--sequential-read is used on command-line), dar
will read the archive from standard input (see also -i option), this
can eventually be used in combination with dar_split.
-l, --list [[<URL>]<path>/]<basename>
lists the contents of the given backup (see also Remote repository
syntax below) dar will only require the last slice of the archive in
direct access mode. If however sequential mode is used, dar will read
the overall archive, from the first slice to the last one. "-" can be
used as basename, the behavior is the same as with -x option (read
just above).
-t, --test [[<URL>]<path>/]<basename>
checks the backup integrity. Even without compression, dar is able to
detect at least one error per file in the archive, thanks to a
variable length CRC recorded per file data, file EA and file FSA in
the catalogue. Archive structure (slice header, archive header,
catalogue) is also protected by CRC to be able to detect any kind of
archive corruption. Same remark here, "-" may be used as basename (see
-x option above for details).
-d, --diff [[<URL>]<path>/]<basename>
compares saved files in the backup with those on the filesystem.
<basename> may also be "-" (see -x option above for details). Note
that the target for this operation is to be seen as a step further
than archive testing, where in addition to archive coherence, the
archive contents is verified to be the same as what is found on the
filesystem. But if new files are present on the filesystem, dar
ignores them. If you want to check for changes since a archive has
been made, better use dry-run differential backup.
-C, --isolate [[<URL>]<path>/]<basename>
isolate a catalogue from its archive (that's to say make a copy of the
internal catalogue to its own archive container). The argument is the
basename of the file to create which will contain the catalogue's
copy. The -A option is mandatory here to give the name of the archive
to copy the catalogue from, this archive is not modified at all.
Slicing is available (-s -S -p -b etc.). If the filename is "-" *and*
no slice is asked (no -s option) the isolated catalogue is produced on
the standard output, allowing the user to send the resulting archive
through a pipe. Note that there is quite no difference in concept
between an isolated catalogue and an archive. Thus you can do all
operations on an isolated catalogue, in particular take it in place of
the original backup as reference for a differential archive, archive
testing, archive comparison. Note however that for comparison (-d
option) as data is not present in the isolated catalogue, dar relies
on embedded CRC rather than comparing data byte by byte (what is done
with a plain archive), and no comparison can be performed concerning
EA or FSA even if each of them have their own CRC in the catalogue
because different ordering as provided by the OS of the items
composing EA and FSA may lead the CRC to be different while the EA or
FSA are exactly the same, so CRC here is used only to detect archive
corruption. Since release 2.4.0 you can use an isolated catalogue to
rescue a corrupted internal catalogue of the archive it has been based
on (see -A option).
-+, --merge [[<URL>]<path>/]<basename>
create a subset archive from one or two existing archives (the
resulting archive name is the argument to this command). The dar file
selection mechanism (see GENERAL OPTIONS) let the user decide which
files will be present in the resulting archive and which one will be
ignored. This option thus let the user merge two archives in a single
one (with a filtering mechanism that accepts all files), as well as
this option let the user create a smaller archive which data is taken
from one or two archives of reference. Note that at no time the
contents of the archives of reference is extracted to real files and
directories: this is an archive to archive transfer, thus you may lack
support for Extended Attribute while you will be able to fully
manipulate files with their Extended Attributes from one archive to
the resulting one. If the basename is "-" *and* no slice is asked (no
-s option), the archive is produced on standard output allowing the
user to send the resulting archive through a pipe. The first mandatory
archive of reference is provided thanks to the -A option, while the
second "auxiliary" (and optional) archive of reference is provided
thanks to the -@ option. When a tie contention occurs (same file names
from both archive have to be merged), the overwriting policy (-/
option) is used to define the one to keep in the resulting archive. By
default, archive data selected for merging is uncompressed, and re-
compressed. Thus the merging operation can be used to change
compression algorithm of given archive as well as change its
encryption. But, for better performance it is also possible thanks to
the -ak option (see below the -ak option for usage restrictions) to
merge files keeping them compressed, thus no decompression/re-
compression is performed at all, which make the operation faster. Last
it is not possible to merge two isolated catalogues.
-y, --add-missing-catalogue [[<URL>]<path>/]<basename>
create a "repaired" archive based on the archive given with -A option.
The repairing only concerns the case where an archive has been
interrupted and dar could not cleanly end the archive creation process
(lack of disk space, power outage, and so on). This operation consists
in reading the tape marks in sequential reading mode to gather the
content of the archive and once its end is reached, to recreate the
missing table of content (aka catalogue) located at the end of the
archive. Note that the damaged archive is not modified but a repaired
copy is built beside it. Why not just appending the catalogue to the
archive? Because first it was simpler to implement allowing to reuse
routines of the merging operation, second by precaution for dar to not
mess an existing archive due to a bug and last, it would not be
compatible with archive signing and gpg encryption under certain
conditions (several recipients or the archive is signed and you are
not the one who signed it).
During the repairing operation, the repaired archive may have a different slicing
(-s and -S options), a different encryption (-K and associated options, including
gpg encryption and signing), a different repository slices permissions and
ownership (--slice-mode option), user comment (--user-comment), generated hash
(--hash) and min digits in slice number (--min-digits), but compression cannot be
changed and tape marks cannot be removed (you can do it once reparation has
completed using the merging operation). Last, file filtering is not allowed during
archive repairing.
-h, --help displays help usage.
-V, --version displays version information.
Remote repository syntax for [<URL>]<path>
for all commands described above as well as some options detailed below (-A and -@
options), the <path> optional argument can be a Unix path like /var/tmp when the
archive is located on the host dar runs on. But it can also make use of <URL> to
define the remote host the archive is to be read or written to. "<URL><path>"
follows the usual syntax:
proto://[login[:password]@]hostname[:port]/path
proto
is either ftp or sftp
login
is optional, if not provided it defaults to anonymous. If the login string
comports an @ it need to be escaped by \\ (a pair of backshashes) to avoid
libdar considering it the hostname starting part. Example: login is me@here.com
host is www.example.org gives: sftp://me\\@here.com@www.example.org/some/file.
You may also need to escape the same way any other special characters like for
example colon (:) slash (/) if they are part of the login string.
password
if login is provided, the associated password may be given after a colon (:) but
this exposes the secret password to other users of the current system having
access the table of process (using top, ps, /proc or other ways). If the login
is given without password, the password will be asked interactively by dar at
run time, which is much more secure. Alternatives are either to rely on ~/.netrc
for FTP and also SFTP (!) transfers for that you need to use the --alter=file-
authentication option (see below), or for SFTP only on public key authentication
(you can also use --alter=file-authentication in that case to avoid a password
being asked interactively). Note that passphrase support for sftp key is not
(yet) supported.
hostname
is the name or IP address of the host to connect to. For sftp the server's
public key is checked against the ~/.ssh/known_hosts file (or the file pointed
to by then environment variable DAR_SFTP_KNOWNHOST_FILE, see more details about
that variable at the bottom of this man page), the host must be known and the
public key received from the network must match the one in that file, else dar
aborts. If thus you want to operate with a new sftp server, first use ssh of
sftp commands to do the usual fingerprint verifications which updates the
known_hosts file accordingly, then run dar/libdar toward this sftp server.
port
if not provided, dar will use the default/standard port in regard to the
protocol specified in the "proto" field
path
a unix path where resides the archive to read from the remote repository or
where to write the archive to in that remote repository. The given path is
absolute, in regard to the remote root filesystem available for the given
account though the requested protocol. See also --network-retry-delay option
below.
GENERAL OPTIONS:
-v, --verbose For backward compatibility, this is an alias to "-vt -vm" (both
options set).
-vs, --verbose=skipped
Display files skipped because of file filtering exclusion specified by
the user
-vt, --verbose=treated
Display treated files because of file filtering inclusion specified by
the user or no file filtering specified at all. For each file a
message is displayed *before* the file is treated. This option is not
available for archive isolation and is useless for archive listing as
it is always set, unless -q is used.
-vd, --verbose=dir Display the directory under process. The messages shows *before*
entering a directory. You can have a less verbose output than -vt
while are still able to follow what's dar is doing. Note that -vt and
-vd are mutually exclusive.
-vm, --verbose=messages
Display detailed messages about what dar is currently performing but
not related to currently treated or skipped files and directories
-vf, --verbose=finished
Issues a summary *after* each treated directory containing the amount
of data backed up in that directory as well as the average compression
ratio. This option is only available for archive creation.
-va, --verbose=all is equivalent to -vm -vs -vt, see also -Q and -q options below. Note:
When using dar from a script better use dar's exit status to know
which way the operation has ended (seen EXIT CODES at the end of this
document).
-vmasks, --verbose=masks
Display raw information about the masks set by dar and passed to
libdar
-avc, --alter=verbose-libcurl
activate verbose output from libcurl (remote repositories context).
This is to be considered as a debug option relative to remote
connection problems.
-q, --quiet Suppress the final statistics report. If no verbose output is asked
beside this option, nothing is displayed if the operation succeeds.
When using dar from a script better use dar's exit status to know
which way the operation has ended (seen EXIT CODES at the end of this
document)
-b, --beep makes the terminal ring when user action is required (like for example
the creation of a new slice using the -p option)
-B, --batch <filename>
In the file which name is given in argument to this option, You can
put any option or argument as used on command line, that will be
parsed as if they were in place of the "-B <filename>" option. This
way you can overcome the command line size limitation. Commands in the
file may be disposed on several lines, and -B option can also be used
inside files, leading a file to include other files. But an error
occurs in case of loop (a file that includes itself directly or not)
and DAR aborts immediately. Comments are allowed, and must start by a
hash `#' character on each line. Note that for a line to be considered
as a comment the hash character must be the first character of the
line (space or tab can still precede the hash). See Conditional Syntax
below for a richer syntax in this type of configuration files known as
DCF file (Dar Configuration File). See also the environment variable
DAR_DCF_PATH in the ENVIRONMENT section at the end of this document.
Note that you can use quotes simple (´arg´) double ("arg") and back-
quotes (`arg`) inside such file, but they need to be balanced (have an
ending one). To use such character without the meaning of a quote, for
example as an apostrophe, you need to escape it using a back-slack
("That\'s an example"). Of course to add a single back-slash as a
normal character in the file you will have to double it ("c:\\windows"
for example)
-N, --noconf Do not try to read neither ~/.darrc nor /etc/darrc configuration
files. See files section below.
-Q Do not display an initial warning on stderr when not launched from a
terminal (when launched from a cronjob for example). This means that
all questions to the user will be answered by 'no', which most of the
time will abort the program. Please note that this option cannot be
used in a configuration file (-B option). Since version 2.2.2, giving
this option also forces the non-interactive mode, even if dar is
launched from a terminal. This makes it possible for dar to run in the
background. When you do, it's recommended to also redirect stdout
and/or stderr to files: dar -Q ... &> /dev/null &
-n, --no-overwrite do not allow overwriting
If an overwriting policy is specified (see -/ option) -n option do
only apply to slices overwriting, the overwriting of files during
restoration or merging is handled by the overwriting policy. Without
overwriting policy, -n applies to restored files as well as generated
slices.
-w, --no-warn Do not warn before overwriting (applied for slice overwriting and for
overwriting decision make by the overwriting policy). By default
overwriting is allowed but a warning is issued before proceeding. This
option may receive 'a' as argument (see just below):
-wa, --no-warn=all This implies the -w option, and means that over avoiding warning for
file overwriting, DAR also avoids signaling a file about to be removed
when its type is not the expected one. File are removed when they have
been recorded as deleted since the archive of reference. At
restoration of the differential archive, if a file of the given name
exists, it is remove, but if the type does not match the file that was
present at the time of the archive of reference (directory, plain
file, fifo, socket, char or block device, etc.), a warning is normally
issued to prevent the accidental removal of data that was not saved in
the backup of reference. (See also -k option)
-A, --ref [[<URL>]<path>]/<basename>
Depending on the context, it specifies the archive to use as
reference, which is mandatory for archive isolation (-C option) and
merging operation (-+ option). Else it specifies the rescue catalogue
to use when restoring (-x command), testing (-t command) or comparing
(-d command) an archive. All slices of the reference backup are
expected to be on the same directory given by <path> or the current
directory by default. Usually only the last slice is required to
extract the catalogue of reference. If necessary the use of symbolic
links is also possible here to gather slices that do not reside in the
same directory. You can also point <path> to a USB key, DVD-R(W) or
any other mounted directory, because dar will pause and ask the user
for required slices if they are not present. The argument to -A may be
of four types:
- An existing archive basename, which will be taken as
reference
- a dash ("-") in direct access mode (default mode, when
--sequential-read is not used) it may imply the use of -o and
-i options, this allows the archive of reference to be read
from a pair of pipes with dar_slave at the other ends.
Dar_slave can be run through ssh on a remote host for example.
Note that this type of argument ("-") is only available when -A
is used for isolation (-C option) and merging (-+ options). In
sequential mode (--sequential-read is used), the archive of
reference is read from standard input or from the named pipe
specified by -i option. -o option has no use in sequential
mode. Note that merging operation (-+ option) cannot read
archive of reference in sequential mode.
- a plus sign ("+") which makes the reference be the current
directory status. This argument is only available for archive
creation (-c option). In other word, no file's data will be
saved, just the current status of the inodes will be recorded
in the catalogue. This feature is known as the "snapshot"
backup. A snapshot backup can be used as reference later on to
detect or save only the files that have changed since the
snapshot was made.
- a <date>, if -af option has been placed before -A on the
command-line or in a included file (see -B option). For more
about that feature see -af option below. This form is only
available for archive creation (-c option).
During backup operation (-c option) the archive of reference, given
thanks to the -A option, is used for comparison with existing files on
the filesystem. Dar will then backup only files that have changed
since the archive of reference was done. If no -A option is given, the
backup operation is a full backup. With -A option if the archive of
reference is a full backup some call it a differential backup, while
if the archive of reference is differential backup, some call this
type of backup an incremental backup. For dar there is no difference
in structure between incremental and differential backup, both are
usually designed globally as "differential" backup in the
documentation.
During merging operation (-+ option), the contents of the -A given
archive will been taken eventually with the contents of the -@
auxiliary archive if specified (see below), to form a new archive from
files of this or these archives. Note that you can filter out files
from the operation and setup subset of the original archive(s).
During Catalogue isolation (-C option), dar will create the isolated
catalogue from the one given with -A option.
During testing, diff or extraction, (-t, -d or -x options
respectively), the table of contents (the catalogue) will be read from
the archive given with -A instead of using the internal catalogue of
the archive. The archive given for rescue must has been previously
isolated from this same archive (else the contents will not match and
dar will refuse to proceed to this operation). This acts as a backup
solution to the case of corruption inside an archive's catalogue,
while the best way is still to use Parchive to protect your data
against media error.
-af, --alter=fixed-date
Modify the -A option behavior, making it receiving a <date> as
argument in place of the [<path>]/<basename> default argument. The
<date> is used to define which file to save: file which modification
is newer or equal to <date>, and which to consider unchanged: those
older than <date>. This option has only a meaning when creating an
archive (-c option) and must be placed before -A option to have an
effect.
<date> must be a date in the two following possible formats:
- a number of second since Jan 1st, 1970
- a date in the following form
[[[year/]month/]day-]hour:minute[:second]
Here are some examples of date:
91836383927108078
1 2005/11/19-19:38:48 Which is 38 past 7 PM and 48 seconds, the
19th of November 2005
20:20 Which is 8 PM of the current day
2-00:08 Which is 8 past noon, the second day of the current
month
2/2-14:59 Which is 1 to 3 PM, the 2nd of February in the
current year
Note that the provided date is relative to the system timezone which
is overridden if the TZ environment variable is set (see tzselect(1)
for more details)
-@, --aux [[<URL>]<path>]/<basename>, --on-fly-isolate [<path>]/<basename>
specifies an auxiliary archive of reference (merging context) or the
name of the on-fly isolated catalogue (creation context). This option
is thus only available with -+ option (merging) and -c option (archive
creation). Note that --aux and --on-fly-isolate are really aliases to
the same option, this is the context of use (archive creation or
merging) which lead it to behave a way or another.
In a merging context, over -A option which is mandatory, you may give
a second archive of reference thanks to the -@ option. This allows you
to merge two archives into a single one. See also -$ option
(encryption) -~ option (command execution) and -% (crypto block size)
for other options concerning auxiliary archive of reference. They are
the respective equivalent of -J, -F and -* options relative to archive
given thanks to -A option.
In a backup context -@ option let the user specify the archive name
for an on-fly isolation. With on-fly isolation, you can also use -$
option (to define encryption algorithm and passphrase), -~ option (to
execute a command once the on-fly isolated catalogue is completed) and
-% option (crypto block size). On-fly isolated catalogue is always
bzip2 if possible else gzip else lzo compressed (using compression
level 9) else not compressed, and it is also always a single sliced
archive. Due to command-line exiguity, it is not possible to change
compression algo nor slice size for the on-fly isolation. If you need
a more complicated isolation, either look for a GUI over libdar, or do
a normal (= not an on-fly) isolation operation (By the way it is
possible to isolate an already isolated catalogue, this is equivalent
to doing a copy, but you can change encryption, compression or
slicing, for example), you can also use dar_xform on an isolated
catalogue if you only want to change slices size (this is faster as no
decompression/re-compression nor encryption/decryption is necessary).
Using the merging operation on an isolated catalogue instead of
isolating the isolated catalogue, leads the resulting archive to not
be able to be used as a rescue for internal catalogue of the original
archive. --aux-ref is a synonym to --aux.
-R, --fs-root <path>
The path points to the directory tree containing all the files that
will be enrolled in the operation (backup, restoration or comparison).
By default the current directory is used. All other paths used in -P
or -g options on the command line are and must be relative to this
path (or to current directory if -R is not present). Note that -R is
useless for testing (-t option) isolation (-C option) and merging (-+
option)
-X, --exclude <mask>
The mask is a string with wildcards (like * and ? see glob(7) for
details) which is applied to filenames which are not directories. If a
given file matches the mask, it is excluded from the operation. By
default (no -X on the command line), no file is excluded from the
operation. -X may be present several times on the command line, in
that case a file will not be considered for the given operation if it
matches at least one -X mask. See also -ar and -am options.
-I, --include <mask>
The mask is applied to filenames which are not directories (see
glob(7) for details on wildcard characters). If a given file matches
the mask and does not match any mask given with -X, the file is
selected for the operation. By default (no -I and no -X on the command
line), all files are included for the operation. -I may be present
several times on the command line, in that case all files that match
one of the -I mask will be considered for the given operation, if they
do not also match one of the -X mask. See also -ar and -am options.
-P, --prune <path> Do not consider file or directory sub-tree given by the path. -P may
be present several time on the command line. The difference with -X is
that the mask is not applied only to the filename, but also includes
the path. Moreover it applies also to directories (-X does not). By
default (no -P on the command-line), no sub-tree or file is excluded
from the operation, and the whole directory tree (as indicated by -R
option) is considered. Note that <path> may contains wildcards like *
or ? see glob(7) or regex(7) man page for more information as well as
-ar option to use regex instread of glob expressions.
-g, --go-into <path>
Files or directory to only take in account, as opposed to -P. -g may
be used several time on command-line. Same thing here, the difference
with -I is that the mask is applied to the path+filename and also
concerns directories. By default all files under the -R directory are
considered. Else, if one or more -g option is given, just those are
selected (if they do not match any -P option). All paths given this
way must be relative to the -R directory, which defaults to current
directory. Warning, -g option cannot receive wildcards, these would
not be interpreted.
-[, --include-from-file <listing_file>
Files listed in the listing file are included for the operation. No
wildcard expression is interpreted in the listing file, the null
character is not allowed and the carriage return is used to separate
file names (one file name per line) each line must not exceed 20479
bytes. Note that this option applies to any files and directory
exactly as -g does, with an important difference however: -g option
only uses relative paths to the root directory (the directory given
with the -R option), while -[ can use absolute path as well but only
for operations that have a fs_root argument (archive creation,
comparison, extraction, and so on, but not for archive listing,
testing and merging). Another difference is when the argument is a
directory -g will include all the subdirectories under that directory,
while when the same entry is found in a listing file given to -[
option, only that directory will be included, no subdirectory or
subfile would be enrolled in the backup. With -[ you need to list the
exact set of file you want to backup. You can thus generate a listing
file with the 'find / -print > somefile' command and give 'somefile'
as argument to -[ option. Note that however, dar will never save files
out of the -R given root directory tree, even if some are listed in
the 'somefile' file.
-], --exclude-from-file <listing_file>
Files listed in the listing file are excluded from the operation. If a
directory is listed in the file, all its contents is excluded. This
option is the opposite of -[ and acts the same was as -P option does
(in particular it is compared to the whole path+filename and applies
to files and directories). As for -[ option, -] listing file can
contain absolute paths, but wildcards are not expanded, neither.
File selection in brief:
As seen above, -I -X -P, -g, -[ and -] options are used to select the files to operate on.
-I and -X only use the name of files and do not apply to directories, while -P, -g -[ and
-] use the filename *and* the path, they *do* apply to directories.
since version 2.2.0 two modes of interpretation of these options exist. The normal
original method and the ordered method:
the normal method is the default and is the one that has been presented above:
A directory is elected for operation if no -P or -] option excludes it. If at
least one -g or -[ option is given on command line, one -g or -[ option must
cover it, else it is not elected for operation. If a directory is not
selected, no recursion is done in it (the directory is pruned). For non
directories files, the same is true (P, -g, -[ and -] do apply) and a second
test must also be satisfied: no -X option must exclude the filename, and if at
least one -I option is given, one must match the given filename (using or not
wildcards).
the ordered method (when -am option is given on command-line):
The ordered method takes care of the order of presence between -X and -I in
one hand and of -P, -g, -[ and -] in the other hand (note that it has also the
same action concerning EA selection when using -u and -U options, but that's
no more file selection). In the ordered method the last argument take
precedence over all the previous ones, let's take an example:
-X "*.mp?" -I "*.mp3" -I "toto*"
Here dar will include all files except file of name "*.mp?" (those ending
with "mpX" where X is any character), but it will however include those
ending with ".mp3". It will also include files which name begin by "toto"
whatever they end with. This way, "toto.mp2" will be saved (while it
matches "*.mp?" it also begins by "toto") as well as "toto.txt" as well
as "joe.mp3" (while it matches "*.mp?" it also ends by "mp3"). But will
not be saved "joe.mp2" (because it does not begin by "toto", nor ends by
"mp3", and match "*.mp?" mask). As we see the last option (-I or -X)
overcomes the previous one. -P, -g, -[ and -] act together the same but
as seen above they do not only act on filename, but on the whole
path+filename. Note that (-g, -P, -[, -]) and (-X , -I) are independent
concerning their relative order. You can mix -X -I -g -P -] -[ in any
order, what will be important is the relative positions of -X options
compared to -I options, and the relative positions of -g -[ -] and -P
options between them.
In logical terms, if <prev_mask> is the mask generated by all previous mask on the
command line, -I <mask> generates the new following mask: <prev_mask> or <mask> .
While -X <mask> generates the new following mask: <prev_mask> and not <mask>. This
is recursive each time you add a -I or -X option. Things work the same with -P, -g,
-[ and -] options.
This ends the file selection explication let's continue with other options.
-u, --exclude-ea <mask>
Do not consider the Extended Attributes (EA) that are matched by the
given mask. By default, no EA are excluded, if the support for EA has
been activated at compilation time. This option can be used multiple
times.
-U, --include-ea <mask>
Do only consider the EA that match the given mask. By default, all EA
are included if no -u or -U option is present and if the support for
EA has been activated at compilation time. This option can be used
multiple times. See also the -am and -ae options, they also apply to
-U and -u options and read below the Note concerning EA.
Note concerning Extended Attributes (EA)
Support for EA must be activated at compilation time (the configure script tries to
do so if your system has all the required support for that). Thus you can get two
binaries of dar (of the same version), one supporting EA and another which does not
(dar -V to see whether EA support is activated). The archives they produce are the
same and can be read by each other. The only difference is that the binary without
EA support is not able to save or restore EAs, but is still able to test them and
list their presence.
In the following when we will speak about Extended Attribute (EA) or EA entry, we
will only consider a particular Extended Attribute key and its value. By
opposition, the set of all EA associated to a file will be designated by "EA set".
Since version 2.3.x the name of EA entries include the namespace for dar be able to
consider any type of EA (not only "system" and "user" as previously). Thus the two
previous options -u and -U have changed and now take an argument which is a mask
applied to EA entry names written in the following form namespace.name where
"namespace" is for example "user". Note that the mask may or may not include the
dot (.) and may match arbitrary part of the EA namespace+name, just remind that
masks will be applied to the "namespace.name" global string.
the -am flag here also enables the ordered method, for EA selection too. The
ordered versus normal method have been explained above in the file selection note,
with some examples using -X and -I. Here this is the same with -U and -u, (just
replace -X by -u and -I by -U, the corresponding mask will apply to Extended
Attribute selection in place of file selection).
Another point, independently of the -am option the -ae option can be used at
restoration time only. If set, when a file is about to be overwritten, all EA will
be first erased before restoring those selected for restoration in the archive
(according to the -U and -u options given). If not set, the EA of the existing file
will be overwritten, those extra EA that are not in the archive or are not selected
for restoration in regard to the -u and -U options will be preserved. If you have
not used any -u/-U option at backup time and want to restore from a set of
full/differential backups the EA exactly as they were, you have to use -ae for dar
removes the EA before overwriting their set of EA as stored in the archive. Without
-ae option dar will simply add EA to existing ones, thus get a different set of EA
for a give file than those recorded at the time of the backup.
Last point the -acase and -an options alters the case sensitivity of the -U and -u
masks that follow them on the command-line/included files as they do for -I, -X,
-P, -g, -[ and -] as well. Very last point ;-), if -ac option is used during backup
dar set back the atime after having read each file (see -aa/-ac options), this has
as side effect to modify the ctime date of each file. But ctime change is used by
dar to detect EA changes. In brief, the next time you backup a file that had to be
read (thus which contents changed), its EA will be saved even if they had not
changed. To avoid this side effect, don't use the -ac option if not necessary.
This ends the Extended Attribute selection explication let's continue with other options.
-4 --fsa-scope <family>[,<family>[, ...]
Reduce the scope of Filesystem Specific Attribute (FSA) to be
considered for the operation. FSA are grouped by family. Current
available families are:
extX this family takes care of Linux ext2/3/4 flag attributes set by
chattr(1) and read by lsattr(1). Dar only considers flags that
are possible to set or clear by users (or privileged user):
append-only, compressed, no_dump (Yes, dar can save files having
the nodump flag set and restore then afterward with that flag
set!), immutable, data-journaling, secure-deletion, no-tail-
merging, undeletable, noatime-update, synchronous-directory,
synchronous-update, top-of-directory-hierarchy. Note that "extx"
and "ext" are aliases for this FSA family. In spite of its name,
this family of attributes is not limited to ext2/3/4 filesystems.
HFS+
this family takes care of Mac OS X HFS+ birth date of files, in
addition of commonly found dates like atime (last access time),
ctime (last meta data change) and mtime (last data change).
none "none" is not a FSA family but can be used alone to ignore all
FSA families.
By default no restriction is done and FSA of all families are
considered at restoration time, but if a family has not been activated
at compilation time a warning is issued for each file that cannot have
its FSA restored completely (unless this family is excluded from the
scope thanks to the -4 option). At backup time, if an FSA family has
not been activated at compilation time, no warning is issued and FSA
of that family are ignored. Still at backup time, you can also ignore
FSA that have compilation time support by excluding them from the
operation thanks to this -4 option.
Example of use: --fsa-scope extX,HFS+
-am, --alter=mask set the ordered mode for mask. This affects the way -I and -X options
are interpreted, as well as -g, -P, -[ and -] options, -Z and -Y
options and -U and -u options. It can take any place on the command-
line and can be placed only once. See the file selection in brief
paragraph above for a detailed explanation of this option. It has also
an incidence on the --backup-hook-exclude and --backup-hook-include
options.
-an, --alter=no-case
set the filters in case insensitive mode. This concerns only masks
specified after this option (see also -acase option below). This
changes the behavior of -I, -X, -g, -P, -Z, -Y, -u and -U options.
Warning: case insensitivity requires interpreting filenames which
depends on the locale with which dar is run (defined by the LANG
environment variable). For example if you create files with LANG set
to fr_FR.UTF-8 and use non plain ASCII characters in filename, there
is chances that these non ASCII characters will be stored over several
bytes in that filename: so called "wide characters". If then you run
dar with LANG set to another value like ru_RU.koi8r, there is much
chances that these wide characters do not correspond to the same
letter or worse, that they do not match any valid wide character for
that locale. A filename is always a sequence of bytes and always saved
as such, but using --alter=no-case implies interpreting that sequence
in a way that depends on the given locale (as defined by the LANG
environment variable). As such, dar cannot know if a given file has to
be read with fr_FR.UTF-8 locale or with it_IT.iso88591 or ru_RU.koi8r
and so on, because this information is not stored in filenames. In
consequence, if different locales are used on your system and you are
doing a system wide backup, using --alter=no-case option may lead dar
to detect invalid wide character, in that case it falls back to a byte
by byte case sensitivity comparison (ASCII characters), which may not
be what you would expect at first sight: Most of the time, an upper
case wide character (stored on several bytes) does not match the
equivalent lower case wide character (several bytes too), when case
sensitivity comparison is performed byte by byte.
-acase, --alter=case
set back to case sensitive mode for filters. All following masks are
case sensitive, up to end of parsing or up to the next -an option.
This changes the behavior of -I, -X, -g, -P, -Z, -Y, -u and -U
options.
-ar, --alter=regex set the filters to be interpreted as regular expressions (man regex(7)
) instead of the default glob expression (man glob(7) ) This modifies
the -I, -X, -g, -P, -Z, -Y, -u and -U options that follows up to an
eventual -ag option (see just below). Note that for -P option, the
given mask matches the relative path part of the files path: Let's
take an example, assuming you have provided /usr/local to the -R
option, the mask "^foo$" will replaced internally by
"^/usr/local/foo$" while the mask "foo$" will be replaced internally
by "^/usr/local/.*foo$".
-ag, --alter=glob This option returns to glob expressions mode (which is the default)
after an -ar option has been used, this applies to any -I, -X, -g, -P,
-Z, -Y, -u and -U options that follow up to an eventual new -ar option
(see just above).
-i, --input <path> is available when reading from pipe (basename is "-" for -x, -l, -t,
-d or for -A when -c, -C or -+ is used). When reading from pipe,
standard input is used, but with this option, the file <path> (usually
a named pipe) is used instead. This option is to receive output from
dar_slave program (see doc/usage_notes.html for examples of use). Note
that when --sequential-read is used, dar uses a single pipe and does
no more rely on dar_slave, -i option can be used to tell dar which
named pipe to read the archive from, instead of the standard input.
-o, --output <path> is available when reading from pipe (basename is "-" for -x, -l, -t,
-d or for -A when -c, -C or -+ is used). When reading from pipe,
standard output is used to send request to dar_slave, but with this
option, the file <path> (usually a named pipe) is used instead. When
standard output is used, all messages goes to standard error (not only
interactive messages). See doc/usage_notes.html for examples of use.
This option is not to be used in --sequential-read mode.
-O, --comparison-field[=<flag>]
When comparing with the archive of reference (-c -A) during a
differential backup, when extracting (-x) or when comparing (-d) do
only considers certain fields. The available flags are:
ignore-owner all fields are considered except ownership.
This is useful when dar is used by a non-privileged
user. It will not consider a file has changed just
because of a uid or gid mismatch and at restoration dar
will not even try to set the file ownership.
mtime only inode type and last modification date is
considered as well as inode specific attributes like
file size for plain files. Ownership is ignored,
permission is ignored. During comparison, difference on
ownership or permission is ignored and at restoration
time dar will not try to set the inode permission and
ownership.
inode-type Only the inode type is considered. Ownership,
permission and dates are ignored. Inode specific
attributes are still considered (like file size for
plain files). Thus comparison will ignore differences
for ownership, permission, and dates and at restoration
dar will not try to set the ownership, permission and
dates.
When no flag is provided to this option, -O option acts as if the
"ignore-owner" flag was set, which is the behavior in older releases
(< 2.3.0). Note also that for backward compatibility, --ignore-owner
option still exists and since version 2.3.0 is just an alias to the
--comparison-field=ignore-owner option. Of course if this option is
not used, all fields are used for comparison or restoration.
-H[num], --hour[=num]
if -H is used, two dates are considered equal if they differ from a
integer number of hours, and that number is less than or equal to
[num]. If not specified, num defaults to 1. This is used when making a
differential backup, to compare last_modification date of inodes, at
restoration or merging time if overwriting policy is based on file's
data or EA being more recent and last, when comparing an archive with
a filesystem (-d option). This is to workaround some filesystems (like
Samba filesystem) that seems to change the dates of files after having
gone from or to daylight saving time (winter/summer time). Note that
-H option has influence on the overwriting policy (see -/ option) only
if it is found before on command-line or in an included file (using -B
option).
-E, --execute <string>
the string is a user command-line to be launched between slices. For
reading an archive (thus using -t, -d, -l or -x commands), the given
string is executed before the slice is read or even asked, for writing
an archive instead (thus using -c, -C or -+ commands), the given
string is executed once the slice has been completed. Some
substitution macros can be used in the string:
%% will be replaced by %
%p will be replaced by the slice path
%b will be replaced by the slice basename
%n will be replaced by the slice number (to be read or just
written). For reading, dar often needs the last slice, but
initially it does not know its number. If it cannot be found
in the current directory, the user command-line is then
called with %n equal to 0. This is a convenient way to
inform the user command to provide the last slice. If after
executing the string the requested slice is still not
present, dar asks the user (as usually) with a message on
the terminal. Once the last slice is found, the user
command-line is called a second time, with %n equal to the
value of the last slice number.
%N is the slice number with the leading zero as defined by
--min-digits option. If this option is not used, %N is
equivalent to %n.
%e will be replaced by the slice extension (always substituted
by "dar")
%c will be replaced by the context. Actually three possible
values exist: "init", "operation" and "last_slice". When
reading an archive for (testing, extraction, diff, listing,
or while reading the archive of reference, see below the -F
option), the "init" context takes place from the beginning
up to the time the catalogue is retrieved. On a multiple
slice archive this correspond to the last slice request.
After, that point comes the "operation" context. While
creating an archive, the context is always "operation"
except when the last slice has been created, in which case
the context is set to "last_slice".
%u will be replaced by the full URL of path where the slice is
stored
Several -E option can be given, given commands will then be called in
the order they appear on the command line and -B included files. Note
that having '-E script1 -E script2' is totally equivalent to '-E
"script1 ; script2"'. In other words if script1 fails, script2 fill
still be executed and dar will only be notified of the exit status of
the last -E option. Exit status of previous -E given commands will be
ignored. If this does not match your need, consider using a single
-aduc option (see below). More generally you can use any shell
construction in the argument to -E, including parenthesis, || and &&.
Such files given to -E option are known as DUC files (Dar User
Command). See also the environment variable DAR_DUC_PATH in the
ENVIRONMENT section at the end of this document.
-aduc, --alter=duc As described above for -E option, several -E/-F/-~ options (aka DUC
commands) are combined using the shell ";" operator, which ignores the
exit status of the first commands and only reports to dar the exit
status of the last command, leading all commands to always being
executed. --aduc option combines the different DUC commands using the
shell "&&" operator, which execute the next command if and only if the
previous command succeeded. In other words, dar get notified of an
error in any given DUC command but due to an error not all DUC
commands may be executed.
--aduc modifies the way the next DUC file is sticked to the previous command, in other
words:
dar --aduc -E script1 -E script2 ...
leads libdar to call a shell with the following line "script1 && script2"
dar -E script1 -script2 --aduc -E script3 ...
leads libdar to call a shell with the following line "script1 ; script2 &&
script3". In other words if you want to avoid the ";" use --aduc before any
-E/-F/-~ option.
-F, --ref-execute <string>
same as -E but is applied between slices of the reference archive (-A
option). --execute-ref is a synonym.
-~, --aux-execute <string>
same as -E and -F but is applied between slices of the auxiliary
archive (-@ option).
-K, --key [[<algo>]:]<string>
-K, --key gnupg:[<algo>]:keyid/email[,keyid/email[...]]
In the first syntax, encrypt/decrypt the archive using the <algo>
cipher with the <string> as pass phrase. An encrypted archive can only
be read if the same pass phrase is given (symmetric encryption).
Available ciphers are "blowfish" (alias "bf"), "aes", "twofish",
"serpent" and "camellia" for strong encryption and "scrambling" (alias
"scram") for a very weak encryption. By default if no <algo> or no ':'
is given, the aes256 cipher is assumed (default was blowfish up to
2.5.x). If your password contains a colon ':' you need to specify the
cipher to use (or at least use the initial ':' which is equivalent to
'bf:'). If the <string> is empty the pass phrase will be asked at
execution time. Thus, the smallest argument that -K can receive is ':'
which means aes256 cipher with the pass phrase asked at execution
time.
Note that giving the passphrase as argument to -K (or -J or '-$' see
below) may let other users learn pass phrase (thanks to the ps, or top
program for examples). It is thus wise to either use an empty pass
which will make dar ask the pass phrase when needed, or use -K (or -J
option) from a Dar Command File (see -B option), assuming it has the
appropriated permission to avoid other users reading it. For those
paranoids that are really concerned about security of their passwords,
having a password read from a DCF is not that secure, because while
the file gets parsed, dar makes use of "unsecured" memory (memory than
can be swapped to disk under heavy memory load conditions). It is only
when the passphrase has been identified that locked memory (aka secure
memory) is used to store the parsed passphrase. So, the most secure
way to transmit a passphrase to dar, then to libdar, then to
libgcrypt, is having dar asking passphrase at execution time, dar then
makes use of secured (locked) memory from the beginning.
since archive format 9 (archive generated by release 2.5.0 and
following) at reading time, it is not necessary to provide the
encryption algorithm used, just the passphrase is required, dar will
figure out which encryption algorithm had been used at archive
creation time. You can either omit -K in which case dar will ask for
the passphrase at execution time, or you can use -K <string> in a DCF
file as explained above (avoid using -K directly on command-line).
The second syntax starts with the word "gnupg" followed by a colon ':'
. In that situation, the same set or symmetric encryption algorithms
as described above is available after the colon, but the passphrase is
not given by the user but randomly chosen by libdar and encrypted
using the public key of the target users which email okkeyid (since
2.7.0) is given in a comma separated list. This random key (see also
--key-length below), once encrypted is placed at the beginning and at
the end of the generated archive. At reading time only the listed user
will be able to read that archive thanks to their respective private
key. This feature implies that each user (the archive creator as well
as the target users) have their GnuPG keyring set properly. In
particular, the archive creator must have validated the public keys of
the target users, and the target users must own the corresponding
private key in their keyring. Example: using "--key
gnupg::bob@nowhere.org,joe@somewhere.com" will generate an aes256
encrypted archive which passprhase randomly chosen by libdar will be
encrypted with the public keys of bob@nowhere.org and
joe@somewhere.com. To use blowfish in place of ars256 one could use
"--key gnupg:bf:bob@nowhere.org,joe@somewhere.com". Note that no check
is done about the trust you have set in GPG keyring that a particular
public key is owned by the phyical person you expect. See also --sign
option below.
Note that if you have set a passphrase on your private key, dar will
ask it dynamically, which requires dar to be run from a terminal. No
other way has been provided to transmit a private key's passphrase to
libdar. In consequence if you want to use dar/libdar in scripts and
make use of public key algorithm you should avoid setting a passphrase
to the private key you want to use. See also GNUPGHOME in the
ENVIRONMENT section at the end of this document.
Obvious but important! To read a gnupg encrypted archive, you need
your private key (not only the passphrase to activate it, if set).
Thus if you plan to make backup of your system and encrypt the backup
using gnupg, you should have a copy of this private key available out
of the archive (usb key, floppy, CD/DVD, ...) in order to be able to
restore your backup!
-J, --ref-key [[<algo>]:]<string>
same meaning/use as -K option's first syntax, but the given key is
used to decrypt the archive of reference (given with -A option).
--key-ref is a synonym. Note that for archives generated using dar
release 2.5.0 and above this option is no more necessary, unless you
want to give the passphrase on command-line (not recommended) or in
DCF file (which file would be set with restricted access permissions
and/or ACL).
-$, --aux-key [[<algo>]:]<string>
same as -J but for the auxiliary archive of reference (given with -@
option). Here too, this option is no more necessary to read archives
generated by dar release 2.5.0 and above.
-#, --crypto-block <size>
to be able to randomly access data in an archive, it is not encrypted
globally but block by block. You can define the encryption block size
thanks to this argument which default to 10240 bytes. Note that the
syntax used for -s option is also available here (k, M, G, etc.). Note
also that crypto-block is stored as a 32 bits integer thus value
larger than 4GB will cause an error. Note last, that the block size
given here must be provided when reading this resulting archive, using
the -* option if the archive is the archive of reference (given to -A
option) using -% options if the archive is the auxiliary archive of
reference (given to -@ option) or using this -# option if it is the
subject of the operation (listing, comparing, testing that archive).
If the value is not the default and the given value is not correct in
regard to the value given at archive creation time, the archive will
not be possible to decrypt, it is thus safer to keep the default value
(and not using at all the -#, -*, -% options).
-*, --ref-crypto-block <size>
same as --crypto-block but to read the archive of reference (-A
option). --crypto-block-ref is a synonym.
-%, --aux-crypto-block <size>
same as --crypto-block but to read the auxiliary archive of reference
(-@ option).
-e, --dry-run Do not perform any action (backup, restoration or merging), displays
all messages as if it was for real ("dry run" action). The --empty
option is a synonym.
-aSI, --alter=SI[-unit[s]]
when using k M G T E Z Y prefixes to define a size, use the SI
meaning: multiple of 10^3 (a Mega is 1,000,000).
-abinary, --alter=binary[-unit[s]]
when using k M G T E Z Y prefixes to define a size, use the historical
computer science meaning: multiple of 2^10 (a Mega is 1,048,576).
The --alter=SI and --alter=binary options can be used several times on
the command line. They affect all prefixes which follow, even those
found in files included by the -B option, up to the next
--alter=binary or --alter=SI occurrence. Note that if in a file
included by the -B option, an --alter=binary or --alter=SI is
encountered, it affects all the following prefixes, even those outside
the included files. For example, when running with the parameters "-B
some.dcf -s 1K", 1K may be equal to 1000 or 1024, depending on
--alter=binary or --alter=SI being present in the some.dcf file. By
default (before any --alter=SI/binary option is reached), binary
interpretation of prefixes is done, for compatibility with older
versions.
-ac, --alter=ctime When reading a filesystem (during a backup or comparison), restores
the atime of all files to what it was before the file was read. This
makes it appear as if it had not been read at all. However, because
there is no system call to let applications changing the ctime (last
inode change) of a file, setting back the atime results in the ctime
being changed (hence the alter=ctime). Some recent unix system allow
an application to get 'furtive read mode' to the filesystem (see
below). On older systems, however, for most users, having the atimes
of the files changed shouldn't be a problem, since they can be changed
by any other program (running by any user!) as well (like the content-
index program Beagle). Ctimes on the other hand, are the only way for
security software to detect if files on your system have been replaced
(by so called root-kits mostly). This means, that should you run dar
with -ac, security software which uses ctimes to check, will mark
every file on your system as compromised after the backup. In short,
this means this option should only be used by people who know what
they are doing. It's the opinion of this writer that any software
susceptible to atime changes is flaky or even broken (because of the
afore mentioned reasons why atimes can change). But, that doesn't take
away that there are programs who rely on atimes remaining the same,
like Leafnode NNTP caching software. Therefore this option exists.
-aa, --alter=atime When specifying -aa (by opposition to -ac), the atime of every read
file and directory is updated, and the ctime remains the same. In
other words, Dar itself does nothing with atimes and ctimes, it only
let the system do its job to update atimes when files are accessed for
reading. This is in accordance with what atimes and ctimes were meant
to represent. This is Dar's default (since version 2.4.0), unless
'furtive read mode' (see below) is supported by your system and dar
has been compiled with this support activated.
Furtive read mode is a mode in which neither atime nor ctime are modified while dar reads
each file and directory. This provides also better performances as nothing has to be wrote
back to disk. A known Unix kernel that supports this feature is Linux 2.6.8 and above
(support must also be present in the standard C library of the system for dar to be able
to activate this feature at compilation time). When this feature is activated, it becomes
the default behavior of dar for super user ; for other users the default is -aa. If
however as root user, you do not want to use "furtive read mode" (while it has been
activated at compilation time), you can specify either -aa or -ac option.
-at, --alter=tape-marks
For archive creation and merging, the default behavior (since release
2.4.0) is to add escape sequences (aka tape marks) followed by inode
information all along the archive. If -at is given, dar will not add
this information to the archive, resulting in a slightly smaller
archive and faster backup. When reading an archive, the default
behavior is to ignore these escape sequences and rather rely on the
catalogue located at the end of the archive. If instead --sequential-
read is given on command-line (see below), dar will avoid using the
catalogue at the end of the archive and will rely on these escape
sequences to know the contents of the archive, which will lead to a
sequential reading of the archive, operation suitable for tape media.
Note that it is not recommended to disable escape sequences (aka tape
marks) by using -at option except if you are more concerned by the
resulting size and execution speed of your backup (in particular if
you have a lot of small files) than by the possibility to recover your
data in case of corrupted or partially written archive. Without
escape sequences, dar cannot sequential read an archive, which is the
only way beside using an isolated catalogue to use an archive that has
a corrupted catalogue or has no catalogue at all, thing that happens
if a system crash occurred during the archive creation or due to lack
of disk space to complete the archive.
-0, --sequential-read
Change dar's behavior when reading an archive. By default, the
traditional way is used, which relies on the table of contents (aka
"the catalogue") located at the end of the archive. With the
--sequential-read option instead, dar will rely on escape sequences
that are inserted all along the archive with each file's inode
information. This will lead to a sequential reading of the archive,
operation suitable for tape medium. However, this feature is only
available for archive format starting revision "08" (i.e.: since
release 2.4.0) and if -at option has no been used during archive
creation or merging. This option is available for archive testing
(-t), comparison (-d), restoration (-x), listing (-l) and to read the
archive of reference (-A option) for isolation (-C) and archive
creation (-c). The sequential reading of an archive is always much
slower than the usual reading method, so you should not use this
option unless you really need it.
-9, --min-digits <num>[,<num ref>[,<num aux>]]
By default slice number contained in filename do not have any padded
zeros, which, when sorting a directory contents alphabetically leads
to read all the slices starting by '1', then by '2'. for example,
slice 1, 10, 11, 12, 13, ... 2, 20, 21, 23, ... etc. While dar is
absolutely not perturbed by this display problem, some user shall like
to have the slices sorted by order. For that reason, the --min-digits
option lets you ask dar to prepend enough zeros in the slice number
for it be as wide as the argument passed to --min-digits. For example,
if you provide 3 for that number, dar will store the slice number as
001, 002, 003, ... 999. Well, next slice will be 1000, thus it will
break again the alphabetical sorting order. You are thus advised to
use a number large enough to convert the number of slice you expect to
use. Before release 2.7.0, when reading an archive, you were also
requested to provide this same argument else dar was unable finding
the slice. Since 2.7.0 dar auto-detects the mi-digits value to use,
unless there is a mix of archive of the same basename with different
min-digits. In such conflicting context, you must bypass the min-
digits auto-detection mechanism and specify which min-digits value to
retain in order to read the archive, eventually followed by a comma
and the number of digits to use to read the archive of reference
(given to -A option), eventually followed by a comma and the number of
digits to use for the auxiliary archive of reference (given to -@
option).
--pipe-fd <num> will read further arguments from the file-descriptor <num>. The
arguments read through this file-descriptor must follow a TLV
(Type/Length/Value) list format. This option is not intended for human
use, but for other programs launching dar like dar_manager. This
feature has been added to overcome the command line length limit.
-al, --alter=lax When reading an archive, dar will try to workaround data corruption of
slice header, archive header and catalogue. This option is to be used
as last resort solution when facing media corruption. It is rather and
still strongly encourage to test archives before relying on them as
well as using Parchive to do parity data of each slice to be able to
recover data corruption in a much more effective manner and with much
more chance of success. Dar also has the possibility to backup a
catalogue using an isolated catalogue, but this does not face slice
header corruption or even saved file's data corruption (dar will
detect but will not correct such event).
-G, --multi-thread { <num> | <crypto>,<compression> }
When libdar is compiled against libthreadar, it can make use of
several threads. If the argument is two numbers separated by a comma
the first defines the number of worker threads to cipher/decipher, the
second the number of threads to compress/decompress. If the argument
is a single number (-G <n>) it is equivalent to giving this number as
the number of compression threads and giving 2 for the ciphering
threads (-G 2,<n>). The use of multi-threading at archive creation
time leads to rely on per block compression rather than the legacy
streaming compression and if the block-size is not specified (see -z
option for details) it defaults to 240 KiB. Not providing any -G
option, is equivalent to providing -G 2,1 when libthreadar is
available else -G 1,1. Note that if an archive has been created with
streaming compression, the decompression cannot use multi-threads, the
deciphering can always use multiple threads.
-j, --network-retry-delay <seconds>
When a temporary network error occurs (lack of connectivity, server
unavailable, and so on), dar does not give up, it waits some time then
retries the failed operation. This option is available to change the
default retry time which is 3 seconds. If set to zero, libdar will not
wait but rather ask the user whether to retry or abort in case of
network error.
-afile-auth, --alter=file-authentication
With this option, When reading or writing an archive to a remote
repository when no password is provided, instead of interactively
asking for a password dar will first check the ~/.netrc file for
credentials when relying on FTP protocol and also for SFTP protocol
(libcurl allows that, which is unusual but somehow useful). If no
password could be found in ~/.netrc, in second time and for SFTP only,
dar will try to connect using public key authentication. Public key
authentication is tried without this option, but it is useful here to
avoid having password requested interactively.
-ab, --alter=blind-to-signatures
do not check whether an encrypted archive with public key that has
also been signed have correct signatures.
SAVING, ISOLATION, MERGING AND REPAIRING SPECIFIC OPTIONS (to use with -c, -C or -+)
-z, --compression={ [algo] | level | algo:level | algo:level:block-size }
add compression within slices. If -z is not specified, no compression is performed,
but if -z is specified without algorithm gzip will be assumed.
algo:
the following values are available "gzip", "bzip2", "lzo", "xz", "zstd" or
"lz4".
level:
The compression level (an integer from 1 to 9 except for zstd which ranges from
1 to 22) is optional, and is 9 by default. Be careful when using xz algorithm
better specify a compression ratio less than or equal to 6 to avoid important
memory requirements. A ratio of 1 means less compression and faster processing,
while at the opposite a ratio of 9 gives the best compression but longest
processing time.
block-size:
if set to zero (which is also the default value), you will get the legacy (and
performant) "streaming compression" mode that was the only available up to
release 2.7.0. Since then, the "block compression" mode gives the ability to
leverage multi-threading (see -G option) by compressing per block and giving
different blocks to different threads. The larger the block is, the better the
compression ratio will be (it tends to be as good as the one of the streaming
compression mode, when block size increases), but files smaller than a block
size can only be processed by a single thread. The memory requirement also
increases by the product of the block size times the number of threads. Last, a
too small block-size will cost more CPU cycles (the multi-threading management
overhead will become important compared to the effective compression processing)
and independently, short blocks gives poor compression rates. It is thus advised
to use values at least greater than 50 ~ 100 KiB (you can use the k,M,G,...
suffixes described for the -s option). If the block-size is not specified and
given -G option leads to a number of compression threads greater or equal to 2,
a block-size of 240 KiB is used. If you want the legacy streaming compression,
do not use -G option (or use it specifying only 1 compression thread) and do not
set the compression block size (or set it to zero).
Valid usage of -z option is for example: -z, -z9, -zlzo, -zgzip, -zbzip2, -zlzo:6,
-zbzip2:2, -zgzip:1, -zxz:6, -zlz4::10k -z::12000 -zbzip2:8:10k and so on. Usage for
long option is the same: --compression, --compression=9, --compression=lzo,
--compression=gzip, --compression=bzip2, --compression=lzo:6, --compression=bzip2:2,
--compression=gzip:1 --compression=xz:9 and so on.
About lzo compression, the compression levels of dar and lzop program do not match.
If you want to get the behavior of compression level 1 of lzop, use the lzop-1
algorithm in place of lzo with dar/libdar. If you want to get the behavior of lzop
compression level 3, use the lzop-3 algorithm in place of the lzo algorithm. Lzop
compression levels 2, 4, 5 and 6 are the same as level 3. last, there is no
difference about compression level 7, 8 and 9 between dar and lzop. The lzop-1 and
lzop-3 algorithms do not make use of any compression level (compression level is
ignored with these algorithms).
-s, --slice <number>
Size of the slices in bytes. If the number is appended by k (or K), M,
G, T, P, E, Z, Y, R or Q the size is in kilobytes, megabytes,
gigabytes, terabytes, petabytes, exabytes, zettabytes, yottabytes,
ronnabytes or quettabytes respectively. Example: "20M" means 20
megabytes, by default, it is the same as giving 20971520 as argument
(see also -aSI and -abinary options). If -s is not present the backup
will be written to a single slice whatever the size of the backup may
be (assuming your operating system can support arbitrarily large
files).
-S, --first-slice <number>
-S gives the size of the first slice which may be chosen independently
of the size of following slices (either bigger or smaller). This
option needs -s option and by default of -S option, the size of the
first slice is the same as the one of the following slices.
-p [<integer>], --pause[=<integer>]
pauses before writing to a new slice (this requires -s). By default
there is no pause, all slices are written in the same directory, up to
the end of the backup or until the filesystem is full. In this later
case, the user is informed of the lack of disk space and dar stops for
user action. As soon as some disk space is available, the user can
continue the backup. The optional integer that this option can receive
tells dar to only pause every 'n' slice. Giving 3 for 'n' will make
dar pause only after slices 3, 6, 9 and so on. If this integer is not
specified, the behavior is as if '1' was given as argument which makes
dar pause after each slice.
-D, --empty-dir At backup time only, when excluding directories either explicitly
using -P or -] options, or implicitly by giving a -g or -[ options (a
directory is excluded if it does not match mask given with -g options
or -[ options) dar does not store anything about these. But with -D
option, dar stores them as empty directories. This can be useful, if
excluding a mount point (like /proc or /dev/pts). At restoration time,
dar will then recreate these directories (if necessary). This option
has no meaning with -C and is ignored in that case. Independently of
that, -D can also be used at restoration time, but it activates a
slightly different feature (see RESTORATION SPECIFIC OPTIONS below).
-Z, --exclude-compression <mask>
Filenames covered by this mask are not compressed. It is only useful
in conjunction with -z option. By default, all files are compressed
(if compression is used). This option can be used several times, in
that case a file that matches one of the -Z mask will not be
compressed. Argument given to -Z must not be include any path, just
the filename (eventually/probably using wildcards). This option used
while merging or repairing allow one to change the compression of
files.
-Y, --include-compression <mask>
Filenames covered by this mask (and not covered masks given to -Z
option(s)) are the only to be compressed. It is only available with -z
option. By default all files are compressed. This option can be used
several times, in that case all files that match one of the -Y will be
compressed, if they do not also match on of the -Z masks. The ordered
method here applies too when activated (with -am option), it works
exactly the same as -I and -X options, but apply to file compression,
not file selection. In other word, it matches only on the file name,
not on the path of files. This option used while merging or repairing
allow one to change the compression of files.
-m, --mincompr <number>
files which size is below this value will not be compressed. If -m is
not specified it is equivalent to giving -m 100 as argument. If you
want to compress all files whatever their size is you thus need to
type -m 0 on the command line. The size unit is the byte (octet) and
the same number extensions as those used with -s or -S are available
here, if you want to specify the size in kilobyte, megabyte, gigabyte
etc.
-1, --sparse-file-min-size <number>
Define the minimum length of zeroed bytes to replace by "holes". By
default, this feature is activated with a value of 15 bytes. To
completely disable it, set the size to zero. Disabling this feature
will bring some noticeable speed improvement but will probably make
the archive slightly bigger (depending on the nature of the data).
Sparse files are files that contain so called holes. On a filesystem,
the portion of zeroed bytes is not stored on disk, thus an arbitrary
large file with huge portion of zeros may only require a few bytes of
disk storage. While dar cannot detect how is allocated a given file
because it makes a filesystem abstraction (it does not know the
implementation of any particular filesystem, where from its
portability), when it finds a sequence of zeroed bytes larger than the
given threshold it can assume that it is in presence of a hole. Doing
so, it does not store the given zeroed bytes into the archive, but
place a tag beside the saved data to record the size of the hole and
thus where to place the next non zeroed bytes. This makes dar archive
disk space requirement much smaller when a sparse files is met. At
restoration time, dar will restore holes writing normal data and
seeking over the hole to write down the normal data after each hole.
If the underlying file system supports sparse files, this will restore
the holes. Note that there is no difference for applications whether a
file is sparse or not, thus dar may well transform normal files into
sparse files and vice-versa, only the disk requirement will change.
Last point, if dar can reduce disk requirement for archive with holes
as small as 15 bytes (smaller value works but the overhead cost more
than what is required to store the zeroed bytes normally), it may not
be the same at restoration, because filesystem allocation unit is
usually several kilobytes (a page), however restored file will never
be larger than it could be without holes. The only drawback of this
feature is the additional CPU cycle it requires.
-ak, --alter=keep-compressed
During merging and repairing operation, keep files compressed, this
has several restrictions : -z, -Z, -Y, -m are ignored, if two archives
have to be merged, both must use the same compression algorithm or one
of them must not use compression at all (this last restriction will
probably disappear in a next version). The advantage of this option is
a greater speed of execution (compression is usually CPU intensive).
-ah, --alter=holes-recheck
For merging and repairing, the sparse file detection mechanism is
disabled by default. However if you want to activate it (assuming you
have an old archive you want to convert the current archive format
taking care of sparse files), you need to use -ah option to reactivate
the sparse file detection mechanism. Then for merging and repairing
--sparse-file-min-size can be used as described above for archive
creation. In addition, you can have files stored as sparse file in the
archive of reference be stored as normal files in the merged archive
using -ah and passing to --sparse-file-min-size an value larger than
all file sizes, for example as of today in year 2018, passing -ah
--sparse-file-min-size 1E (1E for one exabyte) should be large enough.
--nodump do not save files which have the 'd' flag set (see chattr(1) lsattr(1)
ext2 commands). This option may not be available if the system dar has
been compiled on did not provide support for ext2 flags. Note that
this option does nothing with -+ option (merging) as no filesystem is
used for that operation.
-5, --exclude-by-ea[=<extended attribute name>]
exclude inodes from backup that have been set with the EA given in
argument. If not argument is given to that option the default EA used
to exclude files from backup is "user.libdar_no_backup". To set this
attribute to a given file, use the following command: "setfattr -n
user.libdar_no_backup <filename>", to remove it: "setfattr -x
user.libdar_no_backup <filename>". Last, to check the presence this
EA: "getfattr <filename>"
-M, --mount-points={ I:<path to fs> | X:<path to fs> }
If the argument is of the I:<path to fs> form, the filesystem to which
this path points to is considered for the backup operation, that's to
say, other file filtering mechanism will be applied and some or all
files of that filesystem will be saved for backup. While with the
X:<path to fs> form, no file in that filesystem will even be
considered for backup. both X: and I: forms must be provided with an
absolute path. -M option can be used several times on the command-
line. If only I: forms are used, the filesystem based filtering
mechanism behaves as a white list (only those listed paths are
included). If only X: form is used, the filesystem based filtering
mechanism behaves as a black list (everything is considered except
those listed paths). Last, while a mix of I: and X: forms are used,
filsystems that will be considered for backup will be those given with
an I: form and not also given with an X: form. Note that this is
filesystem based filtering, not path based: If for example a
filesystem is mounted under /var directory and you specify I:/var/log
all /var filesystem will be considered for backup. If you rather want
to only save what is in /var/log use the -P/-g/-X/-I/-[/-] options
that realise the file filtering by name and path+name. You cannot
exclude the filesystem which contains the path given to -R option. The
use of -M option with argument erases any previous configuration done
with -M option without argument (see below), and vice versa. By
default (no -M option specified), no filtering based on filesystem is
performed, in other worlds all files are considered for other file
filtering mechanism (in particular -P/-g/-X/-I/-[/-] options) and
eventually backed up.
example of use:
-MI:/var -MX:/var/spool
--mount-points=I:/var --mount-point=X:/var/spool
-M, --no-mount-points
This is the legacy form of the option described just above, that
existed before release 2.7.0. When -M option is provided without
argument, only files located on the filesystem pointed to by the path
given to -R option will be considered for backup. Subdirectory that
are mounting points for other filesystems will not be saved (or saved
empty if -D option is used). This option is useless and ignored for
merging operation. The use of -M without option lead dar to ignore any
previous -M I:<path> and -M X:<path> options that could have been
given on command-line or -B included file so far.
-, , --cache-directory-tagging
don't save contents of directories that use the Cache Directory
Tagging Standard. See http://www.brynosaurus.com/cachedir/spec.html
for details. (this option is useless with -+ option)
-/ , --overwriting-policy <policy>
This option let the user define when or how file overwriting can occur
at restoration or archive merging time. It does no apply to slice
overwriting which are driven by the -n option, it does instead apply
to file during extraction and files inside archives when merging two
of them. When considering overwriting, a file is said to be 'in place'
while an other is known as 'new' or 'to be added'. At restoration
time, the 'in place' is the one that is present in filesystem while
the 'to be added' is the one from the archive. At merging time, the
'in place' is the one of the '-A' archive of reference while the 'to
be added' is the one from the auxiliary '-@' archive or reference.
This option does not apply to archive repairing.
As soon as you use -/ option -n only applies only to slice overwriting
and the -r, -k and -ae options are ignored (restoration specific
options).
The given <policy> argument is composed of actions and eventually of
conditional expressions. Actions do define how to solve overwriting
conflict about file's data on one side and file's Attributes (Extended
and Filesystem Specific) on the other side. An action is thus a couple
of action for Data and for EA+FSA. Actions for Data are represented by
uppercase letters, while action for EA+FSA are defined by lowercase
letters. Both actions are independent of each other:
P means 'Preserve'. When merging two archives, the data of the
resulting archive will be taken from the 'in place' file. While
when extracting, the data of the inode in filesystem will be
preserved (thus no overwriting will occur for the data).
O means 'Overwrite'. When merging two archives, the data of the
resulting archive will be taken from the 'to be added' file.
While when extracting, the data of the inode in filesystem will
be overwritten by data from the archive.
S means 'mark Saved and preserve'. When merging two archives, the
data of the resulting archive will be marked as already saved in
the archive of reference (making thus a differential archive,
even if none of the original archive were differential archives).
All data will be dropped in the resulting archive, but the last
modification date [aka mtime] (used to detect change in file's
data) will be taken from the 'in place' file. This action does
not apply when extracting files, it is thus considered equal to
"Preserve" (P) in that situation.
T means 'mark Saved and overwrite'. When merging two archives, the
data of the resulting archive will be marked as already saved
(same as 'S' action): all data will be dropped in the resulting
archive, however the last modification date [aka mtime] (used to
detect changes in a file's data) will be taken from the 'to be
added' file. This action does not apply when extracting files, it
is thus considered equal to "Overwrite" (O) in that situation.
R means 'Remove'. When merging two archives, the resulting archive
will not contain any entry corresponding to the file that were in
conflict. This also implies that no EA will be stored for that
particular entry as the entry will no more exist in the resulting
archive (as if it had never yet existed). When extracting files,
this will lead to file's suppression.
p means 'Preserve', same as 'P' (but lowercase letter) preserve the
whole EA set and FSA. When merging two archives, the Attributes
set of the resulting file will be the ones of the 'in place' file
(whatever is the overwriting action taken for its data). While
when extracting files to filesystem, the Attributes of the file
in filesystem will not be changed (whatever is the overwriting
action taken for its data, unless the file is removed using the
'R' policy, which would remove the inode and thus also any
Attributes it had).
o means 'Overwrite', same as 'O' (but lowercase letter) overwrite
the whole EA set and FSA. When merging two archives, the
Attributes set of the resulting file will be taken from the 'to
be added' file. While when extracting files, the Attributes set
of the file in the filesystem will have its Attributes erased and
replaced by those of the file in the archive (still independent
of what overwriting action is taken for file's data).
s means 'mark Saved and preserve', same as 'S' (but lowercase
letter) for EA and FSA instead of data. When merging two
archives, the EA and FSA of the resulting file are marked as
already saved in the archive of reference, thus they are dropped
but the date of last inode change [aka ctime] (used to detect
changes in file's EA and FSA) will be taken from the 'in place'
file. This action does not apply when extracting files, it is
thus considered equivalent to "Preserve" (p) in that situation.
t means 'mark Saved and overwrite', same as 'T' (but lowercase
letter) for EA and FSA instead of data. When merging two
archives, the EA and FSA of the resulting file are marked as
already saved in the archive of reference, thus they are dropped
but the date of last inode change [aka ctime] (use to track
changes in EA) will be taken from the 'to be added' file. This
action does not apply when extracting files, it is thus
considered an equivalent to "Overwrite" (o) in that situation.
m means 'merge Attributes and preserve'. The resulting file in the
merged archive will have Attribute entries from both the 'in
place' and the 'to be added' files. If both files share a same
Attribute entry (same FSA or for EA the same key for a given
association) the one of the 'in place' file is kept (where from
the 'preserve' notion). When extracting a file, the file in the
filesystem will have its EA and FSA set enriched by the ones of
the file in the archive that do not exist on filesystem, but its
already existing Attributes will stay untouched.
n means 'merge Attributes and overwrite'. The resulting file in the
merged archive will have Attribute entries from both the 'in
place' and the 'to be added' files. If both files share a same
Attribute entry (same FSA or for EA the same key for a given
association) the one of the 'to be added' file will be kept
(where from the 'overwrite' notion). When extracting file, the
file in the filesystem will have its Attributes set enriched by
ones of the file in the archive with some of them possibly been
overwritten.
r means 'remove', same as 'R' but for the Attribute set (thus all
EA and FSA entries) of a given file ('r' is lowercase letter
here). The file of the resulting archive during merging operation
will not own any EA nor any FSA, even if the 'in place' and/or
the 'to be added' files did have some. For file extraction, this
means that the file in the filesystem will loose all its EA set.
The FSA cannot be 'removed' from a filesystem and may not always
have a default value, thus this action does not modify FSA at all
in case of archive extraction. But in case of merging the FSA are
removed as previously described. As for all the previous tests,
this Attribute operation is independent of the operation chosen
for file's data (uppercase letters).
d means 'delete'. When a same EA or FSA entry is found both in the
'in place' and 'to be added' files, such entry will be absent in
the resulting archive. In other words, when merging, the EA set
and FSA will only contain EA and FSA entries specific to the 'in
place' and those specific to the 'to be added' file. Entries in
common will not be present. When extracting a file from an
archive, the file on filesystem will have its EA set enriched by
entries of the 'to be added' file that are new to the 'in place'
file. The other EA entries (which are thus present in both
archive and filesystem) will be removed from the set, which the
other FSA will stay untouched (FSA cannot be "removed" from a
filesystem, nor they always have a default value).
* is valid for both EA and data. It tells that the action is not
yet defined at this step of the evaluation and that further
evaluation is required (see the 'chain' operator below).
A means 'Ask for user decision'. This uppercase letter concerns
Data overwriting. An application interaction let the user define
the action for each file in conflict. Note, that this action if
used alone may become very boring or painful. The idea is to use
it in conditional statements (which are described below) to have
dar ask for only non obvious cases.
a means 'Ask for user decision'. This lowercase letter is the
equivalent for EA and FSA of the 'A' action. It is intended to be
used in the same conditional statements described below.
An action is thus a couple of letters, the first being uppercase (for
file's data) the second being lowercase (for file's EA and FSA). When
-/ option is not given, the action is equivalent to '-/ Pp', making
dar proceed to file, EA and FSA preservation. Before release 2.4.0
(June 2011), only -n and -w options were available to define the
overwriting policy and the default behavior was to warn and wait for
confirmation before overwriting, which behavior can be set by the '-/
Oo' policy. It seems the default behavior changed to '-/ Pp' at that
time and nobody complained or noticed the difference until 2023, so
this default behavior will not be reverted, as nobody complained for
more than 12 years about that. Here follows some examples of actions,
all these are done for any entry found in conflict during archive
merging or archive extraction, we will see further how to define
conditional actions.
-/ Rr
will lead dar to remove any file from filesystem that ought to be
restored(!). Note the action for EA/FSA is useless, the EA and
FSA will always be erased as well as data using 'R'. Thus '-/ Rp'
would lead to the same result.
-/ Po
will keep data of the 'in place' file and EA and FSA set from the
'to be added' file.
-/ Ss
Using this option when merging an archive with itself (used both
as archive of reference (-A option) and auxiliary archive of
reference (-@ option) ) will provide the same action as an
archive isolation of the archive of reference, but using twice
more memory (so keep using the isolation operation as before!
Here this is just an illustration of the possibility)
As seem previously -u and -U options can be used to filter which EA
entry to consider and which to ignore. The question here is to explain
how this filtering mechanism interacts with the different policies we
just presented above. For files that are not in conflict (found only
as 'in place' or as 'to be added'), only the EA entries matching the
EA filter are kept. For files in conflict, the overwriting policy is
evaluated first, then the filtering mechanism is applied *after* it.
Thus for example, using the following [ -/ "Po" -u "*test" ], when
merging two archives, only EA ending with "test" will be retained, and
when a conflict takes place, this "*test" ending EA will be taken from
the 'to be added' file if it has some EA of that type, its other EA
entry will be ignored as well as any EA entry of the 'in place' file
even those ending by "test". At restoration in using the same options,
file without conflict will get restored but only EA entry ending with
"test" will be restored, and for file with conflict (already present
in filesystem), EA set of file in filesystem will be removed and
replaced the EA entries of the file in archive that ends by "test", if
some exist.
the situation is similar with FSA family scope and overwriting policy.
Only FSA of a family present in the scope will be retained, the
overwriting policy acts first then the FSA scope is applied. Note
however that any FSA present on filesystem and excluded from the FSA
scope are not touched.
Well, now let's see how to bring some more fun using conditional
statements in all these actions. The structure to use is the
following:
{<condition>}[<action if condition is true>]
This syntax let you place an action (as the ones we saw just
above) inside the brackets '[' and ']' (for example [Pp]) that
will take effect only if the evaluation of the <condition> is
true. Stated that a such statement is a new type of action, you
may have guessed that you may use it recursively:
{<condition1>}[{<condition2>}[<action>]).
Well so far it seems useless. But instead of the "if <condition> then
<action> else <action>" paradigm common to programming languages, due
to the command line context it has been chosen to instead use and
implicit "OR" operator between actions. Thus you can "stack"
conditional statements this way: {<condition1>}[<action1>]
{<condition2>}[<action2>] <action3>. In this example, if <condition1>
is true then <action1> will be used, ELSE if <condition2> is true then
<action2> will be used ELSE <action3> will be used. This leads to the
same possibilities as what is available with programming languages,
but with a slightly more simple syntax. Seen this, the recursion of
conditional syntax is more interesting. For readability, you are
allowed to add any space or tab in the overwriting policy, but the
resulting overwriting policy must be given as a single argument to
dar, thus the use of quotes (either simple ´arg´ or double "arg") is
necessary.
The last operator we will see is the 'chain' operator. Once an
expression is evaluated, the resulting couple of action may contain an
'*' (undefined action for EA or data). Further evaluation must be
done. The chain operator which is represented by a semicolon ';' let
one to separate several independent expressions that will be evaluated
in turn up to the time the couple of action is fully defined. Once an
action (for EA or for Data) is defined, it can be redefined by a
subsequent evaluation in the chain, however if the action is defined
it cannot be set back to undefined, thus '*' will never overwrite a
previously defined action. If at the end of the policy the couple of
action is not fully defined, the 'preserve' action is used ('P' or 'p'
depending on which of EA or Data is left undefined). Here follow a
example of syntax:
-/ "{<condition1>}[P*] O* ; {<condition2>[*p] *o} ; Rr"
The first expression will evaluate to either P* or O*. At this
step, as the action is not completely defined, the second part of
the chain is evaluated, It will end with either *p or *o. In any
case, we have after this second statement of the chain a fully
defined action for both data and EA (either Pp, Po, Op or Oo).
Thus the evaluation stops here and the "Rr" policy will never be
evaluated.
We now have one last thing to see: the available conditions (what to
place between braces '{' and '}'). Conditions are defined each by a
letter, eventually followed by an argument between parenthesis. The
usual logical operators are available: negation (!), conjunction (&)
disjunction (|). These characters must be escaped or quoted to not be
interpreted by the shell when used on command-line. In particular the
'!' under most shell must be quoted and escaped (-/ '{\!R}[..]..', The
escape character '\' is not necessary inside DCF files (those given to
-B option) as no shell is used to interpret these files. To these
usual operators has been added a new one: the "inversion" operator,
noted '~'. Like the negation, it is an unary operator but unlike the
negation, it inverses the roles of 'in place' and 'to be added' for
the evaluation, which is slightly different from taking the negation
of the result of the evaluation. All these operators follow the usual
precedence: unary operators ('!' and '~') are evaluated first, then
the conjunction '&' then the disjunction '|'. To override this, you
can use parenthesis '(' and ')' inside the condition. Over these
logical operators, the conditions are based on atomic operator that
compare the 'in place' file to the 'to be added' file. Here they
follow:
I true only if the 'in place' entry is an inode. This condition
does not have any consideration toward the to be added object.
Note that ~I can be used to check the nature of the 'to be added'
object. A 'detruit' entry, which record the fact that a file has
been removed since the archive of reference, is not an inode for
example, and the only type of entry that is not an inode is a
'detruit'. Thus you can define an action on 'detruit' objects
using the "!I" expression for the 'in place' entry and "!~I" for
the 'to be added' entry.
D true only if the 'in place' entry is a directory. To know whether
the 'to be added' is a directory or not, one would use the
"inversion" operator: ~D
F true only if the 'in place' entry is a plain file (true also if
this plain file is a 'hard link', that's it if its inode is
linked several times to the directory tree)
H true only if the 'in place' entry is an inode linked several
times to the directory tree (= hard link) it may be a plain file,
a Unix socket, a pipe, char device, a block device for example.
A same as H but the current 'in place' entry is the first link we
meet pointing to that hard linked inode.
R true if the 'in place' entry is more recent than or of same date
as the 'to be added' entry. The last modification date [aka
mtime] is used for this comparison. If the 'to be added' entry is
not an inode (and thus has no mtime), the 'in place' is
considered to be more recent than the 'to be added' entry. Same
thing if the 'in place' entry is not an inode (and has no mtime
available for comparison), it is here too assumed to be more
recent.
R(<date>)
true if the 'in place' entry is more recent than or of the same
date as the fixed <date> given in argument. No consideration is
done toward the 'to be added' element. The <date> format is the
same as the one used with -af option. If an entry has no mtime
(it is not an inode for example) it is assumed an virtual mtime
of zero.
B true only if both 'in place' and 'to be added' are plain file
(hard linked or not) and if the 'in place' file's data is larger
or equal to the 'to be added' file's data. If one or both entry
are not plain files (or hard link to plain file) and thus the
file size comparison is not possible, the 'in place' entry is
assumed to be 'bigger' than the 'to be added' entry.
S true only if the 'in place' data is saved in the archive (not
marked as unchanged nor marked as only inode metadata changed,
since the archive of reference). Note that while extracting files
from an archive, the 'in place' file is the one in the
filesystem, which always has its data 'saved' (from libdar point
of view). The 'inversion' of this atomic operator ~S may still be
interesting in the context of restoration.
Y true only if the 'in place' data is saved but dirty (plain file
having its data changed at the time it was read for backup).
Note, that restoring in sequential read mode, it is not possible
to known whether a file is dirty (it is possible to know it once
having read its data, but sequential reading does not allows then
to skip forward to get the dirty state of the file and skip
backward to eventually restore that file, depending on the
overwriting policy result).
X true only if the 'in place' data is a sparse file
T true only if the 'in place' and 'to be added' entries are of same
type (plain file, Unix socket, named pipe, block device, char
device, symlink, directory, 'detruit' (which stands for file
deleted since the archive of reference was done), and so on).
Note that the number of links to inode (i.e. whether this is a
hard links or not) is not taken into account.
L true only if the 'in place' entry has delta signature associated
with it.
E true only if 'in place' and 'to be added' are of the same type
and have the same inode data information: uid, gid, permission,
modification date are taken into account, atime and ctime are
ignored in this comparison. If both are plain files, the file
sizes must be the same for this condition to succeed. For char
and block devices, both major and minor numbers must match. Last,
for symlink, the target (the file path they point to) must be the
same.
e true if the 'in place' entry has EA (may they be saved or just
recorded as existing).
r true if the 'in place' entry has more recent or equal dated EA to
the 'to be added' entry. If 'to be added' has no EA or is even
not an inode, true is returned. If 'in place' has no EA or is
even not an inode, true is returned unless 'to be added' has some
EA. The comparison is done on ctime dates.
r(<date>)
true if the 'in place' entry has more recent or equal dated EA to
the fixed <date> given in argument. No consideration is done
toward the 'to be added' element. The <date> format is the same
as the one used with -af option. If an entry has no date (ctime
date) (when it is not an inode for example) it is assumed an
virtual ctime of value zero.
m true only if 'in place' has more or equal number of EA entry in
its set of EA than 'to be added' has. If an entry has not EA or
is not even an inode, it is assumed it has zero entry. The
comparison is done on this number. Note that the number of EA
entry is not the size used to store these entries. For example,
the EA entry "user.test" counts for 1, whatever is the length of
the value associated to it.
b true if the 'in place' entry has bigger EA set or equal size EA
set than the 'to be added' entry. If an entry has no EA or is
even not an inode, it is assumed that it has a zero byte length
EA set. The comparison is done on this number in that case. Note
that the comparison is done on the bytes used to store the whole
EA set associated to a given file.
s true if the 'in place' entry is an inode (or a hard linked inode)
and has its EA saved in the archive of reference, not only marked
present but unchanged since last backup. This test does not take
the 'to be added' entry into account.
Well, you've seen that uppercase letter are kept when comparison is
based on the inode or data while lowercase letter is used for atomics
based on EA. Now that we have completed our tour of this feature let's
see some examples:
-/ Pp
as seen previously this is what does -n option for files when no
overwriting policy is defined, which avoids any overwriting for
Data as well as for EA.
-/ "{!T}[Pp] {R}[{r}[Pp]Po] {r}[Op] Oo"
Space and tabs are allowed to ease readability. Here the policy
stands for: If files in conflicts are not of the same type then
keep Data and EA of the entry 'in place'. Else if 'in place' has
a more recent data then if 'in place' has more recent EA then
keep both its Data and EA, else keep only its Data and overwrite
its EA. Else (if 'in place' has not the more recent data), if it
has the more recent EA then overwrite the data but keep its EA,
else overwrite both its data and EA. This policy tends to
preserve the most recent data or EA, but it does not take into
account the fact that EA or Data is effectively saved into the
archive of just marked as unchanged since the archive of
reference.
-/ "{!T}[{~D}[Oo] Pp]"
If entries are not of the same type, if the 'to be added' entry
is a directory then we keep it and overwrite the 'in place'
entry, else we keep the 'in place' entry. If entry are of same
type, the policy does not provide any action, thus the default
action is used: "Pp". You can change this default action easily
using a chain operator:
-/ "{!T}[{~D}[Oo] Pp] ; Aa"
In this case instead, if entry are of the same type, the user
will be asked what to.
-/ "{!T|!I}[{R}[Pp] Oo] {I&~I}[{S}[{~S}[{R}[P*] O*] P*] {~S}[O*]
{R}[P*] O* ; {s}[{~s}[{r}[*p] *o] *p] {~s}[*o] ] {r}[*p] *o"
Well this may seems a bit too complex but just see it as an
illustration of what is possible to do: If both 'in place' and
'to be added' are not of the same type we keep data and EA of the
most recent file (last modification date). Else, both are of the
same type. If both are inode we evaluate a two expressions chain
(expressions are separated by a semicolon ';') we will see in
detail further. Else if they are of same type but are not inode
we take the EA and data of the most recent entry (this is the
last 10 chars of the string). Well, now let's see the case of
inode: The first expression in the chain sets the action for data
and keep the action for EA undefined. While the seconds, is the
exact equivalent but instead it leaves the action for data
undefined '*' and set the action for EA. These two expressions
follow the same principle: If both entries are saved (by
opposition to be marked as unchanged since the archive of
reference) in the archives, the most recent EA/Data is kept,
else, the one of the inode that is saved is kept, but if none is
saved in the archive the most recent entry (mtime/ctime) is kept.
-^, --slice-mode perm[:user[:group]]
defines the permission and ownership to use for created slices. By
default, dar creates slices with read and write available for anyone
letting the umask variable disable some privileges according to user's
preferences. If you need some more restricted permissions, you can
provide the permission as an octal value (thus beginning by a zero),
like 0600 to only grant read and write access to the user. Be careful
not to avoid dar writing to its own slices, if for example you provide
permission such as 0400. Note also that the umask is always applied
thus specifying -^ 0777 will not grant word wide read-write access
unless your umask is 0000.
-_, --retry-on-change count[:max-byte]
When a file has changed at the time it was read for backup, you can
ask dar to retry saving it again. By default a file can be re-saved up
to 3 times (this is the 'count' field), you can set it to zero to
disable this feature. In option the overall maximum amount of byte
allowed to be wasted due to retry changing file's backup can be given
after a colon character (:), this is the 'max-byte' field. By default
(no --retry-on-change option specified) a limit of 1 wasted byte is
allowed which is the mininum. Specifying zero for max-byte set no
limit on the amount of wasted bytes (same as if no 'max-byte' was
specified), each changing file is then saved up to 'count' times if
necessary.
A file is considered as changed when the last modification time has
changed between the time the file has been opened for backup and the
time it has been completely read. In some situation it is not possible
to replace the already saved data for a file (writing archive to a
pipe for example), in that situation only, a second copy of the file
is added just after the first previous try which leads that previous
try to becomes inaccessible, however it holds some place in the
archive, where from the designation of "wasted bytes". You can remove
all wasted bytes from an archive using the merging/filtering feature:
dar -+ new_arch -A old_arch -ak.
Note: since release 2.5.0, in normal condition no byte is wasted when
a file changed at the time it was read for backup, except when doing a
backup to pipe (using '-c -' option), except if the beginning of the
modified file is located in a previous slice and except if slice
hashing or strong encryption is used.
-ad, --alter=decremental
This flag is to be used only when merging two archives. Instead of the
usual merging where each files of both archives are added to the
resulting archive with eventually a tie using the overwriting policy
(see -/ option), here the merging builds an archive which corresponds
to the decremental backup done based on two full backups. the -A
backup is expected to receive the older archive while the -@ is
expected to point to the more recent one. If this option is used, the
eventually overwriting policy is ignored and replaced internally by -/
"{E&R&~R&(A|!H)}[S*] P* ; {(e&~e&r&~r)|(!e&!~e)}[*s] *p".
Additionally, files found in the newer archive that do not existed in
the older are replaced by a 'detruit' entry, which marks them to be
remove at restoration time. For more information about decremental
backups read the usage_notes.html file in the documentation. Note that
decremental backup is not compatible with delta binary.
-asecu, --alter=secu
This option disable the ctime check done by default during an
differential backup: If the ctime of an plain file has changed since
the archive of reference was done while all other values stay
unchanged (inode type, ownership, permission, last modification date),
dar issues a "SECURITY WARNING", as this may be the sign of the
presence of a rootkit. You should use the -asecu option to disable
this type of warning globally, if you are doing a differential backup
of a just restored data (a differential backup with the archive used
for restoration taken as reference). Effectively in that situation, as
it is not possible to restore ctime, the restored data's ctime will
have changed while other parameters will be unchanged for all restored
files, leading dar to issue a warning for all restored files. This
security check is disabled (implicitly) if dar is run with -ac option.
Last, if a file has only its EA changed since the archive of reference
was done (new EA, removed EA, modified EA), the security warning will
show (false positive).
-., --user-comment "<message>"
This option let the user add an arbitrary message into the archive
header. Warning! this message is always stored in clear text, even if
the archive is encrypted. You can see the message inserted in an
archive displaying the archive summary (dar -l <archive> -q). Some
macro can be used inside the <message>:
%c is replaced by the command line used. Note that for security, any
option related to archive encryption is removed (-K, -J, -$, -#,
-*, -%). The command included from a DCF file (see -B option) are
never added by this macro. As a consequence, if you do not want
to see --user-comment stored in user comments you can add the
--user-comment definition in an included file like ~/.darrc for
example.
%d this is the current date and time
%u this is the uid under which dar has been run
%g this is the gid under which dar has been run
%h the hostname on which the archive has been created
%% the % character.
-3, --hash <algo> With this option set, when creating, isolating, merging or repairing
an archive, beside each generated slices an on-fly hash file of the
slice is created using the specified algorithm. Available algorithm
are "md5", "sha1" and "sha512". By default no hash file is generated.
The hash file generated is named based on the name of the slice with
the .md5, .sha1 or .sha512 extension added to it at the end. These
hash files can be processes by md5sum, sha1sum and sha512sum usual
commands (md5sum -c <hash file>) to verify that the slice has not been
corrupted. Note that the result is different than generating the hash
file using md5sum or sha1sum once the slice is created, in particular
if the media is faulty: calling md5sum or sha1sum on the written slice
will make you compute the hash result on a possibly already corrupted
file, thus the corruption will not be seen when testing the file
against the hash at a later time. Note also that the creation of a
hash file is not available when producing the archive on a pipe ("dar
-c -").
-7, --sign email[,email[,...email]]
When creating, isolating, merging or repairing an archive with public
key encryption (read -K option) it is also possible to sign it with
one or more of your private key(s). At the difference of the hash
feature above, only the randomly generated key used to cipher the
archive, key that is dropped at the beginning and at the end of the
archive, is signed. If the archive is modified at some place, that
part will not be possible to decipher, but signature verification will
stay quick and valid, unless the part that has been tempered is the
key inside the archive in which case signature check will report a
failure and archive will not be readable at all. If the signature is
valid and the archive could be extracted without error, the whole
archive could be assumed to be signed by the gnupg key owners, but
read below the security note. See also GNUPGHOME in the ENVIRONMENT
section at the end of this document.
A summary information about the signature information is displayed
while listing an archive in summary mode "dar -l <archive> -q". For
any operation involving a signed archive, a short message only shows
if the archive is signed an one or more signature check failed, no
message is displayed in case of successful signature check. This
warning may be disabled using the --alter=blind-to-signatures command.
-<, --backup-hook-include <mask>
The mask is applied to path+filename during backup operation only. If
a given file matches the mask, a user command (see -= option below)
will be run before proceeding to the backup and once the backup will
be completed. See also -> option below. IMPORTANT: if using the short
option, you need to enclose it between quotes: '-<' for the shell not
to interpret the < as a redirection.
-> --backup-hook-exclude <mask>
The mask is applied to path+filename during backup operation only. If
a given file matches the mask, even if it matches a mask given after
-< option, no user command will be executed before and after its
backup. The -< and -> options act like -g and -P, they can receive
wildcard expression and thus have their comportment driven by the
--alter=globe and --alter=regex expressions seen above, as well as the
--alter=mask option. Last the --alter=case and --alter=no-case modify
also the way case sensitivity is considered for these masks. By
default, no -> or -< option, no file get selected for backup hook.
IMPORTANT: if using the short option, you need to enclose it between
quotes: '->' for the shell not to interpret the > as a redirection.
-=, --backup-hook-execute <string>
for files covered by the mask provided thanks to the -< and ->
options, the given string is executed before the backup of that file
starts and once it has completed. Several macro can be used that are
substituted at run time:
%% will be replaced by a literal %
%p will be replaced by the full path under backup
%f will be replaced by the filename (without the path)
%u will be replaced by the UID of the file
%g will be replaced by the GID of the file
%t will be replaced by a letter corresponding to the type of
inode: 'f' for plain file, 'l' for symlink, 'd' for
directory, 'c' for char devices, 'b' for block devices, 's'
for sockets, 'p' for pipes, 'o' for doors.
%c and most interesting, %c (c for context), will be replaced
by "start" or by "end" when the command is executed before
or after the backup respectively.
This way, one can dump a database in a directory just before it is about to be backed up,
and clean it up once the backup has completed. Note that the masks seen above that drive
the execution of this command can be applied to a directory or a plain file for example.
When a directory is selected for this feature, the command is logically ran before
starting (with the context "start") to backup any file located in that directory or in a
subdirectory of it, and once all files in that directory or subdirectories have been
saved, the command is ran a second time (with the context "end"). During that time, if any
file do match the backup-hook masks, no command will be executed for these. It is assumed
that when a directory has been asked for a backup-hook to be executed this hook (or user
command) is prepare for backup all data located in that directory. The environment
variable DAR_DUC_PATH also applies to these user commands (see -E above, or the
ENVIRONMENT paragraph below).
-ai, --alter=ignore-unknown-inode-type
When dar meets an inode type it is not aware about (some times ago, it
was the case for Door inode on Solaris for example, Door inodes are
handled by dar since release 2.4.0), it issues a warning about its
inability to handle such inode. This warning occurs even if that entry
is filtered out by mean of -X, -I, -P, -g, -[ or -] options, as soon
as some other entry in that same directory has to be considered for
backup, leading dar to read that directory contents and failing on
that unknown inode type (filtering is done based on the result of
directory listing). This option is to avoid dar issuing such warning
in that situation.
-8, --delta sig This option can be used for archive backup, isolation and merging.
Important: read also the best practice paragraph below
Called during a backup operation it leads dar to create delta
signature for each file: If the file is new or has changed, a
signature is computed and stored beside the file's data, which
increases the archive size. If the file is not new and has not changed
(differential backup context) if an delta signature is found in the
archive of reference (or isolated catalogue), this signature is copied
to the resulting archive, but not the file's data. If the reference
archive does not hold delta signature, a new delta signature is
computed based on the current data found on filesystem for that file
and then stored in the resulting archive. But in any case, without
--delta sig the resulting archive will hold no delta signature. Note
that delta signature transfer is not possible when the archive of
reference is read in sequential mode (still here for backup
operation), thus delta signature is disabled when the archive of
reference is read in sequential mode.
For isolation and merging operations, the behavior is slightly
different: --delta sig option let dar transfer existing delta
signatures from the original archive to the isolated/merged one but
does not lead dar to compute delta signatures for files that do not
have one, unless one of the --include-delta-sig or --exclude-delta-sig
option is specified; in that case the delta signatures are
transfered/dropped and if not present calculated accordingly to these
mask options. However note that it is not possible to calculate delta
signature for unsaved files in the archive of reference (because the
archive of reference does not hold their data) as well as for fully
saved files when merging is performed keeping files compressed (see
-ak option). Another restriction while merging concernes sparse files,
it is not possible to calculate binary signature for file stored as
sparse files, but if sparse file detection mechanism is activated at
merging time, delta signature can be calculated for sparse files too
even if it is missing in the reference archive. In short: if you want
recalculation of delta signature while merging, do not keep file
compressed (do not use -ak option) and if you want to avoid having
sparse files excluded from the delta signature recalcutation, activate
sparse file detection (use -ah option). Delta signature transfer is
not possible for on-fly isolation, you need to do normal archive
isolation to obtain an isolated catalogue with delta signatures.
-8, --delta sig:<function>:<multiplier>[:<divisor>[:<min>[:<max>]]]
this variant of '--delta sig' option let you specify the block length
used to build delta signatures. Larger values reduce CPU load required
to build delta signature, but also lead to less accuracy when
computing delta binary, which means larger delta patch and more data
saved when a file has changed. The block len is calculated following
the formula: block_len = function(filesize)*multiplier/divisor If this
calculated value is lower than "min", it is set to min. If the
calculated value is greater than "max" it is set to max unless max is
set to zero in which case the value is kept as is. Of course "divisor"
cannot be null. The available functions are:
fixed
always returns 1, in other terms, the block size is independent
from the file size to build delta signature for
linear
returns the filesize. here, you will most of the time use 1 for
multiplier and increase divisor to at least 10 for it makes sense
log2 returns the upper rounded power of 2 closest to the file size
(base 2 logarithm).
square2
returns the approximated value of the square root of the file
size. Note that for better performance and as accuracy is not
important here, this function is implemented as
exp2(log2(filesize)/2) where exp2 and log2 are based on the
integer left and right bit shift operations.
square3
returns the approximated value of the cube root of filesize,
implemented as exp2(log2(filesize)/3)
All numerical fields can receive multiplier suffix (k, M, ...) for more details
about these suffixes, see -s option description. If not specified, "max" defaults
to zero (no maximum value defined). If not specified "min" defaults to
RS_DEFAULT_BLOCK_LEN (see below for details on this symbol). If not specified
"divisor" defaults to 1. Using "--delta sig" without additional fields is
equivalent to using --delta sig:fixed:RS_DEFAULT_BLOCK_LEN up to dar/libdar version
2.7.10. Starting release 2.7.11, the default is equivalent to use --delta
sig:square2:1:1:RS_DEFAULT_BLOCK_LEN:128k , which is _almost_ what is used by rsync
command line tool (rsync use rather 700 bytes as minimum block size), where
"RS_DEFAULT_BLOCK_LEN" is taken from librsync and is today equal to 2048 bytes
(which may well change in the future by the way if librsync maintainers decide to
do so).
-{, --include-delta-sig <mask>
By default when --delta sig is provided, delta signatures are computed
for all files enrolled in the backup operation (see also --delta-sig-
min-size option). This option and --exclude-delta-sig allow
restricting the files for which delta signature have to be calculated
in that situation. The mask applies to the whole path, the same way as
-P/-g options do.
For merging or isolation operations, when --delta sig is used no delta
signature is computed only existing ones are transferred as is without
restriction. To change that behavior and thus either drop or add delta
signature to files that did not have one in the archive of reference,
specify an combination of --include-delta-sig or --exclude-delta-sig
with --delta sig. This option as well as --exclude-delta-sig can be
used several times on command-line but are useless/ignored without
--delta sig. See also -am, -ag and -ar options.
-}, --exclude-delta-sig <mask>
Files matching the given mask will never have their delta signatures
calculated, may --delta sig option be specified or not. See also
--include-delta-sig option above and --delta-sig-min-size below.
-6, --delta-sig-min-size <number>
For archive merging, isolation and creation, when dar has to
(re-)calculate delta signatures, this option modifies the minimum file
size (in bytes) below which dar never calculates delta signatures.
This option acts independently from --include-delta-sig and --exclude-
delta-sig , however it cannot re-activate delta signature
recalculation by itself while merging/isolating an archive, it
requires either --exclude-delta-sig or --include-delta-sig option to
be active in that situation. For archive backup instead, it does not
require --exclude-delta-sig nor --include-delta-sig to act, but only
need --delta sig option to be set. By default, this minimum size is 10
kio. The same option suffixes (k for kilo, M for mega, G for giga, T,
...) as the ones available with --slice option can be used here too.
Using zero as argument gives the same result as not specifying this
option at all (default size).
-8, --delta no-patch
In the context of differential backup, this option leads dar to never
consider files for delta binary even if delta signatures are present.
By default delta binary (rsync-like) operation is performed when a
file has changed since the archive of reference was made *and* if a
delta signature could be found in the archive of reference for that
file (or in the isolated catalogue used as reference for the
incremental/differential backup). If no delta signature could be found
or if --delta no-patch is used, the normal behavior is done, which
consist of saving that whole file in the archive. Note that if the
archive of reference is read in sequential mode, the --delta no patch
is required, dar will refuse to execute the operation: sequential read
and binary delta are not compatible, because reading in sequential
mode an archive does not let skipping backward to fetch the delta
signature necessary to setup a delta patch.
Binary delta options usage and best practices:
First it must be understood that binary delta has advantages (less storage
requirement) and drawbacks: data corruption has a wider impact on the ability to
restore a given file, restoration of incrementally backed up file may ask much more
than one archive to be used. To limit the impact of the first drawback, dar binary
delta is done per file, not globally on the total amount of saved data. You are
also strongly encouraged to protect your backups with parity data using par2 (see
dar_par.dcf file in the examples section of the documentation). Adding par2 data
will increase storage requirement by a little, but usually much less than the
amount gained using binary delta. Last drawback, binary delta relies on checksum
(contained in the delta signature) and not on the real data to build the binary
delta. There is chances that two different files provide the same checksum, even if
the chances are very low, probability is not null. The consequence is that using
binary delta the risk exists that the restored data do not match the original data
and this will not be noticed by the librsync library on which libdar relies for
that feature. Dar adds a second level of checksum, to detect data corruption inside
the archive and to check that the file the delta patch is about to be applied is
the expected base file, this reduces the risk of "collision" but does not remove it
completely. After these warnings, let's now see the best practices about binary
delta:
Once a full backup has been done using --delta sig, any differential backup made
based on this archive will use binary diff for file having a delta signature
present in the full backup. If you always make differential (not incremental)
backups based on such full backup you have nothing more specific to do in regard to
binary delta, dar will handle it transparently. In particular you do not need to
invoke --delta sig at subsequent backup, this saves space in differential archives
as well as CPU cycles.
However, When doing incremental (not differential) backups this time, if you want
to have dar using binary delta at each subsequent incremental backup, delta
signatures must be present in the successive incremental backups. This is done by
using --delta sig option for each new incremental backup created.
If you were used to use isolated catalogues before release 2.6.0 you can add
--delta sig option while isolating a catalogue from an archive containing delta
signatures. Such isolated catalogue will be much larger than what it can be without
this option but it can be used as reference for a new differential/incremental
backup letting dar relying on binary delta. Isolated catalogue generated without
--delta sig do not contain delta signature and cannot lead to binary delta
operation when used as reference for an incremental or decremental backup.
Another way of doing differential backup is to make a normal full backup without
--delta sig option, and only add delta signatures at archive isolation time using
--delta sig --include-delta-sig "*" options. Binary delta signature will then be
calculated based on the saved files. Then, using the resulting isolated catalogue
as reference dar will be able to proceed to binary delta for the differential
backup. If this works pretty well for differential backup (or the first incremental
backup) which is based on a full backup, for incremental backup this is less
adapted as a file that has not changed since the archive of reference was made does
not hold any data and calculating the delta signature is not possible. The first
method explained two paragraphs above is better as the incremental backup fetches
the already calculated delta signature from the reference to keep it in the
resulting incremental backup, so even without data, binary delta is still possible.
Isolated catalogue using the --delta sig option, can still be used as backup of the
internal catalogue they have been isolated from. However, as they hold their own
delta signatures, such isolated catalogue can only have access to its own ones, not
to those of the archive of reference. In particular when testing an archive (-t
option), using -A option to rescue the archive internal catalogue using an isolated
catalogue containing delta signatures, dar will not be able to check that there is
no corruption in the delta signatures fields of the archive under test. For that
type of testing either use the internal catalogue of the archive or rescue it using
an isolated catalogue built without --delta sig option.
-az, --alter=zeroing-negative-dates
dar/libdar saves dates as a number of seconds since the beginning of
year 1970, the well known "Unix time" (plus a positive fraction for
sub-second time-stamping). Some systems may return a negative number
as the Unix time of a given file (files having dates before 1970), in
that situation by default and since release 2.5.12 dar pauses and asks
the user whether to assume the date as being zero. But with -az
option, dar/libdar automatically assumes such negative dates to be
zero and just issue a warning about the problem met.
-\, --ignored-as-symlink <absolute path>[:<absolute path>[:...]]
When dar reaches an inode which is part of this provided colon-
separated list, if this inode is not a symlink this option has no
effect, but if it is a symlinks dar saves the file the symlink points
to and not the symlink itself as dar does by default. In particular,
if the pointed to inode is a directory dar recurses in that directory.
You can also pass this list as argument to the DAR_IGNORED_AS_SYMLINK
environment instead of using --ignored-as-symlink (which takes
precedence over the environment variable).
-'\'', --modified-data-detection=any-inode-change, --modified-data-detection=mtime-and-
size
Before release 2.6.0, during a differential/incremental backup if any
part of a file's inode metadata changed (ownership, permission, ...)
even if the mtime (last modification time) and file size stood the
same, dar had no choice than resaving the whole file for backup to
record the metadata changes. This lead to a waste of backup time and
space if in fact and for example only the ownership had been modified.
You can still keep this historical behavior by invoking the
--modified-data-detection=any-inode-change option. Since release
2.6.0 a new entry status ("inode-only") has been added. Dar can now
re-save only metadata when the inode change does not concern the data.
To know whether the data has changed or not, by default (no
--modified-data-detection option given) dar looks at mtime and at
file's size only. Specifying --modified-data-detection=mtime-and-size
(which is the default behavior) can be used to revert the action of
--modified-data-detection=any-inode-change for example when playing
with included files (DCF files): the latest met takes precedence.
-T, --kdf-param <integer>[:<hash algo>]
At the difference of the listing context (see below), in the context
of archive creation, merging and isolation, -T option let you define
the iteration count used to derive the archive key from the passphrase
you provided (archive encryption context) and the hash algorithm used
for that derivation. -T has another older meaning when doing archive
listing, but due to the lack of free character to create a new CLI
option, there was no other choice than recycling an existing option
not used in the context of archive creation/merging/isolation. The
consequence is that the -T option must appear after the -+/-c/-C
options for the operational context to be known at the time the -T
option is met and its --kdf-param meaning to be taken into account. As
--kdf-param is an alias to -T, this long form of this option must also
be found after the use of either -c, -C or -+ option.
Without --kdf-param the KDF fonction uses 200,000 iterations for md5, sha1 and
sha512 (PBKDF2 from PKCS#5 v2) but only 10,000 for argon2. If libargon2 is present,
this is the default hash algorithm, else sha1 is used with PBKDF2. Valid parameters
are "sha1", "sha512", "md5" and "argon2" for the hash algorithms and a value
greater than 1 for the iteration count. However it is advise to use a value equal
or greater to the default values mentionned previously. The suffixes described for
-s option are also available here (k, M, G, T, P, ...) however pay attention to the
-aSI/-abinary mode which default to binary, in which case "-T 1k" is equivalent to
"-T 1024". Example of use: --kdf-param 20k:argon2
RESTORATION SPECIFIC OPTIONS (to use with -x)
-k[{ignored|only}], --deleted[={ignore|only}]
Without argument or with the "ignore" argument, this option leads dar
at restoration time to not delete files that have been deleted since
the backup of reference (file overwriting can still occur). By
default, files that have been destroyed since the backup of reference
are deleted during restoration, but a warning is issued before
proceeding, except if -w is used. If -n is used, no file will be
deleted (nor overwritten), thus -k is useless when using -n. If -/
option is used, this option without argument is ignored! With the
"only" argument, this option only consider files marked as to be
removed in the archive to restore, no file are restored but some file
are removed. When -konly (or --deleted=only) is used, the -/ option is
ignored (at the opposition of the "--deleted=ignore" option which is
ignored when the -/ is used). Of course "--deleted=ignore" and
"--deleted=only" are mutually exclusive, because if both of them were
available at the same time dar would do nothing at all.
-r, --recent only restore files that are absent or more recent than those present
in filesystem. If -/ option is used, this option is ignored!
-f, --flat do not restore directory structure. All files will be restored in the
directory given to -R, if two files of the same name have to be
restored, the usual scheme for warning (-w option) and overwriting (-n
option) is used. No rename scheme is planned actually. When this
option is set, dar does not remove files that have been stored as
deleted since last backup. (-f implicitly implies -k).
-ae, --alter=erase_ea
[DEPRECATED use -/ instead] Drop all existing EA of files present in
filesystem that will have to be restored. This way, the restored files
will have the exact set of EA they had at the time of the backup. If
this option is not given, a file to restore will have its EA
overwritten by those present in the backup and if some extra EAs are
present they will remain untouched. See the Note concerning Extended
Attributes (EA) above for a detailed explanation about this behavior.
If -/ option is used, this option is ignored!
-D, --empty-dir At restoration time, if -D is not specified (default) any file and
directory is restored in regard to the filtering mechanism specified
(see -I, -X, -P, -g, -[ and -] options). But if -D option is provided
the restoration skips directory trees that do not contain saved files.
This avoid having a huge empty tree with a few restored files
especially when restoring a differential archive in an empty place.
Note: This feature cannot work when --sequential-read is used, as it
is not possible to know whether a directory contains or not some saved
files at the time the directory inode is read from the archive in
sequential reading mode.
-2, --dirty-behavior { ignore | no-warn }
At restoration time, if a file in the archive is flagged as "dirty"
(meaning that it had changed at the time it was saved), user is asked
for confirmation before restoring it. Specifying "ignore" will skip
those dirty files, while "no-warn" will restore them without user
confirmation. This feature is incompatible with sequential reading
mode, in this mode dar cannot know whether a file is dirty before
having restored it. In consequences, in --sequential-read, once a file
has been restored, if it is found to be dirty it will be removed
unless dirty-behavior is set to "no-warn".
-/, --overwriting-policy <policy>
Overwriting policy can be used for archive restoration to define when
and how file overwriting can occur. See above the description of this
option.
-A, --ref [[<URL>]<path>]/<basename>
The --ref option can be used with an isolated catalogue to rescue an
archive that has a corruption in the catalogue part, see GENERAL
OPTIONS above for more details.
-au, --alter=unix-sockets
Do not restore unix-sockets. By default saved unix sockets are
recreated at restoration time.
-ap, --alter=place Since version 2.7.1 libdar stores the filesystem root path (given -R
option) used when creating a backup, this is the known as the 'in-
place' path. At restoration time by default, dar uses the provided -R
option or if not specified uses the current directory as root
directory for the restoration operation. Using -ap option lead dar to
read the in-place path from the backup and restore the data using this
path instead. This option is thus exclusive with -R option and may
lead dar to report an error if the archive has not stored any in-place
path (older archive format or backup resulting of the merging of two
backups having different in-place path).
TESTING AND DIFFERENCE SPECIFIC OPTIONS (to use with -t or -d)
-ado-not-compare-symlink-mtime, --alter=do-not-compare-symlink-mtime
With this option set, when comparing a symlink, no message shows when
symlink in archive and symlink on filesystem do only differ by their
mtime. See also -O option.
-ap, --alter=place is also available as described just above for restoration options.
No other specific option, but all general options are available except for example -w
which is useless, as testing and comparing only read data. -A option is available as
described in GENERAL OPTIONS to backup of internal catalogue of the archive (assuming you
have a previously isolated catalogue available).
Doing a difference in sequential read mode is possible but hard linked inodes can only be
compared to the filesystem the first time they are met, next hard links to this same inode
cannot obtain the corresponding data because skipping backward in sequential read mode is
forbidden. In that situation, the hard links are reported as skipped, meaning that data
comparison could not be performed.
LISTING OPTIONS (to use with -l)
-T, --list-format=<normal | tree | xml | slicing>
By default, listing provides a tar-like output (the 'normal' output).
You can however get a tree-like output, an XML structured output or an
output focusing on slice(s) where each file's data, EA and FSA is
located in. The option --tree-format is an alias to --list-format=tree
(backward compatibility). Note that the files doc/dar-catalog-*.dtd
define the format of the XML output listing (This file is also
installed under $PREFIX/share/doc)
the -Tslicing option can also be used with isolated catalogue
generated with dar 2.5.0 or above, as isolated catalogues now contain
a copy of the slicing layout of the archive of reference. However, if
the archive of reference has been re-sliced (using dar_xform) after
the isolated catalogue has been built, the slicing information would
not be correct. For that corner case, you can use the -s and -S
options with -Tslicing to specify what are the new slice sizes of the
archive of reference. Last, -Tslicing and --sequential-read options
are not compatible except for isolated catalogues.
-as, --alter=saved list only saved files
-alist-ea, --alter=list-ea
list Extended Attributes name for each file that has some.
-ay, --alter=byte, --alter=bytes
by default files size is displayed to occupy the shortest number of
characters by using the largest unit possible (KiB, MiB, GiB, and so
on). With this option instead, the size is displayed with maximum
precision using the exact number of bytes used for each file.
-I, -X, -P, -g, -[, -]
can be used to filter file to list base on their name or path.
-aheader displays the header (when --sequential-read is used) or the trailer of
the archive and then stops. This archive header/trailer is always in
clear text even when the archive is ciphered. This option is here to
let you access to these fields without providing the encryption key.
From the general options it seems only -vm and -b stay useful here. Note that -vm displays
an archive summary first, where a detailed of information about the archive can be
obtained. If you want to display only this summary use -q with -l option.
displayed fields
[Data] possible values are [ ] or [Saved] or [InRef] or [DIRTY] or
[Inode] or [Delta]. [ ] means that the data has not been saved
because there is no change since backup of reference. [Saved] means
that the data has been saved completely, and thus this archive is able
to restore the file without other help. [InRef] was used in archive
generated by dar version 2.3.x and before when isolating a catalogue
from an archive, and means that the file was saved in the reference
archive. [DIRTY] means that data is saved (like [Saved]) but has
changed at the time dar was reading it for backup, leading dar to
possibly store the file in a state it never had. [Inode] means only
permission ownership and ctime data changed since the archive of
reference was done is recorded in the archive, the data did not
changed according to the --comparison-field set or not set. Last
[Delta] means the file's data is saved as a binary delta (or delta
patch), which is much shorter than the full data as what is done with
[Saved]. It also means that you can only restore the file if it exists
on filesystem in the state it had when the archive of reference was
done, for the patch to be possible to apply on it. This is the case
for example if you just restored this file from the archive of
reference.
[D] possible values are [-], [ ] or [D]. [D] means that delta signature
associate with this file is present in the archive. [ ] means that the
file has no associated delta signature and thus binary diff will not
be possible for it. [-] is used for non plain files inodes for which
delta signature is not applicable.
[EA] possible values are " " (empty string) or [ ] or [InRef], [Saved]
or [Suppr]. It Shows whether Extended Attributes are present and saved
([Saved]), are present but not saved ([ ]) which means there is no
change since backup of reference, if there is no EA saved for this
file (empty string) or if some EA were present in the archive of
reference but none is currently available ([Suppr]). [InRef] was used
when isolating a catalogue (release 2.3.x and before) from an archive
and means that the file was saved in the reference archive.
[FSA] Each character represent a FSA Family:
"L" is the first character (L/l/-) representing ext2/3/4 FSA family
"H" is the second character (H/h/-) representing HFS+ FSA family
"-" the third character is reserved for future FSA family and is
always a dash for now.
Uppercase means the FSA set is saved, lowercase means the FSA is
present in the archive of reference and has not changed since that
time. Last a dash (-) means no FSA of that family has been saved for
that file.
[compr] possible values are [....%] or [-----] or [ ] or [worse]. Shows if
the file has been compressed ([...%]) and the compression ratio
reached "(uncompressed-compressed)/uncompressed", for example [ 33%]
means that the compressed data uses only 66% of the space required to
store uncompressed data (33% of space saved thanks to compression), or
if the file is stored without compression ([ ] see -m, -Y and -Z
options) or if the file is not subject to compression because it is
not a saved regular file ([----]), or if the file takes more space
compressed than its original size ([worse]), due to compression
overhead. Note that 1% compression ratio brings quite no data
reduction, while obviously 98% is a very performant compression
(compressed file takes only 2% of the size required by the
uncompressed date).
[S] possible values are [ ] or [X]. [X] only applies to saved plain files,
and tells that the file is stored using sparse file data structure:
not all data is stored, long sequence of zeros are skipped. This also
means that at restoration time, if the filesystem supports it, holes
will be restored. To store hole information libdar uses escape
sequence (special sequence of byte), but to avoid real data to be
considered as such escape sequence, a special escape sequence is used
when data looks like an escape sequence. So if a data contains a such
escape sequence, it must be read as if it contains holes to be able to
restore back the data in its original form. For that reason, in some
rare circumstances (saving an dar archive inside a dar archive without
compression or encryption, for example) a file without hole may be
marked [X] as if it had holes and will be longer by on byte for each
data sequence looking like an escape sequence.
permission
see ls man page. Note that a star (*) is prepended to the permission
string if the corresponding inode is linked several times to the
directory structure (hard link).
user owner of the file
group group owner of the file
size size in byte of the file (if compression is enabled, the real size in
the archive is "compression rate" time smaller).
date the last modification date of the file. The last access time is also
saved and restored, but not displayed.
filename The name of the file.
Extended Attributes
When using -alist-ea option, for hard linked inode, the filename is
followed by an integer between braces: Entries with the same number do
point the the same inode.
Slice(s) In -Tslice mode, each file is given the range of slices it is located
in. If slice size is chosen particularly small, some slices may
contain no file, EA, FSA data but only tape marks or the internal
catalogue, leading the aggregation of reported slices not to cover all
available slices of the archive.
EXPLICIT OPTIONAL ARGUMENTS
When dar has not been compiled with GNU getopt, which is not present by default on some
systems like FreeBSD, you may lack the optional arguments syntax. For example "-z" will
create a parse error on command-line, or in -B configuration files. The solution is to
explicitly give the argument. Here follows a list of explicit argument to use in place of
optional ones:
-z must be replaced by -z 9
-w must be replaced by -w d or -w default
-H must be replaced by -H 1
-0 must be replaced by -0 ref
-5 must be replaced by -5 ""
-p must be replaced by -p 1
-v must be replaced by -v all
-k must be replaced by -k ignore
-5 must be replaced by -5 user.libdar_no_backup
-M must be replaced by -M I:/
important ! When using GNU getopt(), optional arguments are available by sticking the
argument to the short option: "-z" for example is available as well as "-z9". But "-z 9"
is wrong, it will be read as "-z" option and "9", a command line argument (not an argument
to the -z option). In the other side, when using a non GNU getopt this time, "-z" becomes
an option that always requires an argument, and thus "-z 9" is read as "-z" option with
"9" as argument, while "-z9" will be rejected as a unknown option, and "-z" alone will
generate an error as no argument is provided. In consequences, you need a space between
the option (like "-z") and its argument (like "9"), when dar does not rely on a GNU
getopt() call, which also imply you to explicitly use arguments to options listed just
above.
EXIT CODES
dar exits with the following code:
0 Operation successful.
1 Syntax error on command-line or DCF included file
2 Error due to a hardware problem or a lack of memory.
3 Detection of a condition that should never happen, and which is considered as a
bug of the application.
4 Code issued when the user has aborted the program answering a question from dar.
This also happens when dar is not run from a terminal (for example launched from
crontab) and dar has a question to the user. In that case, dar aborts the same
way as if the user pressed the escape key at the question prompt.
5 is returned when an error concerning the treated data has been detected. While
saving, this is the case when a file could not be opened or read. While
restoring, it is the case when a file could not be created or replaced. While
comparing, it is the case when a file in the archive does not match the one in
the filesystem. While testing, it is the case when a file is corrupted in the
archive.
6 an error occurred while executing user command (given with -E or -F option).
Mainly because the creation of a new process is not possible (process table is
full) or the user command returned an error code (exit status different from
zero).
7 an error has occurred when calling a libdar routine. This means the caller (dar
program), did not respect the specification of the API (and this can be
considered as a particular case of bug).
8 the version of dar used is based on finite length integers (it has been compiled
with the option --enable-mode=...). This code is returned when an integer
overflow occurred. use the full version (based in the so called "infinint"
class) to avoid this error.
9 this code indicates an unknown error. The exception caching code to take care of
new exceptions has probably been forgotten to be update ... this is a minor bug
you are welcome to report.
10 you have tried to use a feature that has been disabled at compilation time.
11 some saved files have changed while dar was reading them, this may lead the data
saved for this file not correspond to a valid state for this file. For example,
if the beginning and the end of the file have been modified at the same time
(while dar is reading it), only the change at the end will be saved (the
beginning has already been read), the resulting state of the file as recorded by
dar has never existed and may cause problem to the application using it. This is
known as a "dirty" file in the archive.
SIGNALS
If dar receives a signal (see kill(2) man page) it will take the default behavior which
most of the time will abruptly abort the program, except for the following signals:
SIGINT This signal is generated by the terminal when hitting CTRL-C (with the
terminal's default settings), it can also be generated with the kill command
SIGTERM This signal is generated by the system when changing of run-level in particular
when doing a shutdown, it can also be generated with the kill command
SIGHUP Depending on the system, this signal may be sent before the SIGTERM signal at
shutdown time, it can also be generated with the kill command
SIGQUIT This signal is generated by the terminal when hitting CTRL-\ (with the
terminal's default settings), it can also be generated with the kill command
SIGUSR1 This signal can be generated by the kill command
SIGUSR2 This signal can be generated by the kill command
For those previous signals, two behavior exit. For SIGHUP, SIGINT, SIGQUIT, SIGTERM and
SIGUSR1, a delayed termination is done: the backup or isolation operation is stopped, the
catalogue is appended to the archive and the archive is properly completed with the
correct terminator string, this way the generated archive is usable, and can be used as
reference for a differential backup at a later time. Note that if an on-fly isolation had
been asked, it will *not* be performed, and no user command will be launched even if dar
has been configured for (-E option). For SIGUSR2 instead a fast termination is done: in
case of backup or isolation, the archive is not completed at all, only memory and mutex
are released properly.
For both type of termination and other operations than backup or isolation, dar's behavior
is the same: For restoration, all opened directories are closed and permissions are set
back to their original values (if they had to be changed for restoration). For listing,
comparison, testing, the program aborts immediately.
Another point, when using one of the previous signals, dar will return with the exist
status 4 meaning that the user has aborted the operation. Note that answering "no" to a
question from dar may also lead dar to exit this way. last, If before the end of the
program the same signal is received a second time, dar will abort immediately.
FILES
$HOME/.darrc and /etc/darrc if present are read for configuration option. They share the
same syntax as file given to -B option. If $HOME/.darrc is not present and only in that
case, /etc/darrc is consulted. You can still launch /etc/darrc from .darrc using a
statement like -B /etc/darrc. None of these file need to be present, but if they are they
are parsed AFTER any option on the command line and AFTER included files from the command
line (files given to the -B option). NOTE: if $HOME is not defined $HOME/.darrc default to
/.darrc (at the root of the filesystem).
Else you can see conditional syntax below, and -N option above that leads dar to ignore
the /etc/darrc and $HOME/.darrc files.
CONDITIONAL SYNTAX
configuration files (-B option, $HOME/.darrc and /etc/darrc) usually contain a simple list
of command-line arguments, split or not over several lines, and eventually mixed with
comments (see -B option for more). But, you can also use make-like targets to ask for a
particular set of commands to be used in certain conditions.
A condition takes the form of reserved word immediately followed by a colon ':'. This word
+ colon must stand alone on its line, eventually with spaces or tabs beside it. The
available conditions are:
extract: all options listed after this condition get used if previously on
command line or file the -x command has been used
create: all options listed after this condition get used if previously on
command line or file (-B option) the -c command has been used
list: (or listing:) if -l command has been used
test: if -t command has been used
diff: if -d command has been used
isolate: if -C command has been used
merge: if -+ command has been used
repair: if -y command has been used
reference: if -A option has been used (except when -A is used for the snapshot
feature or in conjunction with -af)
auxiliary: if -@ option has been used
all: in any case
default: if no -c, -d, -x, -t, -C, -l or -+ option has been used at this point
of the parsing.
The condition stops when the next condition starts, or at End of File. The commands
inserted before any condition are equivalent to those inserted after the "all:" condition.
Remark : -c -d -x -t -C and -l are mutual exclusive, only one of them can be used while
calling dar.
Here is an example of conditional syntax
create:
# upon creation exclude the
# following files from compression
-Z "*.mp3" -Z "*.mpg"
all:
-b
-p
default:
# this will get read if not
# command has been set yet
-V
# thus by default dar shows its version
all:
-v
# for any command we also ask to be verbose
# this is added to the previous all: condition
Last point, you may have several time the same condition (several all: ) for example. They
will be concatenated together.
USER TARGETS
User targets are arbitrary words found on command line, that do not start by a dash ('-').
On most system they should be placed after command and options. They are collected from
command-line first, then comes the parsing of command and optional arguments. Their use is
to extend conditional syntax described just above by having a set of options activated by
the user just adding a single word on command-line. Of course user targets must not be
equal to one of the reserved words of the conditional syntax (extract, create, ... all,
default). A valid target is a word (thus without space) composed of lowercase or uppercase
letters (case is sensitive) with eventually digits, dashes '-' or underscores '_'
characters.
Let's see an example of use:
first a DCF file named 'example.dcf' that will be given on command line:
# normal set of files considered for backup
create:
-R /
-P proc
-P sys
-P mnt
-D
# if the "home" user target is applied on command line the following command get
added
home:
-g home
# if the "verbose" user target is used, we will have some more verbosity ...
verbose:
-v
-vs
Then we could run dar in the following ways:
dar -c test -B example.dcf
in that case only the command in the "create:" section of example.dcf
would be used.
dar -c test -B example.dcf verbose
here over the "create:" target the commands under the "verbose:"
target (-v and -vs) would be also used
dar -c test -B example.dcf verbose home
last we use two user targets "verbose:" and "home:" in addition the
the "create:" target of the usual conditional syntax.
Note that if the last option *may* receive an argument, the first user target that follows
it will be assumed an argument to that option. To avoid this, either change the order of
options on command line for the last option been an option that never or always uses an
argument (for example -b never has an argument while -s always has one). Or separate the
options from the user targets by the -- word. And of course you can also use the explicit
argument of the last option (see EXPLICIT OPTIONAL ARGUMENT section, above).
Second point: It is allowed to have user targets inside a DCF file. Note however that
targets are collected in a first phase, which leads some part of the file to be hidden
(because the corresponding conditional syntax or user target is not present). Then, the
remaining part of the file is then parsed and actions for each option found is taken. At
that time, new user targets found are just recorded, but they do not modify the current
DCF file layout, in particular, hidden part of the file stay hidden even if the
corresponding user target is read in this same file. Next DCF parsing (which may be
triggered by a second -B option on the command line, or by a -B option inside the current
parsed DCF file) will thus be done with the additional targets found in that first DCF
file, so in a way you may have user targets that activate other user targets, but they
will be activated in starting the next -B file. Here follows an examples of two DCF files,
first.dcf and second.dcf:
# cat first.dcf
target3:
-K toto
target1:
target2
-B second.dcf
target3
target2:
#never reached
-s 10k
# cat second.dcf
target2:
-v
target3:
-b
In that example, target1 activates both target2 and target3, but at the time of the
parsing of first.dcf, neither target2 nor target3 were yet activated thus '-K toto' and
'-s 10k' will never be given to dar (unless activated beside target1 before first.dcf get
parsed), however when comes the time to parse second.dcf, target2 *and* target3 are
activated, thus both '-v' and '-b' will be passed to dar, even if 'target3' is located
after '-B second.dcf' in the file first.dcf
ENVIRONMENT
DAR_DCF_PATH
if set, dar looks for Dar Configuration File (DCF files, see -B option) that do
not have an fully qualified path in the directories listed in DAR_DCF_PATH
environment variable. This variable receives a colon (:) separated list of paths
and look in each of them in turn, up to the first file found under the requested
name.
DAR_DUC_PATH
if set, dar looks for Dar User Command (DUC files, see -E, -F, -~, -= options)
that do not have a fully qualified path in the directories listed in
DAR_DUC_PATH. This variable receives a colon (:) separated list of paths and
looks in each of them in turn, up to the first file found under the requested
name.
DAR_SFTP_KNOWNHOSTS_FILE
if set, dar will not use the $HOME/.ssh/known_hosts file to check sftp remote
server authenticity but the file given as value for this environment variable.
Note that setting this variable to an empty string completely disable host
validation, which is not recommended. Dar, the command line interface program
for disk archive relies on libdar for archive format management which relies on
libcurl for network transfer which in turn relies on libssh2 for all that
concerns ssh/sftp protocol. In the known_hosts file, libssh2 does not support
recent lines like those with "ecdsa-sha2-nistp256" in second argument before its
release 1.9.0 (you will also need curl/libcurl 7.69.1 or more recent), in these
old versions you only have support for "ssh-rsa" lines. Check libssh2 and
libcurl documentations and literature for more details about that limitation.
The workaround, if you have not yet libssh2 1.9.0 or more recent, is to disable
known hosts validation or set up a restricted known hosts file without any
"ecdsa*" entry and have DAR_SFTP_KNOWNHOSTS_FILE pointing to it.
DAR_SFTP_PUBLIC_KEYFILE
by default dar will fetch the public key file in $HOME/.ssh/id_rsa.pub file. If
you use the former id_dsa.pub or more recent key types you need to set this
environment variable to point to the appropriated filename
DAR_SFTP_PRIVATE_KEYFILE
by default dar will fetch the public key file in $HOME/.ssh/id_rsa file. If you
use the former id_dsa.pub or more recent key types you need to set this
environment variable to point to the appropriated filename
DAR_IGNORED_AS_SYMLINK
receive a colon separated list of absolute paths, which if they are symlinks are
not saved as symlink but as the inode they point to. For more details see the
--ignored-as-symlink option above.
GNUPGHOME for asymmetric encryption and signature, the keyring used is $HOME/.gnupg by
default. You can change this default by setting GNUPGHOME to the directory
containing the keyring. For example, if you are running dar as root and want to
use your unprivileged account keyring use the following:
export GNUPGHOME=~myaccount/.gnupg
dar -K gnupg:...@...,...@... --sign:...@... etc.
CAPABILITIES
dar fully supports the cap_chown capability, but by design, dar only uses this capability
to restore files at their original ownership. Dar will thus not use this capability to
access files and directories the caller would normally not have access to. In other words,
it should be ok to set the cap_chown capability to the dar executable (setcap cap_chown+p
dar). Calling dar from a process having the cap_chown in the inheritable set would lead
the system to grant this capability to the dar process while other users would not be
granted this capability and would not be able to modify ownership of files at restoration
time. This can be used for the system account that has the role of restoring data upon
user requests, without giving root privilege to this restoration process.
EXAMPLES
You can find some more examples of use in the tutorial, mini-howto, sample scripts, and
other related documentation. All these are available in dar's source package, and are also
installed beside dar in the <--prefix>/share/dar directory. This documentation is also
available on-line at http://dar.linux.free.fr/doc/index.html
SEE ALSO
dar_xform(1), dar_slave(1), dar_manager(1), dar_cp(1), dar_split(1), TUTORIAL and NOTES
included in the source package and also available at
http://dar.linux.free.fr/doc/index.html
KNOWN LIMITATIONS
dar saves and restores atime, mtime, birthtime but cannot restore ctime (last inode
change), there does not seems to be a standard call to do that under UNIX. An up to date
list of known limitation is at http://dar.linux.free.fr/doc/Limitations.html
KNOWN BUGS
http://sourceforge.net/p/dar/bugs/
AUTHOR
http://dar.linux.free.fr/
Denis Corbin
France
Europe