DAR(1)DAR(1)NAMEdar - create, test, list, extract, compare, merge, isolate dar ar‐
chives
SYNOPSISdar [-c | -x | -l | -d | -t | -C | -+] [<path>/]<basename> [<options>]
[<user targets>]
dar-h
dar-V
DESCRIPTIONdar is a full featured backup tool, aimed for disks (floppy, CD-R(W),
DVD-R(W), zip, jazz, etc.) and since release 2.4.0 adapted to tapes.
dar can store a backup in several files (called "slices" in the follow‐
ing) of a given size, eventually pausing or running a user com‐
mand/script before starting the next slice. This can allow for example,
the burning of the last generated slice on a CD-R, or changing a floppy
disk 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 com‐
pressed slices of the defined size. But the most important feature of
dar is its ability to make differential backups. In other words, back‐
ups that contain only new files or files that have changed from a
backup of reference. 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 of the backup. And of course, the reference backup may be a
full or a differential backup itself.
dar is the first backup program I know that can also remove files dur‐
ing restoration! By the way, in this document, "archive" and "backup"
mean the same thing, and are used interchangeably.
Unlike the tar command, dar has not to read a whole archive to know its
contents: dar archive contains a table of contents (aka "catalogue")
located at the end of the archive, so it seeks into the archive forth
and backward to extract only the required files, which is much faster
than what tar is used to do. Since release 2.4.0 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 extract‐
ing file at each step. In other words, the archive contents is located
at both locations, all along the archive used for tar-like behavior
suitable for sequential access media (tapes) and at the end for faster
access, suitable for random access media (disks). However note that
tar archive and dar archive are not compatible. Dar does not known any‐
thing about tar archive structure, neither tar known anything about dar
archive structure. So keep using tar if you are used to it or find no
advantage in using dar. 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).
Since release 2.4.0, a "relax" reading mode is available that let dar
to either ignore some incoherence in archive structure, or use internal
redundant information to overcome what seems to be data corruption, and
in last resort ask the user on what to do when some archive structure
information is missing. This relax mode can be used with both sequen‐
tial and direct access read modes. Note however 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, as
this mode cannot repair the archive, but may only lead to partial ar‐
chive extraction upon archive corruption. For immediate Parchive inte‐
gration with dar, use the "par2" user target defined in /etc/darrc.
A few words about slice before going deeper in detail: 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).
Let's take an example:
considering the basename "joe", dar will make one
or several slices during backup process (depending
on your choice). The filenames of these slices will
be: joe.1.dar joe.2.dar ... joe.10.dar ... etc. If
you want to extract, list, or use this backup as
reference, you will only have to use the basename,
which is the string "joe" in this example.
OPTIONS
COMMANDS:
Only six commands define what action will be done by dar: Archive cre‐
ation, archive extraction, archive listing, archive testing, archive
comparison with filesystem, catalogue isolation and archive merging.
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. Last, optional
user targets may follow options, their use is described at the end of
this document.
Important note: Not all system actually support long options (Solaris,
FreeBSD, ...). For example --create will not be available on these sys‐
tems, and you will have to use -c instead. In the same way, not all
system 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.
-c, --create [<path>/]<basename>
creates a backup with the name based on <basename>.
All the slices will be created in the directory
<path> if specified, else in the current directory.
If the destination filesystem is too small to con‐
tain 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).
-x, --extract [<path>/]<basename>
extracts files from the given backup. Slices are
expected to be in the current directory or in the
directory given by <path>. It is also possible to
use symbolic links to gather slices that are not in
the same directory. Path may also point to a remov‐
able device (floppy, CD, 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 be that directory (see
tutorial for details). The basename may be set to
"-", in direct access mode (the default an histori‐
cal mode), you will need dar_slave to work with dar
(see -i and -o options, as well as dar_slave man
page). However in sequential read mode (--sequen‐
tial-mode is used on command-line), dar will read
the archive from standard input (see also -i
option).
-l, --list [<path>/]<basename>
lists the contents of the given backup. 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 [<path>/]<basename>
checks the backup integrity. Even without compres‐
sion, dar is able to detect at least one error per
file in the archive, thanks to a variable length
CRC recorded per file in the catalogue. Same remark
here, "-" may be used as basename (see -x option
above for details).
-d, --diff [<path>/]<basename>
compares saved files in the backup with those in
the filesystem. <basename> may also be "-" (see -x
option above for details).
-C, --isolate [<path>/]<basename>
isolate a catalogue from its archive. The argument
is the basename of the file that will contain the
catalogue. The -A option is mandatory here to give
the name of the archive to extract the catalogue
from. 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 no difference in concept between an isolated
catalogue and an archive. Thus you can do all oper‐
ation on an isolated catalogue, in particular take
it as reference for a differential archive. An ar‐
chive produced with -C is almost equivalent to dif‐
ferential archive done right after a full backup,
(no data is in it). Since release 2.4.0 you can use
an isolated catalogue to rescue the internal cata‐
logue when it is corrupted (see -A option).
-+, --merge [<path>/]<basename>
create a subset archive from one or two existing
archives (the resulting archive name is the argu‐
ment to this command). The dar file selection mech‐
anism (see below) 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 filter‐
ing 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 manipu‐
late 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 ar‐
chive is produced on standard output allowing the
user to send the resulting archive through a pipe.
The first mandatory archive of reference if pro‐
vided thanks to the -A option, while the second
"auxiliary" (and optional) archive of reference is
provided thanks to the -@ option. When a tie con‐
tention 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-com‐
pressed. Thus the merging operation can be used to
change compression algorithm of given archive as
well as change its encryption. But, for better per‐
formance it is also possible thanks to the -ak
option (see below the -ak option for usage restric‐
tions) 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.
-h, --help displays help usage.
-V, --version displays version information.
GENERAL OPTIONS:
-v, --verbose[=s[kipped]]
verbose output. --verbose and --verbose=skipped are
independent. --verbose=skipped displays the files
being excluded by filters, while --verbose display
actions under process. You can still use dar's exit
status to known which way the operation ended (seen
EXIT CODES at the end of this document).
-q, --quiet Suppress the final statistics report. If no verbose
output is asked beside this option, nothing is dis‐
played if the operation succeeds.
-b, --beep makes the terminal ring when user action is
required (like for example the creation of a new
slice using the -p option)
-n, --no-overwrite do not allow overwriting of any slice.
If an overwriting policy is specified (see -/
option) -n option do only apply to slices overwrit‐
ing, the overwriting of files during restoration or
merging is handled by the overwriting policy. -n
option stay valid to forbid slice overwriting
(merging, saving, isolation).
-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
avoid 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 ar‐
chive of reference. At restoration of the differen‐
tial 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)
-R, --fs-root <path>
The path points to the directory tree containing
all the files that will be enrolled in the opera‐
tion (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 cur‐
rent 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 file‐
names which are not directories. If a given file
matches the mask, it is excluded from the opera‐
tion. 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 file 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
include 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 all the directory tree (as indi‐
cated by -R option) is considered. Note that <path>
may contains wildcards like * or ? see glob(7) man
page for more information.
-g, --go-into <path>
Files or directory to only take in account, as
opposed to -P. -g may be present 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 direc‐
tory. This is equivalent as giving <path> out of
any option. 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 inter‐
preted in the listing file, the null character is
not allowed and the carriage return is used to sep‐
arate file names (one file name per line). 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.
Another difference is when the argument is a direc‐
tory -g will include all the subdirectories under
that directory, while when the same entry is found
in a listing file given to -[ 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 (unless using ordered
method and another mask includes some of its sub‐
files or subdirectories). This option is the oppo‐
site 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 directo‐
ries). As for -[ option, -] listing file can con‐
tain 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 one
command line, one -g 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 con‐
cerning 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 char‐
acter), 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 posi‐
tions 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> gener‐
ates 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 acti‐
vated 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 con‐
figure 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 selec‐
tion 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 and remember that the corresponding mask will
apply to Extended Attribute selection in place of file selec‐
tion).
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 (accord‐
ing 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 sensitiv‐
ity 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.
-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> (usu‐
ally 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 interac‐
tive messages). See doc/usage_notes.html for exam‐
ples of use.
-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 consider cer‐
tain 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 mis‐
match and at restoration dar will
not even try to set the file owner‐
ship.
mtime only inode type and last modifica‐
tion date is considered as well as
inode specific attributes like file
size for plain files. Ownership is
ignored, permission is ignored. Dur‐
ing comparison, difference on owner‐
ship or permission is ignored and at
restoration time dar will not try to
set the inode permission and owner‐
ship.
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 owner‐
ship, 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_modi‐
fication 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 hav‐
ing gone from or to daylight saving time (win‐
ter/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 (thus using -t, -d, -l
or -x options), the command is executed before the
slice is read or even asked, for writing instead
(thus using -c, -C or -+ option), the command is
executed once the slice has been completed. Some
substitution string 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 ini‐
tially 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 it 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 num‐
ber.
%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 read‐
ing an archive for (testing, extraction,
diff, listing, or while reading the ar‐
chive 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
first slice request and to the last slice
requests. After, that point comes the
"operation" context. While creating an
archive, the context is always "opera‐
tion" except when the last slice has been
created, in which case the context is set
to "last_slice".
Several -E option can be given, given commands will then be called in
the order they appear on the command line, and included files. See also
the environment variable DAR_DUC_PATH in the ENVIRONMENT section at the
end of this document.
-F, --ref-execute <string>
same as -E but is applied between slices of the
reference archive (-A option). --execute-ref is a
synonym.
-K, --key [[<algo>]:]<string>
encrypt/decrypt the archive using the <algo> cipher
with the <string> as pass phrase. An encrypted ar‐
chive can only be read if the same pass phrase is
given. 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 blowfish cipher
is assumed. If your password contains a column ':'
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 argu‐
ment that -K can receive is ':' which means blow‐
fish cipher with the pass phrase asked at execution
time.
The old "blowfish_weak" implementation has been removed and is no more
supported.
Note that giving the passphrase as argument to -K (or -J 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 an
Dar Command File (see -B option), assuming it has the appropriated per‐
mission 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 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
time the password is received by dar from user (but through the operat‐
ing system) up to its usage inside libgcrypt (after having been passed
through libdar which also makes use of locked memory).
-J, --ref-key [[<algo>]:]<string>
same as -K but the given key is used to decrypt the
archive of reference (given with -A option). --key-
ref is a synonym.
-#, --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 syntax used for -s option is also available
here. 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 ar‐
chive (through the -* or -# options). If it is not
the correct one, the archive will not be possible
to decrypt, it is thus safe to keep the default
value (and not use at all the -# option).
-*, --ref-crypto-block <size>
same as --crypto-block but for the archive of ref‐
erence (same default value). --crypto-block-ref is
a synonym.
-B, --batch <filename>
You can put in the file 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
includes itself) and DAR aborts immediately. Com‐
ments are allowed, and must start by a hash `#'
character on each line. Note that for a line to be
considered as comment the hash character must be
the first character of the line (space or tab can
still precede the hash). See Conditional Syntax
bellow for a more rich syntax in configuration
files. See also the environment variable
DAR_DCF_PATH in the ENVIRONMENT section at the end
of this document.
-N, --noconf Do not try to read neither ~/.darrc nor /etc/darrc
configuration files. See files section bellow.
-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: multi‐
ple 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.
-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 with 'no', which most
of the time will abort the program. Please note
that this option cannot be used in a configuration
file, it must be given on the command line. 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
redirect stdout and/or sterr to files.
-ac, --alter=ctime When reading a filesystem (during a backup or com‐
parison), 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 sys‐
tems, 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 pro‐
gram 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 flakey 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 Leafn‐
ode NNTP chaching 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 accor‐
dance 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 modi‐
fied while dar reads each file and directory. This provides also better
performances as nothing has to be wrote back to disk. A known Unix ker‐
nel 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 compi‐
lation time), you need to explicitly specify either -aa or -ac option.
-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 inci‐
dence on the --backup-hook-exclude and --backup-
hook-include options.
-an, --alter=no-case
set the filters in case insensitive mode. This con‐
cerns only masks specified after this option (see
also -acase option below). This changes the behav‐
ior of -I, -X, -g, -P, -Z, -Y, -u and -U options.
-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 fol‐
lows 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).
-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 infor‐
mation 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 behav‐
ior is to ignore these escape sequences and rather
rely on the catalogue located at the end of the ar‐
chive. 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 read‐
ing 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.
Whithout escape sequences, dar cannot sequential
read an archive, which is the only way 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 start‐
ing revision "08" (i.e.: since release 2.4.0) and
if -at option has no been used during archive cre‐
ation or merging. This option is available for ar‐
chive testing (-t), comparison (-d), restoration
(-x), listing (-l) and to read the archive of ref‐
erence (-A option) for isolation (-C) archive cre‐
ation (-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.
-j, --jog when virtual memory is exhausted, ask user to make
room before trying to continue. By default, when
memory is exhausted dar aborts. Note that on sev‐
eral system, when memory is exhausted the kernel is
likely to kill the process that failed to obtain
virtual memory, thus on some systems, dar may not
be able to ask user for what to do when memory is
exhausted.
-;, --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 slice starting by '1', then by '2'. for exam‐
ple, 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 exam‐
ple, 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. Then, when read‐
ing your archive, you will also need to provide
this same argument, else dar will fail finding the
slice. In effect, when looking for slice 1 for
example, dar should try opening the file "base‐
name.1.dar", but if it fails, it should try opening
the file "basename.01.dar", then "base‐
name.001.dar", ... up to infinity. If the slice is
just missing, dar would never ask you to provide
it, being still looking for a slice name with an
additional leading zero. The problem also arise
when doing differential backup, merging or on-fly
isolation, dar must know the number of zero to
prepend for each of these archive. This is why the
--min-digits option may receive up to three integer
values, the first for the archive to create or
read, the second for the archive of reference (-A
option), the third for the auxiliary archive of
reference (-@ option). By default, no zero is
added, and it is also well working this way. But
you might well set for example "--min-digits 5,5,5"
in your ($HOME)/.darrc file to do it once and for
all. Last important point, on command-line (not in
DCF files), the short form of this option (-;) need
to be quoted ('-;') to avoid the shell interpreting
the ';' character.
--pipe-fd <num> will read further arguments from the file-descrip‐
tor <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 over‐
come the command line length limit.
SAVING, ISOLATION AND MERGING OPTIONS (to use with -c, -C or -+)
-z[[algo:]level], --compression[=[algo][:][level]]
add compression within slices using gzip, bzip2 or
lzo algorithm (if -z is not specified, no compres‐
sion is performed). The compression level (an inte‐
ger from 1 to 9) is optional, and is 9 by default,
which is max compression/slow processing. At the
opposite, 1 means less compression and faster pro‐
cessing. "Algo" is optional, it specifies the com‐
pression algorithm to use and can take the follow‐
ing values "gzip" "bzip2" or "lzo". "gzip" algo‐
rithm is used by default (for historical reasons
see --gzip below). If both algorithm and compres‐
sion are given, a ':' must be placed between them.
Valid usage of -z option is for example: -z, -z9,
-zlzo, -zgzip, -zbzip2, -zlzo:6, -zbzip2:2,
-zgzip:1 and so on. Usage for long option is the
same: --compression, --compression=9, --compres‐
sion=lzo, --compression=gzip, --compression=bzip2,
--compression=lzo:6, --compression=bzip2:2, --com‐
pression=gzip:1 and so on.
--gzip[=level] Same as -z (see just above). Historically -z/--gzip
was for gzip while -y/--bzip2 was for bzip2. But
due to the lack of available unused letter for com‐
mand line options, lzo compression could not be
added without extending -z option grammar. For
backward compatibility --gzip is kept, but is dep‐
recated. Rather use --compression[=level] or
-z[level].
-y[level], --bzip2[=level]
compresses using bzip2 algorithm. See -z above for
usage details. This option is DEPRECATED and WILL
DISAPPEAR in a future version. Please use
-zbzip2:level or --compression=bzip2:level.
-s, --slice <number>
Size of the slices in bytes. If the number is
appended by k (or K), M, G, T, P E, Z or Y the size
is in kilobytes, megabytes, gigabytes, terabytes,
petabytes, exabytes, zettabytes or yottabytes
respectively. Example: "20M" means 20 megabytes, by
default, it is the same as giving 20971520 as argu‐
ment (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 (there
is probably some filesystem limitation, thus you
might expect problems for file size over 2 giga‐
bytes, depending on your filesystem, but this is
not a limitation of dar).
-S, --first-slice <number>
-S gives the size of the first slice which may be
chosen independently of the size of following
slices. This option needs -s and by default, 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 con‐
tinue the backup. The optional integer that this
option can receive tells dar to only pause very '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.
-A, --ref [<path>]/<basename>
Depending on the context, it specifies the archive
to use as reference (mandatory with -C and -+) or
the rescue catalogue to use (when used with -x -t
or -d). 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 cat‐
alogue of reference. If necessary the use of sym‐
bolic links is also possible here to gather slices
that do not reside in the same directory. You can
also point <path> to a floppy 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)
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 not available when -A is used with -x, -d or -t.
In sequential mode (--sequential-mode is used), the
archive of reference is read from standard input or
on named pipe specified by -i option. -o option has
no use in sequential mode. Note that merging (-+
option) cannot read archive of reference in sequen‐
tial mode.
- a plus sign ("+") which makes the reference be
the current directory status (only available with
-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 is like an
extracted catalogue form a virtual full backup, it
can be taken for further reference without having
to make the full backup itself. This feature is
known as the "snapshot" backup.
- a <date>, if -af option has been placed before -A
on the command-line (or in a included file, see -B
option). For more about that feature see -af option
below.
During backup (-c option) the archive of reference
given thanks to this option is used to compare
existing files on the filesystem. Dar will then
backup only files that have changed since the ar‐
chive of reference was done. During merging (-+
option), the contents of the given archive will
been taken with the contents of the archive speci‐
fied with -@ option (see below). 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 cata‐
logue) will be read from the archive given with -A
instead of using the internal catalogue of the ar‐
chive (given with -t, -d or -x option). 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 opera‐
tion). This gives a solution to the case of corrup‐
tion inside an archive's catalogue, while the best
way is still to use Parchive to protect your data
against media error.
-@, --aux [<path>]/<basename>, --on-fly-isolate [<path>]/<basename>
specifies an auxiliary archive of reference (merg‐
ing 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). Over -A option which is
mandatory with -+ option, you may give a second ar‐
chive of reference thanks to the -@ option (merging
context). This allows you to merge two archives
into a single one. See also -$, -~ and -% for other
options concerning auxiliary archive of reference.
While creating an archive (backup context) this
option let the user specify the archive name for an
on-fly isolation (former -G option), you can also
use -$ and -~ to define encryption of the archive
containing the on-fly isolated catalogue. 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 exigu‐
ity, 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 if you only want to
change slices size (this is faster as no decompres‐
sion/re-compression is done). Using the merging
operation on an isolated catalogue instead of iso‐
lating 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.
-D, --empty-dir At backup time, 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 restora‐
tion 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 options below).
-Z, --exclude-compression <mask>
Filenames covered by this mask are not compressed.
It is only useful with -z option. By default, all
file 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 (eventu‐
ally/probably using wildcards).
-Y, --include-compression <mask>
Filenames covered by this mask (and not covered by
-Z) 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.
-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 com‐
press all file whatever their size is you thus need
to type -m 0 on the command line. The same number
extensions as those used with -s or -S are avail‐
able here, if you want to specify the size in kilo‐
byte, 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 improve‐
ment 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 imple‐
mentation of any particular filesystem, where from
its portability), however 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 no zeroed bytes. This makes dar ar‐
chive 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 viceversa, 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, 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 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 ver‐
sion). The advantage of this option is a greater
speed of execution (compression is usually CPU
intensive).
-ah, --alter=holes-recheck
For merging, the sparse file detection mechanism is
disabled by default. However if you want to acti‐
vate 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 --sparse-file-min-size can be
used as described above for archive creation. In
particular setting --sparse-file-min-size to zero
beside -ah during merging, may also be used to con‐
vert file saved as sparse file into plain normal
files.
-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 modi‐
fication is newer or equal to <date>) and which to
consider unchanged (those older than <date>). This
option has only a sense when creating an archive
(not when merging or isolating).
<date> must be a date in the following possible formats:
- a number of second since Jan 1st, 1970
- a date in the following form [[[year/]month/]day-]hour:minute[:sec‐
ond]
Here are some examples of date:
91836383927108078
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
--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 com‐
piled on did not provide support for ext2 flags.
Note that this option does nothing with -+ option
(merging) as no filesystem is used for that opera‐
tion.
-M, --no-mount-points
stay in the same filesystem as the root directory
(see -R option), 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.
-, , --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)
-$, --aux-key [[<algo>]:]<string>
same as -J but for the auxiliary archive of refer‐
ence (-@ option).
-~, --aux-execute <string>
same as -F but for the auxiliary archive of refer‐
ence (-@ option).
-%, --aux-crypto-block <size>
same as -* but for the auxiliary archive of refer‐
ence (-@ 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 auxil‐
iary '-@' archive or reference.
As soon as you use -/ option -n only applies only to slice overwriting
and the -r, -k and -ae options are ignored (restoration 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 and file's EA. An action is thus a couple of
action for Data and for EA. Actions for Data are represented by upper‐
case letters, while action for EA 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 differen‐
tial 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 ar‐
chives, 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 modifi‐
cation 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) pre‐
serve the whole EA set. When merging two archives, the EA
set of the resulting file will be the EAs of the 'in place'
file (whatever is the overwriting action taken for its
data). While when extracting files to filesystem, the EA 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).
o means 'Overwrite', same as 'O' (but lowercase letter) over‐
write the whole EA set. When merging two archives, the EA
set of the resulting file will be taken from the 'to be
added' file. While when extracting files, the EA set of the
file in the filesystem will have its EA 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 instead of data. When merging two archives,
the EA 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) 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 lower‐
case letter) for EA instead of data. When merging two ar‐
chives, the EA 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 EA and preserve'. The resulting file in the
merged archive will have EA entries from both the 'in
place' and the 'to be added' files. If both files share a
same EA entry (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 set enriched by EA entries of the file in
the archive that do not exist on filesystem, but its
already existing EA will stay untouched.
n means 'merge EA and overwrite'. The resulting file in the
merged archive will have EA entries from both the 'in
place' and the 'to be added' files. If both files share a
same EA entry (same key for a given association) the one of
the 'to be added' file will be kept (where from the 'over‐
write' notion). When extracting file, the file in the
filesystem will have its EA set enriched by EA entries of
the file in the archive with some EA entry possibly been
overwritten.
r means 'remove', same as 'R' but for the EA set (thus all EA
entries) of a given file ('r' is lowercase letter here).
The file of the resulting archive during merging operation
will not own any EA, 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. As for all the previous tests, this EA operation is
independent of the operation chosen for file's data (upper‐
case letters).
d means 'delete'. When a same EA entry is found both in the
'in place' and 'to be added' files these entries will be
absent in the resulting archive. In other words, when merg‐
ing, the EA set will only contain EA entries specific to
the 'in place' and those specific to the 'to be added'
file. Entries in common will not be present. When extract‐
ing 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 entries
(which are thus present in both archive and filesystem)
will be removed from the EA set.
* 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 con‐
cerns 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 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).
When -/ option is not given, the action is equivalent to '-/
Oo', making dar proceed to file and EA overwriting. This is to
stay as close as possible to the former default action where
neither -n nor -w where specified. Note that -w option stays
untouched, in consequences, in this default condition for -/
option, a confirmation will be asked to the user before dar pro‐
ceed to any overwriting. The former -n option (still used to
handle slice overwriting) can be replaced by its equivalent '-/
Pp' for resolving file overwriting conflict (never overwrite).
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 result lead dar to remove any file from filesystem
that ought to be restored(!). Note the action for EA is
useless, the EA 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 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 ar‐
chive 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 dif‐
ferent 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 ar‐
chives, 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.
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 to follow 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 <con‐
dition> 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 state‐
ments this way: {<condition1>}[<action1>] {<condi‐
tion2>}[<action2>] <action3>. In this example, if <condi‐
tion1> is true then <action1> will be used, ELSE if <condi‐
tion2> 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 ' or double ") is necessary.
The last operator we will see is the 'chain' operator. Once an
expression is evaluated, the resulting couple of action may con‐
tain an '*' (undefined action for EA or data). Further evalua‐
tion must be done. The chain operator which is represented by a
semi-column ';' let one to separate several independent expres‐
sions 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 (a 'detruit'
which record the fact that a file has been removed since
the archive of reference is not an inode for example). This
condition do not have any consideration toward the to be
added object, as some others but not all below.
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 sev‐
eral 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 (ad 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 consid‐
eration 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 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 'inver‐
sion' 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 sequen‐
tial 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.
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 exam‐
ple) 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 pre‐
serve 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] {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 semi-
column ';') 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 expres‐
sions 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 permis‐
sion 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 permis‐
sion 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.
To activate this feature you must provide the maxi‐
mum number a given file can be re-saved (this is
the 'count' field).In option the overall maximum
amount of byte allowed to be wasted due to retrying
changing file's backup can be given after a column
charactrer (:), this is the 'max-byte' field. By
default (no --retry-on-change option specified) no
retry is done. If 'max-byte' field is not speci‐
fied, no limit on the bytes is used, each changing
file will be saved up to 'count' times if neces‐
sary. 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. Retrying a backup cannot
replace the already saved backup, a second copy of
the file is added just after the first previous try
and the previous try 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 merg‐
ing/fitering feature: dar -+ new_arch -A old_arch
-ak
-ad, --alter=decremental
This flag is to be used only when merging two ar‐
chives. 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 by -/
"{T&R&~R&(A|!H)}[S*] P* ;
{(e&~e&r&~r)|(!e&!~e)}[*s] *p". Additionally, files
found int 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.
-asecu, --alter=secu
This option disable the ctime check done by default
during an incremental backup: If the ctime of an
plain file has changed since the archive of refer‐
ence was done while all other values stay unchanged
(inode type, ownership, permission, last modifica‐
tion 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 dif‐
ferential backup of a just restored data (a differ‐
ential 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 posi‐
tive).
-., --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 <ar‐
chive> -q). Some macro can be used inside the <mes‐
sage>:
%c is replaced by the command line used. Note
that for security, any option related to ar‐
chive 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> When creating, isolating or merging an archive,
beside each slice is generated an on-fly hash file
using the specified algorithm. Available algorithm
are "md5" and "sha1", by default no hash file is
generated. The hash file generated is named based
on the name of the slice with the .md5 or .sha1
extension added to it at the end. These hash files
can be processes by md5sum and sha1sum usual com‐
mands (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 com‐
pute the hash result on an 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 avail‐
able when producing the archive on a pipe ("dar -c
-").
-<, --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. IMPOR‐
TANT: 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 sensitiv‐
ity 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
by a shell 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
%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 stop a database just before it was about to be backed
up, and restart it once the backup is 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 file in that directory or subdirecto‐
ries have been saved, the command is ran a second time (with the con‐
text "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 com‐
mands (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 con‐
tents and failing on that unknown inode type (fil‐
tering is done based on the result of directory
listing). This option is to avoid dar issuing such
warning in that situation.
RESTORATION 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 pro‐
ceeding, 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 "--no-
delete=ignore" option which is ignored when the -/
is used). Of course "--no-delete=ignore" and "--no-
delete=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 file 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 overwrit‐
ing (-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!
-A, --ref [<path>]/<basename>
-A takes a different meaning when used with -x, -d
or -t. The archive given after -A must be an
extracted catalogue based on the archive given
after -x, -d or -t. This extracted catalogue will
be used for the operation in place of the catalogue
located in the archive. This feature is intended
for the case of corruption within an archive that
affects the internal catalogue. If you have a sane
extracted catalogue of a given archive you can use
it as replacement of the one located in the archive
itself. Note that with the -A option are also
available the following options: -F, -J and -*.
-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 confirma‐
tion before restoring it. Specifying "ignore" will
skip those dirty files, while "no-warn" will
restore them without user confirmation. This fea‐
ture is incompatible with sequential reading mode,
in this mode dar cannot know whether a file is
dirty before having restored it, in consequences,
dar cannot warn nor ignore that a file is dirty
before restoring it, at that time if a file is
dirty it will be removed unless dirty-behavior is
set to "no-warn".
-al, --alter=lax 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).
-/, --overwriting-policy <policy>
Overwriting policy can be used for archive restora‐
tion to define when and how file overwriting can
occur. See above the description of this option.
TESTING AND DIFFERENCE OPTIONS (to use with -t or -d)
-ado-not-compare-symlink-mtime, --alter=do-not-compare-symlink-mtime
Whith this option set, when comparing a symlink,
mtime difference, no message shows when symlink in
archive ans symlink on filesystem do only differ by
their by their mtime. See also -O option.
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 just above for extraction
(backup of internal catalogue).
Doing a difference in sequential read mode is allowed 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>, --tree-format
By default, listing provides a tar-like output (the
'normal' output). You can however get a tree-like
output (the 'tree' output) or an XML structured
output (the 'xml' output). Providing -T without
argument gives the same as providing the 'tree'
argument to it. The option --tree-format is an
alias to --list-format=tree (backward compatibil‐
ity). 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)
-as, --alter=saved list only saved files
-alist-ea, --alter=list-ea
list Extended Attributes name for each file that
has some.
-I, -X, -P, -g, -[, -]
can be used to filter file to list base on their
name or path.
Else only -v and -b from general options are useful. Note that -v dis‐
plays 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]. [ ] 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, and thus this archive is able to restore the
file. [InRef] was used in archive generated by dar
version 2.3.x and before, when isolating a cata‐
logue from an archive and means that the file was
saved in the reference archive. Last, [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.
[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 ref‐
erence, 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 avail‐
able ([Suppr]). [InRef] was used when isolating a
catalogue (release 2.3.x and before) from an ar‐
chive and means that the file was saved in the ref‐
erence archive.
[compr] possible values are [....%] or [-----] or [ ]
or [worse]. Shows if the file has been compressed
and the compression ratio "compressed/uncompressed"
([...%], for example [ 33%] means that the com‐
pressed data takes a third of the corresponding
uncompressed data, thus the lower is this ratio,
the better is the compression), or if the file is
stored without compression ([ ] see -Y and -Z
options) or if the file is not subject to compres‐
sion because it is not a saved regular file
([----]), or if the file takes more space com‐
pressed than its original size ([worse]), due to
compression overhead. Note that the compression
ratio used here is the inverse of what compression
tools usually provide (uncompressed/compressed).
The reason of this choice is that the ratio used
here has the advantage to always stay between 0 and
100%, which is much more easy to work with to pro‐
vide a well formatted output.
[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 cir‐
cumstances (saving an dar archive inside a dar ar‐
chive without compression or encryption, for exam‐
ple) 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 "compres‐
sion 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.
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
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 argu‐
ment 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 CODESdar exits with the following code:
0 Operation successful.
1 Syntax error on command-line.
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 upon dar
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 compar‐
ing, 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 of zero).
7 an error has occurred when calling a libdar routine. This
means the caller (dar program), did not respect the specifi‐
cation of the API (and this can be considered as a particular
case of a bug).
8 the version of dar used is based in 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. I have probably forgot‐
ten to update the exception caching code to take care of new
exceptions... 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.
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 pro‐
gram, 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 gener‐
ated 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 gener‐
ated 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 ar‐
chive 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 isola‐
tion, dar's behavior is the same: For restoration, all opened directo‐
ries 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 opera‐
tion. 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 sig‐
nal 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 con‐
sulted. 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 bellow, 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 sev‐
eral 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 option listed after this condition get used if
previously on command line or file the -x option
has been used
create: all option listed after this condition get used if
previously on command line or file (-B option) the
-c option has been used
list: (or listing:) if -l option has been used
test: if -t option has been used
diff: if -d option has been used
isolate: if -C option has been used
merge: if -+ option 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 com‐
mand 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 fol‐
lowing 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:" sec‐
tion 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 condi‐
tional 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. 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 'tar‐
get3' 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 column (:) 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 column (:) separated list of paths and looks in
each of them in turn, up to the first file found under the
requested name.
EXAMPLES
You can find some more examples of use in the tutorial, mini-howto,
sample scripts, and other related documentation. All these are avail‐
able 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#2
SEE ALSOdar_xform(1), dar_slave(1), dar_manager(1), dar_cp(1), TUTORIAL and
NOTES included in the source package and also available at
http://dar.linux.free.fr/doc/index.html
KNOWN BUGSdar cannot restore time of symbolic links. Many (all ?) UNIX do not
provide any way to do that, the utime() system call changes the file
pointed to by the link rather than the date of the link itself.
dar saves and restores atime and mtime, but cannot restore ctime (last
inode change), there does not seems to be a standard call to do that
under UNIX.
AUTHOR
http://dar.linux.free.fr/
Denis Corbin
France
Europe
3rd Berkeley Distribution Jan. 6th, 2013 DAR(1)
