Provided by: dar_2.4.8-1ubuntu1_amd64 
NAME
dar - create, test, list, extract, compare, merge, isolate dar archives
SYNOPSIS
dar [-c | -x | -l | -d | -t | -C | -+] [<path>/]<basename> [<options>] [<user targets>]
dar -h
dar -V
DESCRIPTION
dar 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 following) of a given
size, eventually pausing or running a user command/script before starting the next slice.
This can allow for example, the burning of the last generated slice on a 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 compressed slices of the defined size. But the most
important feature of dar is its ability to make differential backups. In other words,
backups 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 during 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 extracting 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 anything 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 sequential
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
archive extraction upon archive corruption. For immediate Parchive integration 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 creation, 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 systems, 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
contain all the slices of the backup, the -p option (pausing before
starting new slices) might be of interest. Else, in the case the
filesystem is full, dar will suspend the operation, asking for the
user to make free space, then continue its operation. To make free
space, the only thing you cannot do is to touch the slice being
written. If the filename is "-" *and* no slicing is asked for (no -s
option) the archive is produced on the standard output allowing the
user to send the resulting archive through a pipe (or into a tape
device).
-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 removable 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
historical 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 (--sequential-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 compression, 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 operation on an
isolated catalogue, in particular take it as reference for a
differential archive. An archive produced with -C is almost equivalent
to differential 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 catalogue 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 argument to this command). The dar file
selection mechanism (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 filtering mechanism that accepts all files), as well as this option
let the user create a smaller archive which data is taken from one or
two archives of reference. Note that at no time the contents of the
archives of reference is extracted to real files and directories: this
is an archive to archive transfer, thus you may lack support for
Extended Attribute while you will be able to fully manipulate files
with their Extended Attributes from one archive to the resulting one.
If the basename is "-" *and* no slice is asked (no -s option), the
archive is produced on standard output allowing the user to send the
resulting archive through a pipe. The first mandatory archive of
reference if provided thanks to the -A option, while the second
"auxiliary" (and optional) archive of reference is provided thanks to
the -@ option. When a tie contention occurs (same file names from both
archive have to be merged), the overwriting policy (-/ option) is used
to define the one to keep in the resulting archive. By default,
archive data selected for merging is uncompressed, and re-compressed.
Thus the merging operation can be used to change compression algorithm
of given archive as well as change its encryption. But, for better
performance it is also possible thanks to the -ak option (see below
the -ak option for usage restrictions) to merge files keeping them
compressed, thus no decompression/re-compression is performed at all,
which make the operation faster. Last it is not possible to merge two
isolated catalogues.
-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 displayed 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 overwriting, 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 archive of reference. At
restoration of the differential archive, if a file of the given name
exists, it is remove, but if the type does not match the file that was
present at the time of the archive of reference (directory, plain
file, fifo, socket, char or block device, etc.), a warning is normally
issued to prevent the accidental removal of data that was not saved in
the backup of reference. (See also -k option)
-R, --fs-root <path>
The path points to the directory tree containing all the files that
will be enrolled in the operation (backup, restoration or comparison).
By default the current directory is used. All other paths used in -P
or -g options on the command line are and must be relative to this
path (or to current directory if -R is not present). Note that -R is
useless for testing (-t option) isolation (-C option) and merging (-+
option)
-X, --exclude <mask>
The mask is a string with wildcards (like * and ? see glob(7) for
details) which is applied to filenames which are not directories. If a
given file matches the mask, it is excluded from the operation. By
default (no -X on the command line), no file is excluded from the
operation. -X may be present several times on the command line, in
that case a file will not be considered for the given operation if it
matches at least one -X mask. See also -ar and -am options.
-I, --include <mask>
The mask is applied to filenames which are not directories (see
glob(7) for details on wildcard characters). If a given file matches
the mask and does not match any mask given with -X, the file is
selected for the operation. By default (no -I and no -X on the command
line), all files are included for the operation. -I may be present
several times on the command line, in that case all 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 indicated 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 directory. 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 interpreted in the listing file, the null
character is not allowed and the carriage return is used to separate
file names (one file name per line). 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
directory -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 subfiles or
subdirectories). This option is the opposite of -[ and acts the same
was as -P option does (in particular it is compared to the whole
path+filename and applies to files and directories). As for -[ option,
-] listing file can contain absolute paths, but wildcards are not
expanded, neither.
File selection in brief:
As seen above, -I -X -P, -g, -[ and -] options are used to select the files to operate on.
-I and -X only use the name of files and do not apply to directories, while -P, -g -[ and
-] use the filename *and* the path, they *do* apply to directories.
since version 2.2.0 two modes of interpretation of these options exist. The normal
original method and the ordered method:
the normal method is the default and is the one that has been presented above:
A directory is elected for operation if no -P or -] option excludes it. If at
least one -g or -[ option is given 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 concerning EA selection when using -u and -U options, but that's
no more file selection). In the ordered method the last argument take
precedence over all the previous ones, let's take an example:
-X "*.mp?" -I "*.mp3" -I "toto*"
Here dar will include all files except file of name "*.mp?" (those ending
with "mpX" where X is any character), but it will however include those
ending with ".mp3". It will also include files which name begin by "toto"
whatever they end with. This way, "toto.mp2" will be saved (while it
matches "*.mp?" it also begins by "toto") as well as "toto.txt" as well
as "joe.mp3" (while it matches "*.mp?" it also ends by "mp3"). But will
not be saved "joe.mp2" (because it does not begin by "toto", nor ends by
"mp3", and match "*.mp?" mask). As we see the last option (-I or -X)
overcomes the previous one. -P, -g, -[ and -] act together the same but
as seen above they do not only act on filename, but on the whole
path+filename. Note that (-g, -P, -[, -]) and (-X , -I) are independent
concerning their relative order. You can mix -X -I -g -P -] -[ in any
order, what will be important is the relative positions of -X options
compared to -I options, and the relative positions of -g -[ -] and -P
options between them.
In logical terms, if <prev_mask> is the mask generated by all previous mask on the
command line, -I <mask> generates the new following mask: <prev_mask> or <mask> .
While -X <mask> generates the new following mask: <prev_mask> and not <mask>. This
is recursive each time you add a -I or -X option. Things work the same with -P, -g,
-[ and -] options.
This ends the file selection explication let's continue with other options.
-u, --exclude-ea <mask>
Do not consider the Extended Attributes (EA) that are matched by the
given mask. By default, no EA are excluded, if the support for EA has
been activated at compilation time. This option can be used multiple
times.
-U, --include-ea <mask>
Do only consider the EA that match the given mask. By default, all EA
are included if no -u or -U option is present and if the support for
EA has been activated at compilation time. This option can be used
multiple times. See also the -am and -ae options, they also apply to
-U and -u options and read below the Note concerning EA.
Note concerning Extended Attributes (EA)
Support for EA must be activated at compilation time (the configure script tries to
do so if your system has all the required support for that). Thus you can get two
binaries of dar (of the same version), one supporting EA and another which does not
(dar -V to see whether EA support is activated). The archives they produce are the
same and can be read by each other. The only difference is that the binary without
EA support is not able to save or restore EAs, but is still able to test them and
list their presence.
In the following when we will speak about Extended Attribute (EA) or EA entry, we
will only consider a particular Extended Attribute key and its value. By
opposition, the set of all EA associated to a file will be designated by "EA set".
Since version 2.3.x the name of EA entries include the namespace for dar be able to
consider any type of EA (not only "system" and "user" as previously). Thus the two
previous options -u and -U have changed and now take an argument which is a mask
applied to EA entry names written in the following form namespace.name where
"namespace" is for example "user". Note that the mask may or may not include the
dot (.) and may match arbitrary part of the EA namespace+name, just remind that
masks will be applied to the "namespace.name" global string.
the -am flag here also enables the ordered method, for EA selection too. The
ordered versus normal method have been explained above in the file selection note,
with some examples using -X and -I. Here this is the same with -U and -u, (just
replace -X by -u and -I by -U and remember that the corresponding mask will apply
to Extended Attribute selection in place of file selection).
Another point, independently of the -am option the -ae option can be used at
restoration time only. If set, when a file is about to be overwritten, all EA will
be first erased before restoring those selected for restoration in the archive
(according to the -U and -u options given). If not set, the EA of the existing file
will be overwritten, those extra EA that are not in the archive or are not selected
for restoration in regard to the -u and -U options will be preserved. If you have
not used any -u/-U option at backup time and want to restore from a set of
full/differential backups the EA exactly as they were, you have to use -ae for dar
removes the EA before overwriting their set of EA as stored in the archive. Without
-ae option dar will simply add EA to existing ones, thus get a different set of EA
for a give file than those recorded at the time of the backup.
Last point the -acase and -an options alters the case sensitivity of the -U and -u
masks that follow them on the command-line/included files as they do for -I, -X,
-P, -g, -[ and -] as well. Very last point ;-), if -ac option is used during backup
dar set back the atime after having read each file (see -aa/-ac options), this has
as side effect to modify the ctime date of each file. But ctime change is used by
dar to detect EA changes. In brief, the next time you backup a file that had to be
read (thus which contents changed), its EA will be saved even if they had not
changed. To avoid this side effect, don't use the -ac option if not necessary.
This ends the Extended Attribute selection explication let's continue with other options.
-i, --input <path> is available when reading from pipe (basename is "-" for -x, -l, -t,
-d or for -A when -c, -C or -+ is used). When reading from pipe,
standard input is used, but with this option, the file <path> (usually
a named pipe) is used instead. This option is to receive output from
dar_slave program (see doc/usage_notes.html for examples of use). Note
that when --sequential-read is used, dar uses a single pipe and does
no more rely on dar_slave, -i option can be used to tell dar which
named pipe to read the archive from, instead of the standard input.
-o, --output <path> is available when reading from pipe (basename is "-" for -x, -l, -t,
-d or for -A when -c, -C or -+ is used). When reading from pipe,
standard output is used to send request to dar_slave, but with this
option, the file <path> (usually a named pipe) is used instead. When
standard output is used, all messages goes to standard error (not only
interactive messages). See doc/usage_notes.html for examples of use.
-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 certain fields. The available flags are:
ignore-owner all fields are considered except ownership. This is
useful when dar is used by a non-privileged user. It
will not consider a file has changed just because of a
uid or gid mismatch and at restoration dar will not
even try to set the file ownership.
mtime only inode type and last modification date is
considered as well as inode specific attributes like
file size for plain files. Ownership is ignored,
permission is ignored. During comparison, difference on
ownership or permission is ignored and at restoration
time dar will not try to set the inode permission and
ownership.
inode-type Only the inode type is considered. Ownership,
permission and dates are ignored. Inode specific
attributes are still considered (like file size for
plain files). Thus comparison will ignore differences
for ownership, permission, and dates and at restoration
dar will not try to set the ownership, permission and
dates.
When no flag is provided to this option, -O option acts as if the "ignore-owner" flag was
set, which is the behavior in older releases (< 2.3.0). Note also that for backward
compatibility, --ignore-owner option still exists and since version 2.3.0 is just an alias
to the --comparison-field=ignore-owner option. Of course if this option is not used, all
fields are used for comparison or restoration.
-H[num], --hour[=num]
if -H is used, two dates are considered equal if they differ from a
integer number of hours, and that number is less than or equal to
[num]. If not specified, num defaults to 1. This is used when making a
differential backup, to compare last_modification date of inodes, at
restoration or merging time if overwriting policy is based on file's
data or EA being more recent and last, when comparing an archive with
a filesystem (-d option). This is to workaround some filesystems (like
Samba filesystem) that seems to change the dates of files after having
gone from or to daylight saving time (winter/summer time). Note that
-H option has influence on the overwriting policy (see -/ option) only
if it is found before on command-line or in an included file (using -B
option).
-E, --execute <string>
the string is a user command-line to be launched between slices. For
reading (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
initially it does not know its number. If it cannot be found
in the current directory, the user command-line is then
called with %n equal to 0. This is a convenient way to
inform the user command to provide the last slice. If after
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 number.
%N is the slice number with the leading zero as defined by
--min-digits option. If this option is not used, %N is
equivalent to %n.
%e will be replaced by the slice extension (always substituted
by "dar")
%c will be replaced by the context. Actually three possible
values exist: "init", "operation" and "last_slice". When
reading an archive for (testing, extraction, diff, listing,
or while reading the archive of reference, see below the -F
option), the "init" context takes place from the beginning
up to the time the catalogue is retrieved. On a multiple
slice archive this correspond to the first slice request and
to the last slice requests. After, that point comes the
"operation" context. While creating an archive, the context
is always "operation" except when the last slice has been
created, in which case the context is set to "last_slice".
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 archive 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 argument that -K can receive is ':' which means
blowfish 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
permission to avoid other users reading it. For those paranoids that are really concerned
about security of their passwords, having a password read from a DCF is not that secure,
because while the file gets parsed, dar makes use of "unsecured" memory (memory than can
be swapped to disk under heavy memory load conditions). It is only when the passphrase has
been identified that locked memory 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 operating 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 archive (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 reference (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. Comments 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: multiple of 2^10 (a Mega is 1,048,576).
The --alter=SI and --alter=binary options can be used several times on the command line.
They affect all prefixes which follow, even those found in files included by the -B
option, up to the next --alter=binary or --alter=SI occurrence. Note that if in a file
included by the -B option, an --alter=binary or --alter=SI is encountered, it affects all
the following prefixes, even those outside the included files. For example, when running
with the parameters "-B some.dcf -s 1K", 1K may be equal to 1000 or 1024, depending on
--alter=binary or --alter=SI being present in the some.dcf file. By default (before any
--alter=SI/binary option is reached), binary interpretation of prefixes is done, for
compatibility with older versions.
-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 comparison), restores
the atime of all files to what it was before the file was read. This
makes it appear as if it had not been read at all. However, because
there is no system call to let applications changing the ctime (last
inode change) of a file, setting back the atime results in the ctime
being changed (hence the alter=ctime). Some recent unix system allow
an application to get 'furtive read mode' to the filesystem (see
below). On older systems, however, for most users, having the atimes
of the files changed shouldn't be a problem, since they can be changed
by any other program (running by any user!) as well (like the content-
index program Beagle). Ctimes on the other hand, are the only way for
security software to detect if files on your system have been replaced
(by so called root-kits mostly). This means, that should you run dar
with -ac, security software which uses ctimes to check, will mark
every file on your system as compromised after the backup. In short,
this means this option should only be used by people who know what
they are doing. It's the opinion of this writer that any software
susceptible to atime changes is 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 Leafnode 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 accordance with what atimes and ctimes were meant
to represent. This is Dar's default (since version 2.4.0), unless
'furtive read mode' (see below) is supported by your system and dar
has been compiled with this support activated.
Furtive read mode is a mode in which neither atime nor ctime are modified while dar reads
each file and directory. This provides also better performances as nothing has to be wrote
back to disk. A known Unix kernel that supports this feature is Linux 2.6.8 and above
(support must also be present in the standard C library of the system for dar to be able
to activate this feature at compilation time). When this feature is activated, it becomes
the default behavior of dar for super user ; for other users the default is -aa. If
however as root user, you do not want to use "furtive read mode" (while it has been
activated at compilation time), you 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 incidence on the --backup-hook-exclude and --backup-hook-include
options.
-an, --alter=no-case
set the filters in case insensitive mode. This concerns only masks
specified after this option (see also -acase option below). This
changes the behavior of -I, -X, -g, -P, -Z, -Y, -u and -U options.
-acase, --alter=case
set back to case sensitive mode for filters. All following masks are
case sensitive, up to end of parsing or up to the next -an option.
This changes the behavior of -I, -X, -g, -P, -Z, -Y, -u and -U
options.
-ar, --alter=regex set the filters to be interpreted as regular expressions (man regex(7)
) instead of the default glob expression (man glob(7) ) This modifies
the -I, -X, -g, -P, -Z, -Y, -u and -U options that follows up to an
eventual -ag option (see just below). Note that for -P option, the
given mask matches the relative path part of the files path: Let's
take an example, assuming you have provided /usr/local to the -R
option, the mask "^foo$" will replaced internally by
"^/usr/local/foo$" while the mask "foo$" will be replaced internally
by "^/usr/local/.*foo$".
-ag, --alter=glob This option returns to glob expressions mode (which is the default)
after an -ar option has been used, this applies to any -I, -X, -g, -P,
-Z, -Y, -u and -U options that follow up to an eventual new -ar option
(see just above).
-at, --alter=tape-marks
For archive creation and merging, the default behavior (since release
2.4.0) is to add escape sequences (aka tape marks) followed by inode
information all along the archive. If -at is given, dar will not add
this information to the archive, resulting in a slightly smaller
archive and faster backup. When reading an archive, the default
behavior is to ignore these escape sequences and rather rely on the
catalogue located at the end of the archive. If instead --sequential-
read is given on command-line (see below), dar will avoid using the
catalogue at the end of the archive and will rely on these escape
sequences to know the contents of the archive, which will lead to a
sequential reading of the archive, operation suitable for tape media.
Note that it is not recommended to disable escape sequences (aka tape
marks) by using -at option except if you are more concerned by the
resulting size and execution speed of your backup (in particular if
you have a lot of small files) than by the possibility to recover your
data in case of corrupted or partially written archive. 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 starting revision "08" (i.e.: since
release 2.4.0) and if -at option has no been used during archive
creation or merging. This option is available for archive testing
(-t), comparison (-d), restoration (-x), listing (-l) and to read the
archive of reference (-A option) for isolation (-C) archive creation
(-c). The sequential reading of an archive is always much slower than
the usual reading method, so you should not use this option unless you
really need it.
-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 several 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 example, slice
1, 10, 11, 12, 13, ... 2, 20, 21, 23, ... etc. While dar is absolutely
not perturbed by this display problem, some user shall like to have
the slices sorted by order. For that reason, the --min-digits option
lets you ask dar to prepend enough zeros in the slice number for it be
as wide as the argument passed to --min-digits. For example, if you
provide 3 for that number, dar will store the slice number as 001,
002, 003, ... 999. Well, next slice will be 1000, thus it will break
again the alphabetical sorting order. You are thus advised to use a
number large enough to convert the number of slice you expect to use.
Then, when reading 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
"basename.1.dar", but if it fails, it should try opening the file
"basename.01.dar", then "basename.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-descriptor <num>. The
arguments read through this file-descriptor must follow a TLV
(Type/Length/Value) list format. This option is not intended for human
use, but for other programs launching dar like dar_manager. This
feature has been added to overcome the command line length limit.
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 compression is performed). The compression
level (an integer 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 processing. "Algo" is optional, it specifies
the compression algorithm to use and can take the following values
"gzip" "bzip2" or "lzo". "gzip" algorithm is used by default (for
historical reasons see --gzip below). If both algorithm and
compression 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, --compression=lzo, --compression=gzip,
--compression=bzip2, --compression=lzo:6, --compression=bzip2:2,
--compression=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 command line options, lzo compression could not be added
without extending -z option grammar. For backward compatibility --gzip
is kept, but is deprecated. 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 argument (see also -aSI and -abinary options). If
-s is not present the backup will be written to a single slice
whatever the size of the backup may be (there is probably some
filesystem limitation, thus you might expect problems for file size
over 2 gigabytes, 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
continue 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
catalogue of reference. If necessary the use of symbolic links is also
possible here to gather slices that do not reside in the same
directory. You can also point <path> to a 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 sequential 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 archive of
reference was done. During merging (-+ option), the contents of the
given archive will been taken with the contents of the archive
specified 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 catalogue) will be
read from the archive given with -A instead of using the internal
catalogue of the archive (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 operation). This gives a solution to the case of
corruption inside an archive's catalogue, while the best way is still
to use Parchive to protect your data against media error.
-@, --aux [<path>]/<basename>, --on-fly-isolate [<path>]/<basename>
specifies an auxiliary archive of reference (merging context) or the
name of the on-fly isolated catalogue (creation context). This option
is thus only available with -+ option (merging) and -c option (archive
creation). Over -A option which is mandatory with -+ option, you may
give a second archive 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 exiguity, it is not
possible to change compression algo nor slice size for the on-fly
isolation. If you need a more complicated isolation, either look for a
GUI over libdar, or do a normal (= not an on-fly) isolation operation
(By the way it is possible to isolate an already isolated catalogue,
this is equivalent to doing a copy, but you can change encryption,
compression or slicing, for example), you can also use dar_xform if
you only want to change slices size (this is faster as no
decompression/re-compression is done). Using the merging operation on
an isolated catalogue instead of isolating the isolated catalogue,
leads the resulting archive to not be able to be used as a rescue for
internal catalogue of the original archive. --aux-ref is a synonym.
-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 restoration time, dar will
then recreate these directories (if necessary). This option has no
meaning with -C and is ignored in that case. Independently of that, -D
can also be used at restoration time, but it activates a slightly
different feature (see restoration 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
(eventually/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 compress 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 available here, if you want to specify the size in
kilobyte, megabyte, gigabyte etc.
-1, --sparse-file-min-size <number>
Define the minimum length of zeroed bytes to replace by "holes". By
default, this feature is activated with a value of 15 bytes. To
completely disable it, set the size to zero. Disabling this feature
will bring some noticeable speed improvement but will probably make
the archive slightly bigger (depending on the nature of the data).
Sparse files are files that contain so called holes. On a filesystem,
the portion of zeroed bytes is not stored on disk, thus an arbitrary
large file with huge portion of zeros may only require a few bytes of
disk storage. While dar cannot detect how is allocated a given file
because it makes a filesystem abstraction (it does not know the
implementation of any particular filesystem, where from its
portability), 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 archive disk space requirement much smaller when a sparse files is
met. At restoration time, dar will restore holes writing normal data
and seeking over the hole to write down the normal data after each
hole. If the underlying file system supports sparse files, this will
restore the holes. Note that there is no difference for applications
whether a file is sparse or not, thus dar may well transform normal
files into sparse files and 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 version). 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 activate it (assuming you have an old
archive you want to convert the current archive format taking care of
sparse files), you need to use -ah option to reactivate the sparse
file detection mechanism. Then for merging --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 convert 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 modification
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[:second]
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 compiled on did not provide support for ext2 flags. Note that
this option does nothing with -+ option (merging) as no filesystem is
used for that operation.
-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 reference (-@ option).
-~, --aux-execute <string>
same as -F but for the auxiliary archive of reference (-@ option).
-%, --aux-crypto-block <size>
same as -* but for the auxiliary archive of reference (-@ option).
-/ , --overwriting-policy <policy>
This option let the user define when or how file overwriting can occur
at restoration or archive merging time. It does no apply to slice
overwriting which are driven by the -n option, it does instead apply
to file during extraction and files inside archives when merging two
of them. When considering overwriting, a file is said to be 'in place'
while an other is known as 'new' or 'to be added'. At restoration
time, the 'in place' is the one that is present in filesystem while
the 'to be added' is the one from the archive. At merging time, the
'in place' is the one of the '-A' archive of reference while the 'to
be added' is the one from the auxiliary '-@' archive or reference.
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 uppercase 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 differential archive, even if none of the original archive were
differential archives). All data will be dropped in the resulting archive, but
the last modification date [aka mtime] (used to detect change in file's data)
will be taken from the 'in place' file. This action does not apply when
extracting files, it is thus considered equal to "Preserve" (P) in that
situation.
T means 'mark Saved and overwrite'. When merging two archives, the data of the
resulting archive will be marked as already saved (same as 'S' action): all
data will be dropped in the resulting archive, however the last modification
date [aka mtime] (used to detect changes in a file's data) will be taken from
the 'to be added' file. This action does not apply when extracting files, it
is thus considered equal to "Overwrite" (O) in that situation.
R means 'Remove'. When merging two archives, the resulting archive will not
contain any entry corresponding to the file that were in conflict. This also
implies that no EA will be stored for that particular entry as the entry will
no more exist in the resulting archive (as if it had never yet existed). When
extracting files, this will lead to file's suppression.
p means 'Preserve', same as 'P' (but lowercase letter) preserve the whole EA
set. 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) overwrite 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 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] (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 'overwrite' 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 (uppercase 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 merging, 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 extracting a file from an archive, the file on
filesystem will have its EA set enriched by entries of the 'to be added' file
that are new to the 'in place' file. The other 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 concerns Data
overwriting. An application interaction let the user define the action for
each file in conflict. Note, that this action if used alone may become very
boring or painful. The idea is to use it in conditional statements (which are
described below) to have dar ask for only non obvious cases.
a means 'Ask for user decision'. This lowercase letter is the equivalent for EA
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 proceed 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 archive of reference (-@ option) ) will
provide the same action as an archive isolation of the archive of reference,
but using twice more memory (so keep using the isolation operation as before!
Here this is just an illustration of the possibility)
As seem previously -u and -U options can be used to filter which EA entry to
consider and which to ignore. The question here is to explain how this filtering
mechanism interacts with the different policies we just presented above. For files
that are not in conflict (found only as 'in place' or as 'to be added'), only the
EA entries matching the EA filter are kept. For files in conflict, the overwriting
policy is evaluated first, then the filtering mechanism is applied *after* it. Thus
for example, using the following [ -/ "Po" -u "*test" ], when merging two archives,
only EA ending with "test" will be retained, and when a conflict takes place, this
"*test" ending EA will be taken from the 'to be added' file if it has some EA of
that type, its other EA entry will be ignored as well as any EA entry of the 'in
place' file even those ending by "test". At restoration in using the same options,
file without conflict will get restored but only EA entry ending with "test" will
be restored, and for file with conflict (already present in filesystem), EA set of
file in filesystem will be removed and replaced the EA entries of the file in
archive that ends by "test", if some exist.
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 <condition> then <action> else <action>" paradigm common to
programming languages, due to the command line context it has been chosen to
instead use and implicit "OR" operator between actions. Thus you can "stack"
conditional statements this way: {<condition1>}[<action1>]
{<condition2>}[<action2>] <action3>. In this example, if <condition1> is true
then <action1> will be used, ELSE if <condition2> is true then <action2> will
be used ELSE <action3> will be used. This leads to the same possibilities as
what is available with programming languages, but with a slightly more simple
syntax. Seen this, the recursion of conditional syntax is more interesting.
For readability, you are allowed to add any space or tab in the overwriting
policy, but the resulting overwriting policy must be given as a single
argument to dar, thus the use of quotes (either simple ' 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 contain an '*' (undefined action for
EA or data). Further evaluation must be done. The chain operator which is
represented by a semi-column ';' let one to separate several independent
expressions that will be evaluated in turn up to the time the couple of action is
fully defined. Once an action (for EA or for Data) is defined, it can be redefined
by a subsequent evaluation in the chain, however if the action is defined it cannot
be set back to undefined, thus '*' will never overwrite a previously defined
action. If at the end of the policy the couple of action is not fully defined, the
'preserve' action is used ('P' or 'p' depending on which of EA or Data is left
undefined). Here follow a example of syntax:
-/ "{<condition1>}[P*] O* ; {<condition2>[*p] *o} ; Rr"
The first expression will evaluate to either P* or O*. At this step, as the
action is not completely defined, the second part of the chain is evaluated,
It will end with either *p or *o. In any case, we have after this second
statement of the chain a fully defined action for both data and EA (either Pp,
Po, Op or Oo). Thus the evaluation stops here and the "Rr" policy will never
be evaluated.
We now have one last thing to see: the available conditions (what to place between
braces '{' and '}'). Conditions are defined each by a letter, eventually followed
by an argument between parenthesis. The usual logical operators are available:
negation (!), conjunction (&) disjunction (|). These characters must be escaped or
quoted to not be interpreted by the shell when used on command-line. In particular
the '!' under most shell must be quoted and escaped (-/ '{\!R}[..]..', The escape
character '\' is not necessary inside DCF files (those given to -B option) as no
shell is used to interpret these files. To these usual operators has been added a
new one: the "inversion" operator, noted '~'. Like the negation, it is an unary
operator but unlike the negation, it inverses the roles of 'in place' and 'to be
added' for the evaluation, which is slightly different from taking the negation of
the result of the evaluation. All these operators follow the usual precedence:
unary operators ('!' and '~') are evaluated first, then the conjunction '&' then
the disjunction '|'. To override this, you can use parenthesis '(' and ')' inside
the condition. Over these logical operators, the conditions are based on atomic
operator that compare the 'in place' file to the 'to be added' file. Here they
follow:
I true only if the 'in place' entry is an inode (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 several times to the
directory tree (= hard link) it may be a plain file, a Unix socket, a pipe,
char device, a block device for example.
A same as H but the current 'in place' entry is the first link we meet pointing
to that hard linked inode.
R true if the 'in place' entry is more recent than or of same date as the 'to be
added' entry. The last modification date [aka mtime] is used for this
comparison. If the 'to be added' entry is not an inode (and thus has no
mtime), the 'in place' is considered to be more recent than the 'to be added'
entry. Same thing if the 'in place' entry is not an inode (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 consideration is done toward the 'to be
added' element. The <date> format is the same as the one used with -af option.
If an entry has no mtime (it is not an inode for example) it is assumed an
virtual mtime of zero.
B true only if both 'in place' and 'to be added' are plain file (hard linked or
not) and if the 'in place' file's data is larger or equal to the 'to be added'
file's data. If one or both entry are not plain files (or hard link to plain
file) and thus the file size comparison is not possible, the 'in place' entry
is assumed to be 'bigger' than the 'to be added' entry.
S true only if the 'in place' data is saved in the archive (not marked as
unchanged since the archive of reference). Note that while extracting files
from an archive, the 'in place' file is the one in the filesystem, which
always has its data 'saved' (from libdar point of view). The 'inversion' of
this atomic operator ~S may still be interesting in the context of
restoration.
Y true only if the 'in place' data is saved but dirty (plain file having its
data changed at the time it was read for backup). Note, that restoring in
sequential read mode, it is not possible to known whether a file is dirty (it
is possible to know it once having read its data, but sequential reading does
not allows then to skip forward to get the dirty state of the file and skip
backward to eventually restore that file, depending on the overwriting policy
result).
X true only if the 'in place' data is a sparse file
T true only if the 'in place' and 'to be added' entries are of same type (plain
file, Unix socket, named pipe, block device, char device, symlink, directory,
'detruit' (which stands for file deleted since the archive of reference was
done), and so on). Note that the number of links to inode (i.e. whether this
is a hard links or not) is not taken into account.
e true if the 'in place' entry has EA (may they be saved or just recorded as
existing).
r true if the 'in place' entry has more recent or equal dated EA to the 'to be
added' entry. If 'to be added' has no EA or is even not an inode, true is
returned. If 'in place' has no EA or is even not an inode, true is returned
unless 'to be added' has some EA. The comparison is done on ctime dates.
r(<date>)
true if the 'in place' entry has more recent or equal dated EA to the fixed
<date> given in argument. No consideration is done toward the 'to be added'
element. The <date> format is the same as the one used with -af option. If an
entry has no date (ctime date) (when it is not an inode for example) it is
assumed an virtual ctime of value zero.
m true only if 'in place' has more or equal number of EA entry in its set of EA
than 'to be added' has. If an entry has not EA or is not even an inode, it is
assumed it has zero entry. The comparison is done on this number. Note that
the number of EA entry is not the size used to store these entries. For
example, the EA entry "user.test" counts for 1, whatever is the length of the
value associated to it.
b true if the 'in place' entry has bigger EA set or equal size EA set than the
'to be added' entry. If an entry has no EA or is even not an inode, it is
assumed that it has a zero byte length EA set. The comparison is done on this
number in that case. Note that the comparison is done on the bytes used to
store the whole EA set associated to a given file.
s true if the 'in place' entry is an inode (or a hard linked inode) and has its
EA saved in the archive of reference, not only marked present but unchanged
since last backup. This test does not take the 'to be added' entry into
account.
Well, you've seen that uppercase letter are kept when comparison is based on the
inode or data while lowercase letter is used for atomics based on EA. Now that we
have completed our tour of this feature let's see some examples:
-/ Pp
as seen previously this is what does -n option for files when no overwriting
policy is defined, which avoids any overwriting for Data as well as for EA.
-/ "{!T}[Pp] {R}[{r}[Pp]Po] {r}[Op] Oo"
Space and tabs are allowed to ease readability. Here the policy stands for: If
files in conflicts are not of the same type then keep Data and EA of the entry
'in place'. Else if 'in place' has a more recent data then if 'in place' has
more recent EA then keep both its Data and EA, else keep only its Data and
overwrite its EA. Else (if 'in place' has not the more recent data), if it has
the more recent EA then overwrite the data but keep its EA, else overwrite
both its data and EA. This policy tends to preserve the most recent data or
EA, but it does not take into account the fact that EA or Data is effectively
saved into the archive of just marked as unchanged since the archive of
reference.
-/ "{!T}[{~D}[Oo] Pp]"
If entries are not of the same type, if the 'to be added' entry is a directory
then we keep it and overwrite the 'in place' entry, else we keep the 'in
place' entry. If entry are of same type, the policy does not provide any
action, thus the default action is used: "Pp". You can change this default
action easily using a chain operator:
-/ "{!T}[{~D}[Oo] Pp] ; Aa"
In this case instead, if entry are of the same type, the user will be asked
what to.
-/ "{!T|!I}[{R}[Pp] Oo] {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 expressions follow the same
principle: If both entries are saved (by opposition to be marked as unchanged
since the archive of reference) in the archives, the most recent EA/Data is
kept, else, the one of the inode that is saved is kept, but if none is saved
in the archive the most recent entry (mtime/ctime) is kept.
-^, --slice-mode perm[:user[:group]]
defines the permission and ownership to use for created slices. By
default, dar creates slices with read and write available for anyone
letting the umask variable disable some privileges according to user's
preferences. If you need some more restricted permissions, you can
provide the permission as an octal value (thus beginning by a zero),
like 0600 to only grant read and write access to the user. Be careful
not to avoid dar writing to its own slices, if for example you provide
permission such as 0400. Note also that the umask is always applied
thus specifying -^ 0777 will not grant word wide read-write access
unless your umask is 0000.
-_, --retry-on-change count[:max-byte]
When a file has changed at the time it was read for backup, you can
ask dar to retry saving it again. To activate this feature you must
provide the maximum 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 specified, no limit on the bytes is used, each changing
file will be saved up to 'count' times if necessary. A file is
considered as changed when the last modification time has changed
between the time the file has been opened for backup and the time it
has been completely read. 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
merging/fitering feature: dar -+ new_arch -A old_arch -ak
-ad, --alter=decremental
This flag is to be used only when merging two archives. Instead of the
usual merging where each files of both archives are added to the
resulting archive with eventually a tie using the overwriting policy
(see -/ option), here the merging builds an archive which corresponds
to the decremental backup done based on two full backups. the -A
backup is expected to receive the older archive while the -@ is
expected to point to the more recent one. If this option is used, the
eventually overwriting policy is ignored and replaced 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 inode has changed since the
archive of reference was done with all other values being unchanged
(inode type, ownership, permission, last modification date, file
size), dar issues a "SECURITY WARNING", as this may be the sign of the
presence of a rootkit. You should use this option to disable this type
of warning, if you are doing a differential backup of a just restored
data (differential backup with the archive used for restoration taken
as reference), as it is not possible to restore ctime, 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, the security warning will show (false
positive).
-., --user-comment "<message>"
This option let the user add an arbitrary message into the archive
header. Warning! this message is always stored in clear text, even if
the archive is encrypted. You can see the message inserted in an
archive displaying the archive summary (dar -l <archive> -q). Some
macro can be used inside the <message>:
%c is replaced by the command line used. Note that for security, any
option related to archive encryption is removed (-K, -J, -$, -#,
-*, -%). The command included from a DCF file (see -B option) are
never added by this macro. As a consequence, if you do not want
to see --user-comment stored in user comments you can add the
--user-comment definition in an included file like ~/.darrc for
example.
%d this is the current date and time
%u this is the uid under which dar has been run
%g this is the gid under which dar has been run
%h the hostname on which the archive has been created
%% the % character.
-3, --hash <algo> 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 commands (md5sum -c <hash
file>) to verify that the slice has not been corrupted. Note that the
result is different than generating the hash file using md5sum or
sha1sum once the slice is created, in particular if the media is
faulty: calling md5sum or sha1sum on the written slice will make you
compute the hash result on 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
available 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. IMPORTANT: if using the short
option, you need to enclose it between quotes: '-<' for the shell not
to interpret the < as a redirection.
-> --backup-hook-exclude <mask>
The mask is applied to path+filename during backup operation only. If
a given file matches the mask, even if it matches a mask given after
-< option, no user command will be executed before and after its
backup. The -< and -> options act like -g and -P, they can receive
wildcard expression and thus have their comportment driven by the
--alter=globe and --alter=regex expressions seen above, as well as the
--alter=mask option. Last the --alter=case and --alter=no-case modify
also the way case sensitivity is considered for these masks. By
default, no -> or -< option, no file get selected for backup hook.
IMPORTANT: if using the short option, you need to enclose it between
quotes: '->' for the shell not to interpret the > as a redirection.
-=, --backup-hook-execute <string>
for files covered by the mask provided thanks to the -< and ->
options, the given string is executed 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 subdirectories have been saved, the command is ran
a second time (with the context "end"). During that time, if any file do match the backup-
hook masks, no command will be executed for these. It is assumed that when a directory has
been asked for a backup-hook to be executed this hook (or user command) is prepare for
backup all data located in that directory. The environment variable DAR_DUC_PATH also
applies to these user commands (see -E above, or the ENVIRONMENT paragraph below).
-ai, --alter=ignore-unknown-inode-type
When dar meets an inode type it is not aware about (some times ago, it
was the case for Door inode on Solaris for example, Door inodes are
handled by dar since release 2.4.0), it issues a warning about its
inability to handle such inode. This warning occurs even if that entry
is filtered out by mean of -X, -I, -P, -g, -[ or -] options, as soon
as some other entry in that same directory has to be considered for
backup, leading dar to read that directory contents and failing on
that unknown inode type (filtering is done based on the result of
directory listing). This option is to avoid dar issuing such warning
in that situation.
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
proceeding, except if -w is used. If -n is used, no file will be
deleted (nor overwritten), thus -k is useless when using -n. If -/
option is used, this option without argument is ignored! With the
"only" argument, this option only consider files marked as to be
removed in the archive to restore, no file are restored but some file
are removed. When -konly (or --deleted=only) is used, the -/ option is
ignored (at the opposition of the "--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 overwriting (-n
option) is used. No rename scheme is planned actually. When this
option is set, dar does not remove files that have been stored as
deleted since last backup. (-f implicitly implies -k).
-ae, --alter=erase_ea
[DEPRECATED use -/ instead] Drop all existing EA of files present in
filesystem that will have to be restored. This way, the restored files
will have the exact set of EA they had at the time of the backup. If
this option is not given, a file to restore will have its EA
overwritten by those present in the backup and if some extra EAs are
present they will remain untouched. See the Note concerning Extended
Attributes (EA) above for a detailed explanation about this behavior.
If -/ option is used, this option is ignored!
-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 confirmation before restoring it. Specifying "ignore" will skip
those dirty files, while "no-warn" will restore them without user
confirmation. This feature is incompatible with sequential reading
mode, in this mode dar cannot know whether a file is dirty before
having restored it, in consequences, 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 restoration 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
compatibility). Note that the files doc/dar-catalog-*.dtd define the
format of the XML output listing (This file is also installed under
$PREFIX/share/doc)
-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 displays an archive
summary first, where a detailed of information about the archive can be obtained. If you
want to display only this summary use -q with -l option.
displayed fields
[data] possible values are [ ] or [Saved] or [InRef] or[DIRTY]. [ ]
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
catalogue 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 reference, if there is no EA saved for this
file (empty string) or if some EA were present in the archive of
reference but none is currently available ([Suppr]). [InRef] was used
when isolating a catalogue (release 2.3.x and before) from an archive
and means that the file was saved in the reference archive.
[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
compressed 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 compression because it is not a saved
regular file ([----]), or if the file takes more space compressed than
its original size ([worse]), due to compression overhead. Note that
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 provide 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 circumstances (saving an dar archive inside a dar archive without
compression or encryption, for example) a file without hole may be
marked [X] as if it had holes and will be longer by on byte for each
data sequence looking like an escape sequence.
permission
see ls man page. Note that a star (*) is prepended to the permission
string if the corresponding inode is linked several times to the
directory structure (hard link).
user owner of the file
group group owner of the file
size size in byte of the file (if compression is enabled, the real size in
the archive is "compression rate" time smaller).
date the last modification date of the file. The last access time is also
saved and restored, but not displayed.
filename The name of the file.
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 argument is provided. In consequences, you need a space between
the option (like "-z") and its argument (like "9"), when dar does not rely on a GNU
getopt() call, which also imply you to explicitly use arguments to options listed just
above.
EXIT CODES
dar exits with the following code:
0 Operation successful.
1 Syntax error on command-line.
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
comparing, it is the case when a file in the archive does not match the one in
the filesystem. While testing, it is the case when a file is corrupted in the
archive.
6 an error occurred while executing user command (given with -E or -F option).
Mainly because the creation of a new process is not possible (process table is
full) or the user command returned an error code (exit status different of
zero).
7 an error has occurred when calling a libdar routine. This means the caller (dar
program), did not respect the specification of the API (and this can be
considered as a particular case of 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 forgotten 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 program, except for the following signals:
SIGINT This signal is generated by the terminal when hitting CTRL-C (with the
terminal's default settings), it can also be generated with the kill command
SIGTERM This signal is generated by the system when changing of run-level in particular
when doing a shutdown, it can also be generated with the kill command
SIGHUP Depending on the system, this signal may be sent before the SIGTERM signal at
shutdown time, it can also be generated with the kill command
SIGQUIT This signal is generated by the terminal when hitting CTRL-\ (with the
terminal's default settings), it can also be generated with the kill command
SIGUSR1 This signal can be generated by the kill command
SIGUSR2 This signal can be generated by the kill command
For those previous signals, two behavior exit. For SIGHUP, SIGINT, SIGQUIT, SIGTERM and
SIGUSR1, a delayed termination is done: the backup or isolation operation is stopped, the
catalogue is appended to the archive and the archive is properly completed with the
correct terminator string, this way the generated archive is usable, and can be used as
reference for a differential backup at a later time. Note that if an on-fly isolation had
been asked, it will *not* be performed, and no user command will be launched even if dar
has been configured for (-E option). For SIGUSR2 instead a fast termination is done: in
case of backup or isolation, the archive is not completed at all, only memory and mutex
are released properly.
For both type of termination and other operations than backup or isolation, dar's behavior
is the same: For restoration, all opened directories are closed and permissions are set
back to their original values (if they had to be changed for restoration). For listing,
comparison, testing, the program aborts immediately.
Another point, when using one of the previous signals, dar will return with the exist
status 4 meaning that the user has aborted the operation. Note that answering "no" to a
question from dar may also lead dar to exit this way. last, If before the end of the
program the same signal is received a second time, dar will abort immediately.
FILES
$HOME/.darrc and /etc/darrc if present are read for configuration option. They share the
same syntax as file given to -B option. If $HOME/.darrc is not present and only in that
case, /etc/darrc is consulted. You can still launch /etc/darrc from .darrc using a
statement like -B /etc/darrc. None of these file need to be present, but if they are they
are parsed AFTER any option on the command line and AFTER included files from the command
line (files given to the -B option). NOTE: if $HOME is not defined $HOME/.darrc default to
/.darrc (at the root of the filesystem).
Else you can see conditional syntax 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 several lines, and eventually mixed with
comments (see -B option for more). But, you can also use make-like targets to ask for a
particular set of commands to be used in certain conditions.
A condition takes the form of reserved word immediately followed by a colon ':'. This word
+ colon must stand alone on its line, eventually with spaces or tabs beside it. The
available conditions are:
extract: all 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 command and options. They are collected from
command-line first, then comes the parsing of command and optional arguments. Their use is
to extend conditional syntax described just above by having a set of options activated by
the user just adding a single word on command-line. Of course user targets must not be
equal to one of the reserved words of the conditional syntax (extract, create, ... all,
default). A valid target is a word (thus without space) composed of lowercase or uppercase
letters (case is sensitive) with eventually digits, dashes '-' or underscores '_'
characters.
Let's see an example of use:
first a DCF file named 'example.dcf' that will be given on command line:
# normal set of files considered for backup
create:
-R /
-P proc
-P sys
-P mnt
-D
# if the "home" user target is applied on command line the following command get
added
home:
-g home
# if the "verbose" user target is used, we will have some more verbosity ...
verbose:
-v
-vs
Then we could run dar in the following ways:
dar -c test -B example.dcf
in that case only the command in the "create:" section of example.dcf
would be used.
dar -c test -B example.dcf verbose
here over the "create:" target the commands under the "verbose:"
target (-v and -vs) would be also used
dar -c test -B example.dcf verbose home
last we use two user targets "verbose:" and "home:" in addition the
the "create:" target of the usual conditional syntax.
Note that if the last option *may* receive an argument, the first user target that follows
it will be assumed an argument to that option. To avoid this, either change the order of
options on command line for the last option been an option that never or always uses an
argument (for example -b never has an argument while -s always has one). Or separate the
options from the user targets by the -- word. And of course you can also use the explicit
argument of the last option (see EXPLICIT OPTIONAL ARGUMENT section, above).
Second point: It is allowed to have user targets inside a DCF file. Note however that
targets are collected in a first phase, which leads some part of the file to be hidden
(because the corresponding conditional syntax or user target is not present). Then, the
remaining part of the file is then parsed and actions for each option found is taken. At
that time, new user targets found are just recorded, but they do not modify the current
DCF file layout, in particular, hidden part of the file stay hidden even if the
corresponding user target is read in this same file. Next DCF parsing (which may be
triggered by a second -B option on the command line, or by a -B option inside the current
parsed DCF file) will thus be done with the additional targets found in that first DCF
file, so in a way you may have user targets that activate other user targets. Here follows
an examples of two DCF files, first.dcf and second.dcf:
# cat first.dcf
target3:
-K toto
target1:
target2
-B second.dcf
target3
target2:
#never reached
-s 10k
# cat second.dcf
target2:
-v
target3:
-b
In that example, target1 activates both target2 and target3, but at the time of the
parsing of first.dcf, neither target2 nor target3 were yet activated thus '-K toto' and
'-s 10k' will never be given to dar (unless activated beside target1 before first.dcf get
parsed), however when comes the time to parse second.dcf, target2 *and* target3 are
activated, thus both '-v' and '-b' will be passed to dar, even if 'target3' is located
after '-B second.dcf' in the file first.dcf
ENVIRONMENT
DAR_DCF_PATH
if set, dar looks for Dar Configuration File (DCF files, see -B option) that do
not have an fully qualified path in the directories listed in DAR_DCF_PATH
environment variable. This variable receives a 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 available in dar's source package, and are also
installed beside dar in the <--prefix>/share/dar directory. This documentation is also
available on-line at http://dar.linux.free.fr/doc/index.html#2
SEE ALSO
dar_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 BUGS
dar 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