DragonFly On-Line Manual Pages
DAR(1) DragonFly General Commands Manual DAR(1)
NAME
dar - creates, tests, lists, extracts, compares, merges, isolates dar
archives
SYNOPSIS
dar [-c | -t | -l | -x | -d | -+ | -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, hard-disks, usb keys, etc.) and since release
2.4.0 also adapted to tapes.
dar can store a backup in several files (called "slices" in the
following) of a given size, eventually pausing or running a user
command/script before starting the next slice. This can allow for
example, the burning of the last generated slice on a DVD-R(W), Blue-
ray Disk, or changing of usb key before continuing on the next one.
Like its grand-brother, the great "tar" command, dar may also use
compression, at the difference that compression is used inside the
archive to be able to have compressed slices of the defined size.
But the most important feature of dar is its ability to make
differential and decremental 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 the differential backup was made. And of course, the reference
backup may be a full or a differential backup itself, so you can make
the same way incremental backups.
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 nor to
stick together the different parts (the slices) to get 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. The "catalogue" can be copied out of the archive
(operation called isolation) to be used as reference for further backup
and as backup of the internal catalogue in case of archive corruption.
Dar can also use a sequential reading mode, in which dar acts like tar,
just reading byte by byte the whole archive to know its contents and
eventually extracting file at each step. In other words, the archive
contents is located at both locations, 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 know anything about tar archive structure, neither tar knows
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).
Dar format is quite robust against corruption: Only the file where the
corruption took place in the archive will not be possible to restore.
To have the possibility to repair a corrupted archive dar can work with
par2 seamlessly just specifying "par2" on command-line (see
/etc/darrc). Last a "relax" reading mode is available which let dar to
either ignore some incoherence in archive structure, use internal
redundant information to overcome data corruption or in last resort
asking the user on what to do when some archive structure information
is missing (-al option). This relax mode can be used with both
sequential and direct access read modes. Note that you should rather
use Parchive to protect your data rather than just relying on the
"relax" mode, which has to be seen as a the last chance solution.
dar takes care of POSIX Extended Attributes (EA in short) that are used
in particular under Linux to carry File Access Control List (FACL) as
well as security attributes for SELinux, and also under MacOS X EA they
are used to store file forks. EA also have room for user to add any key
/ value paire to any file, this is known as user EA. These attributes
are not specific to any particular filesystem, they exist the same way
under ext3/4, HFS+ and any other filesystem.
dar also takes care of Filesystem Specific Attributes (FSA in short)
which are, as you can guess, specific to one or several filesystem(s).
For example the Birth date of a file exists for HFS+ and NTFS but not
for ext2/3/4 filesystem. The immutable attribute exists for ext2/3/4
but not for NTFS while the nodump files does not exists for NTFS but
exists for HFS+, ext2/3/4 and many other Unix filesystems.
Sparse files (files with holes that system reports using several
hundred gigabytes while they effectively use a few kilobytes on disk)
are also well managed by dar: they are detected, stored and restored to
filesystem properly.
dar is also able to properly save and restore hard-links
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.
The rest of this document is organized that way:
COMMANDS
The seven actions you can performs with dar
GENERAL OPTIONS
A set of options common to all actions
SAVING, ISOLATING AND MERGING SPECIFIC OPTIONS
A set of options that are specific to the operation of
backup, catalogue isolation and archive merging
RESTORATION SPECIFIC OPTIONS
A set of options that are specific to the restoration
operation
TESTING AND DIFFERENCE SPECIFIC OPTIONS
A set of options that are specific to the operation of
archive testing and archive comparison with a filesystem
LISTING OPTIONS
A set of options that are specific to archive listing
operation
EXPICIT OPTIONAL ARGUMENTS
Some system do not allow optional arguments to options,
this chapter explain how to overcome this restriction
EXIT CODES
List of values dar returns at end of execution. This
chapter should be read if you intend to create scripts
relying on dar
SIGNALS
details the signal and their action on a running dar
process
FILES
List configuration files that dar checks for
CONDITIONAL SYNTAX
Over command line, command and options can be passed to dar
thanks to a plain file (known as DCF file). This plain file
can also contain a specific syntax that will let you pass
an option to dar only under certain situation/condition.
This chapter describes this simple syntax and the different
available conditions.
USER TARGETS
User can add their own conditions known as user targets.
This chapter describes what they are and how to use them
ENVIRONMENT
Dar may rely on environment variables to look for DCF files
and DUC files
OPTIONS
COMMANDS:
Only seven 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.
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 directly or
using the dar_split command).
-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, USB key, etc.), in
this case, to be able to mount/unmount the device,
you must not launch dar from that directory. In
other words, the current directory must not on the
removable media you plan to unmount (see tutorial
for details). The basename may be set to "-", in
direct access mode (the default historical mode),
you will then need dar_slave to work with dar (see
-i and -o options, as well as dar_slave man page).
However in sequential read mode (--sequential-mode
is used on command-line), dar will read the archive
from standard input (see also -i option), this can
eventually be used in combination with dar_split.
-l, --list [<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 data, file EA and file
FSA in the catalogue. Archive structure (slice
header, archive header, catalogue) is also
protected by CRC to be able to detect any kind of
archive corruption. Same remark here, "-" may be
used as basename (see -x option above for details).
-d, --diff [<path>/]<basename>
compares saved files in the backup with those on
the filesystem. <basename> may also be "-" (see -x
option above for details). Note that the target for
this operation is to be seen as a step further than
archive testing, where in addition to archive
coherence, the archive contents is verified to be
the same as what is found on the filesystem. But if
new files are present on the filesystem, dar
ignores them. If you want to check for changes
since a archive has been made, better use dry-run
differential backup.
-C, --isolate [<path>/]<basename>
isolate a catalogue from its archive (that's to say
make a copy of the internal catalogue to its own
archive container). The argument is the basename of
the file to create which will contain the
catalogue's copy. The -A option is mandatory here
to give the name of the archive to copy the
catalogue from, this archive is not modified at
all. Slicing is available (-s -S -p -b etc.). If
the filename is "-" *and* no slice is asked (no -s
option) the isolated catalogue is produced on the
standard output, allowing the user to send the
resulting archive through a pipe. Note that there
is quite no difference in concept between an
isolated catalogue and an archive. Thus you can do
all operations on an isolated catalogue, in
particular take it in place of the original backup
as reference for a differential archive, archive
testing, archive comparison. Note however that for
comparison (-d option) as data is not present in
the isolated catalogue, dar relies on embedded CRC
rather than comparing data byte by byte (what is
done with a plain archive), and no comparison can
be performed concerning EA or FSA even if each of
them have their own CRC in the catalogue because
different ordering as provided by the OS of the
items composing EA and FSA may lead the CRC to be
different while the EA or FSA are exactly the same,
so CRC here is used only to dectect archive
corruption. Since release 2.4.0 you can use an
isolated catalogue to rescue a corrupted internal
catalogue of the archive it has been based on (see
-A option).
-+, --merge [<path>/]<basename>
create a subset archive from one or two existing
archives (the resulting archive name is the
argument to this command). The dar file selection
mechanism (see GENERAL OPTIONS) let the user decide
which files will be present in the resulting
archive and which one will be ignored. This option
thus let the user merge two archives in a single
one (with a filtering mechanism that accepts all
files), as well as this option let the user create
a smaller archive which data is taken from one or
two archives of reference. Note that at no time the
contents of the archives of reference is extracted
to real files and directories: this is an archive
to archive transfer, thus you may lack support for
Extended Attribute while you will be able to fully
manipulate files with their Extended Attributes
from one archive to the resulting one. If the
basename is "-" *and* no slice is asked (no -s
option), the archive is produced on standard output
allowing the user to send the resulting archive
through a pipe. The first mandatory archive of
reference is provided thanks to the -A option,
while the second "auxiliary" (and optional) archive
of reference is provided thanks to the -@ option.
When a tie contention occurs (same file names from
both archive have to be merged), the overwriting
policy (-/ option) is used to define the one to
keep in the resulting archive. By default, archive
data selected for merging is uncompressed, and re-
compressed. Thus the merging operation can be used
to change compression algorithm of given archive as
well as change its encryption. But, for better
performance it is also possible thanks to the -ak
option (see below the -ak option for usage
restrictions) to merge files keeping them
compressed, thus no decompression/re-compression is
performed at all, which make the operation faster.
Last it is not possible to merge two isolated
catalogues.
-h, --help displays help usage.
-V, --version displays version information.
GENERAL OPTIONS:
-v, --verbose For backward compatibility, this is an alias to
"-vt -vm" (both options set).
-vs, --verbose=skipped
Display files skipped because of file filtering
exclusion specified by the user
-vt, --verbose=treated
Display treated files because of file filtering
inclusion specified by the user or no file
filtering specified at all. For each file a message
is displayed *before* the file is treated. This
option is not available for archive isolation and
is useless for archive listing as it is always set,
unless -q is used.
-vd, --verbose=dir Display the directory under process. The messages
shows *before* entering a directory. You can have a
less verbose output than -vt while are still able
to follow what's dar is doing. Note that -vt and
-vd are mutually exclusive.
-vm, --verbose=messages
Display detailed messages about what dar is
currently performing but not related to currently
treated or skipped files and directories
-vf, --verbose=finished
Issues a summary *after* each treated directory
containing the amount of data backed up in that
directory as well as the average compression ratio.
This option is only available for archive creation.
-va, --verbose=all activates all the previously described verbose
options, see also -Q and -q options below. Note:
When using dar from a script better use dar's exit
status to know which way the operation has ended
(seen EXIT CODES at the end of this document).
-q, --quiet Suppress the final statistics report. If no verbose
output is asked beside this option, nothing is
displayed if the operation succeeds. When using dar
from a script better use dar's exit status to know
which way the operation has ended (seen EXIT CODES
at the end of this document)
-b, --beep makes the terminal ring when user action is
required (like for example the creation of a new
slice using the -p option)
-B, --batch <filename>
In the file which name is given in argument to this
option, You can put any option or argument as used
on command line, that will be parsed as if they
were in place of the "-B <filename>" option. This
way you can overcome the command line size
limitation. Commands in the file may be disposed on
several lines, and -B option can also be used
inside files, leading a file to include other
files. But an error occurs in case of loop (a file
that includes itself directly or not) and DAR
aborts immediately. Comments are allowed, and must
start by a hash `#' character on each line. Note
that for a line to be considered as a comment the
hash character must be the first character of the
line (space or tab can still precede the hash). See
Conditional Syntax below for a more rich syntax in
this type of configuration files known as DCF file
(Dar Configuration File). See also the environment
variable DAR_DCF_PATH in the ENVIRONMENT section at
the end of this document.
Note that you can use quotes simple ('arg') double ("arg") and back-
quotes (`arg`) inside such file, but they need to be balanced (have an
ending one). To use such character without the meaning of a quote, for
example as an apostrophe, you need to escape it using a back-slack
("That\'s an example"). Of course to add a single back-slash as a
normal character in the file you will have to double it ("c:\\windows"
for example)
-N, --noconf Do not try to read neither ~/.darrc nor /etc/darrc
configuration files. See files section below.
-Q Do not display an initial warning on stderr when
not launched from a terminal (when launched from a
cronjob for example). This means that all questions
to the user will be answered by 'no', which most of
the time will abort the program. Please note that
this option cannot be used in a configuration file
(-B option). Since version 2.2.2, giving this
option also forces the non-interactive mode, even
if dar is launched from a terminal. This makes it
possible for dar to run in the background. When you
do, it's recommended to also redirect stdout and/or
sterr to files: dar -Q ... &> /dev/null &
-n, --no-overwrite do not allow overwriting
If an overwriting policy is specified (see -/
option) -n option do only apply to slices
overwriting, the overwriting of files during
restoration or merging is handled by the
overwriting policy. Without overwriting policy, -n
applies to restored files as well as generated
slices.
-w, --no-warn Do not warn before overwriting (applied for slice
overwriting and for overwriting decision make by
the overwriting policy). By default overwriting is
allowed but a warning is issued before proceeding.
This option may receive 'a' as argument (see just
below):
-wa, --no-warn=all This implies the -w option, and means that over
avoiding warning for file overwriting, DAR also
avoids signaling a file about to be removed when
its type is not the expected one. File are removed
when they have been recorded as deleted since the
archive of reference. At restoration of the
differential archive, if a file of the given name
exists, it is remove, but if the type does not
match the file that was present at the time of the
archive of reference (directory, plain file, fifo,
socket, char or block device, etc.), a warning is
normally issued to prevent the accidental removal
of data that was not saved in the backup of
reference. (See also -k option)
-A, --ref [<path>]/<basename>
Depending on the context, it specifies the archive
to use as reference, which is mandatory for archive
isolation (-C option) and merging operation (-+
option). Else it specifies the rescue catalogue to
use when restoring (-x command), testing (-t
command) or comparing (-d command) an archive. All
slices of the reference backup are expected to be
on the same directory given by <path> or the
current directory by default. Usually only the last
slice is required to extract the catalogue of
reference. If necessary the use of symbolic links
is also possible here to gather slices that do not
reside in the same directory. You can also point
<path> to a USB key, DVD-R(W) or any other mounted
directory, because dar will pause and ask the user
for required slices if they are not present. The
argument to -A may be of four types:
- An existing archive basename, which will
be taken as reference
- a dash ("-") in direct access mode
(default mode, when --senquential-read is
not used) it may imply the use of -o and -i
options, this allows the archive of
reference to be read from a pair of pipes
with dar_slave at the other ends. Dar_slave
can be run through ssh on a remote host for
example. Note that this type of argument
("-") is only available when -A is used for
isolation (-C option) and merging (-+
options). In sequential mode (--sequential-
mode is used), the archive of reference is
read from standard input or from the named
pipe specified by -i option. -o option has
no use in sequential mode. Note that merging
operation (-+ option) cannot read archive of
reference in sequential mode.
- a plus sign ("+") which makes the
reference be the current directory status.
This argument is only available for archive
creation (-c option). In other word, no
file's data will be saved, just the current
status of the inodes will be recorded in the
catalogue. This feature is known as the
"snapshot" backup. A snapshot backup can be
used as reference later on to detect or save
only the files that have changed since the
snapshot was made.
- a <date>, if -af option has been placed
before -A on the command-line or in a
included file (see -B option). For more
about that feature see -af option below.
This form is only available for archive
creation (-c option).
During backup operation (-c option) the archive of
reference, given thanks to the -A option, is used
for comparison with existing files on the
filesystem. Dar will then backup only files that
have changed since the archive of reference was
done. If no -A option is given, the backup
operation is a full backup. With -A option if the
archive of reference is a full backup some call it
a differential backup, while if the archive of
reference is differential backup, some call this
type of backup an incremental backup. For dar there
is no difference in structure between incremental
and differential backup, both are usually designed
globally as "differential" backup in the
documentation.
During merging operation (-+ option), the contents
of the -A given archive will been taken eventually
with the contents of the -@ auxiliary archive if
specified (see below), to form a new archive from
files of this or these archives. Note that you can
filter out files from the operation and setup
subset of the original archive(s).
During Catalogue isolation (-C option), dar will
create the isolated catalogue from the one given
with -A option.
During testing, diff or extraction, (-t, -d or -x
options respectively), the table of contents (the
catalogue) will be read from the archive given with
-A instead of using the internal catalogue of the
archive. The archive given for rescue must has been
previously isolated from this same archive (else
the contents will not match and dar will refuse to
proceed to this operation). This acts as a backup
solution to the case of corruption inside an
archive's catalogue, while the best way is still to
use Parchive to protect your data against media
error.
-af, --alter=fixed-date
Modify the -A option behavior, making it receiving
a <date> as argument in place of the
[<path>]/<basename> default argument. The <date> is
used to define which file to save: file which
modification is newer or equal to <date>, and which
to consider unchanged: those older than <date>.
This option has only a meaning when creating an
archive (-c option) and must be placed before -A
option to have an effect.
<date> must be a date in the two following possible
formats:
- a number of second since Jan 1st, 1970
- a date in the following form
[[[year/]month/]day-]hour:minute[:second]
Here are some examples of date:
91836383927108078
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
-@, --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). Note that --aux and
--on-fly-isolate are really aliases to the same
option, this is the context of use (archive
creation or merging) which lead it to behave a way
or another.
In a merging context, over -A option which is
mandatory, you may give a second archive of
reference thanks to the -@ option. This allows you
to merge two archives into a single one. See also
-$ option (encryption) -~ option (command
execution) and -% (crypto block size) for other
options concerning auxiliary archive of reference.
They are the respective equivalent of -J, -F and -*
options relative to archive given thanks to -A
option.
In a backup context -@ option let the user specify
the archive name for an on-fly isolation. With on-
fly isolation, you can also use -$ option (to
define encryption algorithm and passphrase), -~
option (to execute a command once the on-fly
isolated catalogue is completed) and -% option
(crypto block size). On-fly isolated catalogue is
always bzip2 if possible else gzip else lzo
compressed (using compression level 9) else not
compressed, and it is also always a single sliced
archive. Due to command-line exiguity, it is not
possible to change compression algo nor slice size
for the on-fly isolation. If you need a more
complicated isolation, either look for a GUI over
libdar, or do a normal (= not an on-fly) isolation
operation (By the way it is possible to isolate an
already isolated catalogue, this is equivalent to
doing a copy, but you can change encryption,
compression or slicing, for example), you can also
use dar_xform on an isolated catalogue if you only
want to change slices size (this is faster as no
decompression/re-compression nor
encryption/decryption is necessary). Using the
merging operation on an isolated catalogue instead
of isolating the isolated catalogue, leads the
resulting archive to not be able to be used as a
rescue for internal catalogue of the original
archive. --aux-ref is a synonym to --aux.
-R, --fs-root <path>
The path points to the directory tree containing
all the files that will be enrolled in the
operation (backup, restoration or comparison). By
default the current directory is used. All other
paths used in -P or -g options on the command line
are and must be relative to this path (or to
current directory if -R is not present). Note that
-R is useless for testing (-t option) isolation (-C
option) and merging (-+ option)
-X, --exclude <mask>
The mask is a string with wildcards (like * and ?
see glob(7) for details) which is applied to
filenames which are not directories. If a given
file matches the mask, it is excluded from the
operation. By default (no -X on the command line),
no file is excluded from the operation. -X may be
present several times on the command line, in that
case a file will not be considered for the given
operation if it matches at least one -X mask. See
also -ar and -am options.
-I, --include <mask>
The mask is applied to filenames which are not
directories (see glob(7) for details on wildcard
characters). If a given file matches the mask and
does not match any mask given with -X, the file is
selected for the operation. By default (no -I and
no -X on the command line), all files are included
for the operation. -I may be present several times
on the command line, in that case all 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, which defaults to current directory.
Warning, -g option cannot receive wildcards, these
would not be interpreted.
-[, --include-from-file <listing_file>
Files listed in the listing file are included for
the operation. No wildcard expression is
interpreted in the listing file, the null character
is not allowed and the carriage return is used to
separate file names (one file name per line). 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. 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 or -[ option must cover it, else it is
not elected for operation. If a directory is not selected,
no recursion is done in it (the directory is pruned). For
non directories files, the same is true (P, -g, -[ and -]
do apply) and a second test must also be satisfied: no -X
option must exclude the filename, and if at least one -I
option is given, one must match the given filename (using
or not wildcards).
the ordered method (when -am option is given on command-line):
The ordered method takes care of the order of presence
between -X and -I in one hand and of -P, -g, -[ and -] in
the other hand (note that it has also the same action
concerning EA selection when using -u and -U options, but
that's no more file selection). In the ordered method the
last argument take precedence over all the previous ones,
let's take an example:
-X "*.mp?" -I "*.mp3" -I "toto*"
Here dar will include all files except file of name
"*.mp?" (those ending with "mpX" where X is any
character), but it will however include those ending
with ".mp3". It will also include files which name
begin by "toto" whatever they end with. This way,
"toto.mp2" will be saved (while it matches "*.mp?" it
also begins by "toto") as well as "toto.txt" as well
as "joe.mp3" (while it matches "*.mp?" it also ends by
"mp3"). But will not be saved "joe.mp2" (because it
does not begin by "toto", nor ends by "mp3", and match
"*.mp?" mask). As we see the last option (-I or -X)
overcomes the previous one. -P, -g, -[ and -] act
together the same but as seen above they do not only
act on filename, but on the whole path+filename. Note
that (-g, -P, -[, -]) and (-X , -I) are independent
concerning their relative order. You can mix -X -I -g
-P -] -[ in any order, what will be important is the
relative positions of -X options compared to -I
options, and the relative positions of -g -[ -] and -P
options between them.
In logical terms, if <prev_mask> is the mask generated by all
previous mask on the command line, -I <mask> generates the new
following mask: <prev_mask> or <mask> . While -X <mask>
generates the new following mask: <prev_mask> and not <mask>.
This is recursive each time you add a -I or -X option. Things
work the same with -P, -g, -[ and -] options.
This ends the file selection explication let's continue with other
options.
-u, --exclude-ea <mask>
Do not consider the Extended Attributes (EA) that
are matched by the given mask. By default, no EA
are excluded, if the support for EA has been
activated at compilation time. This option can be
used multiple times.
-U, --include-ea <mask>
Do only consider the EA that match the given mask.
By default, all EA are included if no -u or -U
option is present and if the support for EA has
been activated at compilation time. This option can
be used multiple times. See also the -am and -ae
options, they also apply to -U and -u options and
read below the Note concerning EA.
Note concerning Extended Attributes (EA)
Support for EA must be activated at compilation time (the
configure script tries to do so if your system has all the
required support for that). Thus you can get two binaries of dar
(of the same version), one supporting EA and another which does
not (dar -V to see whether EA support is activated). The
archives they produce are the same and can be read by each
other. The only difference is that the binary without EA support
is not able to save or restore EAs, but is still able to test
them and list their presence.
In the following when we will speak about Extended Attribute
(EA) or EA entry, we will only consider a particular Extended
Attribute key and its value. By opposition, the set of all EA
associated to a file will be designated by "EA set".
Since version 2.3.x the name of EA entries include the namespace
for dar be able to consider any type of EA (not only "system"
and "user" as previously). Thus the two previous options -u and
-U have changed and now take an argument which is a mask applied
to EA entry names written in the following form namespace.name
where "namespace" is for example "user". Note that the mask may
or may not include the dot (.) and may match arbitrary part of
the EA namespace+name, just remind that masks will be applied to
the "namespace.name" global string.
the -am flag here also enables the ordered method, for EA
selection too. The ordered versus normal method have been
explained above in the file selection note, with some examples
using -X and -I. Here this is the same with -U and -u, (just
replace -X by -u and -I by -U, the corresponding mask will apply
to Extended Attribute selection in place of file selection).
Another point, independently of the -am option the -ae option
can be used at restoration time only. If set, when a file is
about to be overwritten, all EA will be first erased before
restoring those selected for restoration in the archive
(according to the -U and -u options given). If not set, the EA
of the existing file will be overwritten, those extra EA that
are not in the archive or are not selected for restoration in
regard to the -u and -U options will be preserved. If you have
not used any -u/-U option at backup time and want to restore
from a set of full/differential backups the EA exactly as they
were, you have to use -ae for dar removes the EA before
overwriting their set of EA as stored in the archive. Without
-ae option dar will simply add EA to existing ones, thus get a
different set of EA for a give file than those recorded at the
time of the backup.
Last point the -acase and -an options alters the case
sensitivity of the -U and -u masks that follow them on the
command-line/included files as they do for -I, -X, -P, -g, -[
and -] as well. Very last point ;-), if -ac option is used
during backup dar set back the atime after having read each file
(see -aa/-ac options), this has as side effect to modify the
ctime date of each file. But ctime change is used by dar to
detect EA changes. In brief, the next time you backup a file
that had to be read (thus which contents changed), its EA will
be saved even if they had not changed. To avoid this side
effect, don't use the -ac option if not necessary.
This ends the Extended Attribute selection explication let's continue
with other options.
-4 --fsa-scope <family>[,<family>[, ...]
Reduce the scope of Filesystem Specific Attribute
(FSA) to be considered for the operation. FSA are
grouped by family. Current available families are:
extX this family takes care of Linux ext2/3/4 flag
attributes set by chattr(1) and read by
lsattr(1). Dar only considers flags that are
possible to set or clear by users (or
privileged user): append-only, compressed,
no_dump (Yes, dar can save files having the
nodump flag set and restore then afterward
with that flag set!), immutable, data-
journaling, secure-deletion, no-tail-merging,
undeletable, noatime-update, synchronous-
directory, synchronous-update, top-of-
directory-hierarchy. Note that "extx" and
"ext" are aliases for this FSA family. In
spite of its name, this family of attributes
is not limited to ext2/3/4 filesystems.
HFS+
this family takes care of Mac OS X HFS+ birth
date of files, in addition of commonly found
dates like atime (last access time), ctime
(last meta data change) and mtime (last data
change).
none "none" is not a FSA family but can be used
alone to ignore all FSA families.
By default no restriction is done and FSA of all
families are considered at restoration time, but if
a family has not been activated at compilation time
a warning is issued for each file that cannot have
its FSA restored completely (unless this family is
excluded from the scope thanks to the -4 option).
At backup time, if an FSA family has not been
activated at compilation time, no warning is issued
and FSA of that family are ignored. Still at backup
time, you can also ignore FSA that have compilation
time support by excluding them from the operation
thanks to this -4 option.
Example of use: --fsa-scope extX,HFS+
-am, --alter=mask set the ordered mode for mask. This affects the way
-I and -X options are interpreted, as well as -g,
-P, -[ and -] options, -Z and -Y options and -U and
-u options. It can take any place on the command-
line and can be placed only once. See the file
selection in brief paragraph above for a detailed
explanation of this option. It has also an
incidence on the --backup-hook-exclude and
--backup-hook-include options.
-an, --alter=no-case
set the filters in case insensitive mode. This
concerns only masks specified after this option
(see also -acase option below). This changes the
behavior of -I, -X, -g, -P, -Z, -Y, -u and -U
options.
Warning: case insensitivity requires interpreting filenames which
depends on the locale with which dar is run (defined by the LANG
environment variable). For example if you create files with LANG set to
fr_FR.UTF-8 and use non plain ASCII characters in filename, there is
chances that these non ASCII characters will be stored over several
bytes in that filename: so called "wide characters". If then you run
dar with LANG set to another value like ru_RU.koi8r, there is much
chances that these wide characters do not correspond to the same letter
or worse, that they do not match any valid wide character for that
locale. A filename is always a sequence of bytes and always saved as
such, but using --alter=no-case implies interpreting that sequence in a
way that depends on the given locale (as defined by the LANG
environment variable). As such, dar cannot know if a given file has to
be read with fr_FR.UTF-8 locale or with it_IT.iso88591 or ru_RU.koi8r
and so on, because this information is not stored in filenames. In
consequence, if different locales are used on your system and you are
doing a system wide backup, using --alter=no-case option may lead dar
to detect invalid wide character, in that case it falls back to a byte
by byte case sensitivity comparison (ASCII characters), which may not
be what you would expect at first sight: Most of the time, an upper
case wide character (stored on several bytes) does not match the
equivalent lower case wide character (several bytes too), when case
sensitivity comparison is performed byte by byte.
-acase, --alter=case
set back to case sensitive mode for filters. All
following masks are case sensitive, up to end of
parsing or up to the next -an option. This changes
the behavior of -I, -X, -g, -P, -Z, -Y, -u and -U
options.
-ar, --alter=regex set the filters to be interpreted as regular
expressions (man regex(7) ) instead of the default
glob expression (man glob(7) ) This modifies the
-I, -X, -g, -P, -Z, -Y, -u and -U options that
follows up to an eventual -ag option (see just
below). Note that for -P option, the given mask
matches the relative path part of the files path:
Let's take an example, assuming you have provided
/usr/local to the -R option, the mask "^foo$" will
replaced internally by "^/usr/local/foo$" while the
mask "foo$" will be replaced internally by
"^/usr/local/.*foo$".
-ag, --alter=glob This option returns to glob expressions mode (which
is the default) after an -ar option has been used,
this applies to any -I, -X, -g, -P, -Z, -Y, -u and
-U options that follow up to an eventual new -ar
option (see just above).
-i, --input <path> is available when reading from pipe (basename is
"-" for -x, -l, -t, -d or for -A when -c, -C or -+
is used). When reading from pipe, standard input is
used, but with this option, the file <path>
(usually a named pipe) is used instead. This
option is to receive output from dar_slave program
(see doc/usage_notes.html for examples of use).
Note that when --sequential-read is used, dar uses
a single pipe and does no more rely on dar_slave,
-i option can be used to tell dar which named pipe
to read the archive from, instead of the standard
input.
-o, --output <path> is available when reading from pipe (basename is
"-" for -x, -l, -t, -d or for -A when -c, -C or -+
is used). When reading from pipe, standard output
is used to send request to dar_slave, but with this
option, the file <path> (usually a named pipe) is
used instead. When standard output is used, all
messages goes to standard error (not only
interactive messages). See doc/usage_notes.html for
examples of use. This option is not to be used in
--sequential-read mode.
-O, --comparison-field[=<flag>]
When comparing with the archive of reference (-c
-A) during a differential backup, when extracting
(-x) or when comparing (-d) do only considers
certain fields. The available flags are:
ignore-owner all fields are considered except
ownership. This is useful when dar
is used by a non-privileged user. It
will not consider a file has changed
just because of a uid or gid
mismatch and at restoration dar will
not even try to set the file
ownership.
mtime only inode type and last
modification date is considered as
well as inode specific attributes
like file size for plain files.
Ownership is ignored, permission is
ignored. During comparison,
difference on ownership or
permission is ignored and at
restoration time dar will not try to
set the inode permission and
ownership.
inode-type Only the inode type is considered.
Ownership, permission and dates are
ignored. Inode specific attributes
are still considered (like file size
for plain files). Thus comparison
will ignore differences for
ownership, permission, and dates and
at restoration dar will not try to
set the ownership, permission and
dates.
When no flag is provided to this option, -O option acts as if the
"ignore-owner" flag was set, which is the behavior in older releases (<
2.3.0). Note also that for backward compatibility, --ignore-owner
option still exists and since version 2.3.0 is just an alias to the
--comparison-field=ignore-owner option. Of course if this option is not
used, all fields are used for comparison or restoration.
-H[num], --hour[=num]
if -H is used, two dates are considered equal if
they differ from a integer number of hours, and
that number is less than or equal to [num]. If not
specified, num defaults to 1. This is used when
making a differential backup, to compare
last_modification date of inodes, at restoration or
merging time if overwriting policy is based on
file's data or EA being more recent and last, when
comparing an archive with a filesystem (-d option).
This is to workaround some filesystems (like Samba
filesystem) that seems to change the dates of files
after having gone from or to daylight saving time
(winter/summer time). Note that -H option has
influence on the overwriting policy (see -/ option)
only if it is found before on command-line or in an
included file (using -B option).
-E, --execute <string>
the string is a user command-line to be launched
between slices. For reading an archive (thus using
-t, -d, -l or -x commands), the given string is
executed before the slice is read or even asked,
for writing an archive instead (thus using -c, -C
or -+ commands), the given string is executed once
the slice has been completed. Some substitution
macros can be used in the string:
%% will be replaced by %
%p will be replaced by the slice path
%b will be replaced by the slice basename
%n will be replaced by the slice number (to
be read or just written). For reading,
dar often needs the last slice, but
initially it does not know its number. If
it cannot be found in the current
directory, the user command-line is then
called with %n equal to 0. This is a
convenient way to inform the user command
to provide the last slice. If after
executing the string the requested slice
is still not present, dar asks the user
(as usually) with a message on the
terminal. Once the last slice is found,
the user command-line is called a second
time, with %n equal to the value of the
last slice number.
%N is the slice number with the leading zero
as defined by --min-digits option. If
this option is not used, %N is equivalent
to %n.
%e will be replaced by the slice extension
(always substituted by "dar")
%c will be replaced by the context. Actually
three possible values exist: "init",
"operation" and "last_slice". When
reading an archive for (testing,
extraction, diff, listing, or while
reading the archive of reference, see
below the -F option), the "init" context
takes place from the beginning up to the
time the catalogue is retrieved. On a
multiple slice archive this correspond to
the last slice request. After, that point
comes the "operation" context. While
creating an archive, the context is
always "operation" except when the last
slice has been created, in which case the
context is set to "last_slice".
Several -E option can be given, given commands will then be called in
the order they appear on the command line and -B included files. Such
file given to -E option are known as DUC files (Dar User Command). See
also the environment variable DAR_DUC_PATH in the ENVIRONMENT section
at the end of this document.
-F, --ref-execute <string>
same as -E but is applied between slices of the
reference archive (-A option). --execute-ref is a
synonym.
-~, --aux-execute <string>
same as -E and -F but is applied between slices of
the auxiliary archive (-@ option).
-K, --key [[<algo>]:]<string>
-K, --key gnupg:[<algo>]:email[,email[...]]
In the first syntax, encrypt/decrypt the archive
using the <algo> cipher with the <string> as pass
phrase. An encrypted archive can only be read if
the same pass phrase is given (symmetric
encryption). Available ciphers are "blowfish"
(alias "bf"), "aes", "twofish", "serpent" and
"camellia" for strong encryption and "scrambling"
(alias "scram") for a very weak encryption. By
default if no <algo> or no ':' is given, the
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.
Note that giving the passphrase as argument to -K
(or -J or '-$' see below) may let other users learn
pass phrase (thanks to the ps, or top program for
examples). It is thus wise to either use an empty
pass which will make dar ask the pass phrase when
needed, or use -K (or -J option) from a Dar Command
File (see -B option), assuming it has the
appropriated permission to avoid other users
reading it. For those paranoids that are really
concerned about security of their passwords, having
a password read from a DCF is not that secure,
because while the file gets parsed, dar makes use
of "unsecured" memory (memory than can be swapped
to disk under heavy memory load conditions). It is
only when the passphrase has been identified that
locked memory (aka secure memory) is used to store
the parsed passphrase. So, the most secure way to
transmit a passphrase to dar, then to libdar, then
to libgcrypt, is having dar asking passphrase at
execution time, dar then makes use of secured
(locked) memory from the beginning.
since archive format 9 (archive generated by
release 2.5.0 and following) at reading time, it is
not necessary to provide the encryption algorithm
used, just the passphrase is required, dar will
figure out which encryption algorithm had been used
at archive creation time. You can either ommit -K
in which case dar will ask for the passphrase at
execution time, or you can use -K <string> in a DCF
file as explained above (avoid using -K directly on
command-line).
The second syntax starts with the word "gnupg"
followed by a column ':' . In that situation, the
same set or symmetric encryption algorithms as
described above is available after the column, but
the passphrase is not given by the user but
randomly chosen by libdar and encrypted using the
public key of the target users which email is given
in a comma separated list. This random key (see
also --key-length below), once encrypted is placed
at the beginning and at the end of the generated
archive. At reading time only the listed user will
be able to read that archive thanks to their
respective private key. This feature implies that
each user (the archive creator as well as the
target users) have their GnuPG keyring set
properly. In particular, the archive creator must
have validated the public keys of the target users,
and the target users must own the corresponding
private key in their keyring. Example: using "--key
gnupg::bob@nowhere.org,joe@somewhere.com" will
generate a blowfish encrypted archive which
passprhase randomly chosen by libdar will be
encrypted with the public keys of bob@nowhere.org
and joe@somewhere.com. To use AES in place of
blowfish one could use "--key
gnupg:aes:bob@nowhere.org,joe@somewhere.com". Note
that no check is done about the trust you have set
in GPG keyring that a particular public key is
owned by the phyical person you expect. See also
--sign option below.
Note that if you have set a passphrase on your
private key, dar will ask it dynamically, which
requires dar to be run from a terminal. No other
way has been provided to transmit a private key's
passphrase to libdar. In consequence if you want to
use dar/libdar in scripts and make use of public
key algorithm you should avoid setting a passphrase
to the private key you want to use. See also
GNUPGHOME in the ENVIRONMENT section at the end of
this document.
Obvious but important! To read a gnupg encrypted
archive, you need your private key (not only the
passphrase to activate it, if set). Thus if you
plan to make backup of your system and encrypt the
backup using gnupg, you should have a copy of this
private key available out of the archive (usb key,
floppy, CD/DVD, ...) in order to be able to restore
your backup!
-J, --ref-key [[<algo>]:]<string>
same meaning/use as -K option's first syntax, but
the given key is used to decrypt the archive of
reference (given with -A option). --key-ref is a
synonym. Note that for archives generated using dar
release 2.5.0 and above this option is no more
necessary, unless you want to give the passphrase
on command-line (not recommended) or in DCF file
(which file would be set with restricted access
permissions and/or ACL).
-$, --aux-key [[<algo>]:]<string>
same as -J but for the auxiliary archive of
reference (given with -@ option). Here too, this
option is no more necessary to read archives
generated by dar release 2.5.0 and above.
-#, --crypto-block <size>
to be able to randomly access data in an archive,
it is not encrypted globally but block by block.
You can define the encryption block size thanks to
this argument which default to 10240 bytes. Note
that the syntax used for -s option is also
available here (k, M, G, etc.). Note also that
crypto-block is stored as a 32 bits integer thus
value larger than 4GB will cause an error. Note
last, that the block size given here must be
provided when reading this resulting archive, using
the -* option if the archive is the archive of
reference (given to -A option) using -% options if
the archive is the auxiliary archive of reference
(given to -@ option) or using this -# option if it
is the subject of the operation (listing,
comparing, testing that archive). If the value is
not the default and the given value is not correct
in regard to the value given at archive creation
time, the archive will not be possible to decrypt,
it is thus safer to keep the default value (and not
using at all the -#, -*, -% options).
-*, --ref-crypto-block <size>
same as --crypto-block but to read the archive of
reference (-A option). --crypto-block-ref is a
synonym.
-%, --aux-crypto-block <size>
same as --crypto-block but to read the auxiliary
archive of reference (-@ option).
-e, --dry-run Do not perform any action (backup, restoration or
merging), displays all messages as if it was for
real ("dry run" action). The --empty option is a
synonym.
-aSI, --alter=SI[-unit[s]]
when using k M G T E Z Y prefixes to define a size,
use the SI meaning: multiple of 10^3 (a Mega is
1,000,000).
-abinary, --alter=binary[-unit[s]]
when using k M G T E Z Y prefixes to define a size,
use the historical computer science meaning:
multiple of 2^10 (a Mega is 1,048,576).
The --alter=SI and --alter=binary options can be used several times on
the command line. They affect all prefixes which follow, even those
found in files included by the -B option, up to the next --alter=binary
or --alter=SI occurrence. Note that if in a file included by the -B
option, an --alter=binary or --alter=SI is encountered, it affects all
the following prefixes, even those outside the included files. For
example, when running with the parameters "-B some.dcf -s 1K", 1K may
be equal to 1000 or 1024, depending on --alter=binary or --alter=SI
being present in the some.dcf file. By default (before any
--alter=SI/binary option is reached), binary interpretation of prefixes
is done, for compatibility with older versions.
-ac, --alter=ctime When reading a filesystem (during a backup or
comparison), restores the atime of all files to
what it was before the file was read. This makes it
appear as if it had not been read at all. However,
because there is no system call to let applications
changing the ctime (last inode change) of a file,
setting back the atime results in the ctime being
changed (hence the alter=ctime). Some recent unix
system allow an application to get 'furtive read
mode' to the filesystem (see below). On older
systems, however, for most users, having the atimes
of the files changed shouldn't be a problem, since
they can be changed by any other program (running
by any user!) as well (like the content-index
program Beagle). Ctimes on the other hand, are the
only way for security software to detect if files
on your system have been replaced (by so called
root-kits mostly). This means, that should you run
dar with -ac, security software which uses ctimes
to check, will mark every file on your system as
compromised after the backup. In short, this means
this option should only be used by people who know
what they are doing. It's the opinion of this
writer that any software susceptible to atime
changes is 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 caching software. Therefore this
option exists.
-aa, --alter=atime When specifying -aa (by opposition to -ac), the
atime of every read file and directory is updated,
and the ctime remains the same. In other words, Dar
itself does nothing with atimes and ctimes, it only
let the system do its job to update atimes when
files are accessed for reading. This is in
accordance with what atimes and ctimes were meant
to represent. This is Dar's default (since version
2.4.0), unless 'furtive read mode' (see below) is
supported by your system and dar has been compiled
with this support activated.
Furtive read mode is a mode in which neither atime nor ctime are
modified while dar reads each file and directory. This provides also
better performances as nothing has to be wrote back to disk. A known
Unix kernel that supports this feature is Linux 2.6.8 and above
(support must also be present in the standard C library of the system
for dar to be able to activate this feature at compilation time). When
this feature is activated, it becomes the default behavior of dar for
super user ; for other users the default is -aa. If however as root
user, you do not want to use "furtive read mode" (while it has been
activated at compilation time), you can specify either -aa or -ac
option.
-at, --alter=tape-marks
For archive creation and merging, the default
behavior (since release 2.4.0) is to add escape
sequences (aka tape marks) followed by inode
information all along the archive. If -at is given,
dar will not add this information to the archive,
resulting in a slightly smaller archive and faster
backup. When reading an archive, the default
behavior is to ignore these escape sequences and
rather rely on the catalogue located at the end of
the archive. If instead --sequential-read is given
on command-line (see below), dar will avoid using
the catalogue at the end of the archive and will
rely on these escape sequences to know the contents
of the archive, which will lead to a sequential
reading of the archive, operation suitable for tape
media. Note that it is not recommended to disable
escape sequences (aka tape marks) by using -at
option except if you are more concerned by the
resulting size and execution speed of your backup
(in particular if you have a lot of small files)
than by the possibility to recover your data in
case of corrupted or partially written archive.
Without escape sequences, dar cannot sequential
read an archive, which is the only way beside using
an isolated catalogue to use an archive that has a
corrupted catalogue or has no catalogue at all,
thing that happens if a system crash occurred
during the archive creation or due to lack of disk
space to complete the archive.
-0, --sequential-read
Change dar's behavior when reading an archive. By
default, the traditional way is used, which relies
on the table of contents (aka "the catalogue")
located at the end of the archive. With the
--sequential-read option instead, dar will rely on
escape sequences that are inserted all along the
archive with each file's inode information. This
will lead to a sequential reading of the archive,
operation suitable for tape medium. However, this
feature is only available for archive format
starting revision "08" (i.e.: since release 2.4.0)
and if -at option has no been used during archive
creation or merging. This option is available for
archive testing (-t), comparison (-d), restoration
(-x), listing (-l) and to read the archive of
reference (-A option) for isolation (-C) and
archive creation (-c). The sequential reading of an
archive is always much slower than the usual
reading method, so you should not use this option
unless you really need it.
-9, --min-digits <num>[,<num ref>[,<num aux>]]
By default slice number contained in filename do
not have any padded zeros, which, when sorting a
directory contents alphabetically leads to read all
the 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.
--pipe-fd <num> will read further arguments from the file-
descriptor <num>. The arguments read through this
file-descriptor must follow a TLV
(Type/Length/Value) list format. This option is not
intended for human use, but for other programs
launching dar like dar_manager. This feature has
been added to overcome the command line length
limit.
-al, --alter=lax When reading an archive, dar will try to workaround
data corruption of slice header, archive header and
catalogue. This option is to be used as last resort
solution when facing media corruption. It is rather
and still strongly encourage to test archives
before relying on them as well as using Parchive to
do parity data of each slice to be able to recover
data corruption in a much more effective manner and
with much more chance of success. Dar also has the
possibility to backup a catalogue using an isolated
catalogue, but this does not face slice header
corruption or even saved file's data corruption
(dar will detect but will not correct such event).
--single-thread, -G When libdar is compiled against libthreadar, it can
make use of several threads. The number of thread
is not settable but depends on the number of
features activated (compression, encryption, tape
marks, sparse file, etc.) that require CPU
intensive operations. The load-balancing type per
thread used is called "pipeline". As performance
gain is little (not all algorithms are adapted to
parallel computing) this feature is flagged as
experimental: it has not been tested as intensively
as other new features and it is not encouraged for
use. If you want better performance, use several
dar processes each for different directory trees.
You'll get several archives instead of one which
isolated catalogues can be merged together (no need
to merge the backups, just the isolated catalogues)
and used as base for the next differential backup.
Note: if you want to silent the initial warning
about the fact this feature is experimental use -Q
option before -G option.
SAVING, ISOLATION AND MERGING SPECIFIC OPTIONS (to use with -c, -C or
-+)
-z[[algo:]level], --compression[=[algo][:][level]]
add compression within slices using gzip, bzip2,
lzo or xz 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. Be careful when using xz algorithm better
specify a compression ratio less than or equal to 6
to avoid important memory requirements. A ratio of
1 means less compression and faster processing,
while at the opposite a ratio of 9 gives the best
compression but longest procesing time. "Algo" is
optional, it specifies the compression algorithm to
use and can take the following values "gzip",
"bzip2", "lzo" or "xz". "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, -zxz:6 and
so on. Usage for long option is the same:
--compression, --compression=9, --compression=lzo,
--compression=gzip, --compression=bzip2,
--compression=lzo:6, --compression=bzip2:2,
--compression=gzip:1 --compression=xz:9 and so on.
--gzip[=level] Same as -z (see just above). This option is
deprecated, please use --compression or -z.
-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
(assuming your operating system can support
arbitrarily large files).
-S, --first-slice <number>
-S gives the size of the first slice which may be
chosen independently of the size of following
slices (either bigger or smaller). This option
needs -s option and by default of -S option, the
size of the first slice is the same as the one of
the following slices.
-p [<integer>], --pause[=<integer>]
pauses before writing to a new slice (this requires
-s). By default there is no pause, all slices are
written in the same directory, up to the end of the
backup or until the filesystem is full. In this
later case, the user is informed of the lack of
disk space and dar stops for user action. As soon
as some disk space is available, the user can
continue the backup. The optional integer that this
option can receive tells dar to only pause 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.
-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 in conjunction 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
masks given to -Z option(s)) are the only to be
compressed. It is only available with -z option. By
default all files are compressed. This option can
be used several times, in that case all files that
match one of the -Y will be compressed, if they do
not also match on of the -Z masks. The ordered
method here applies too when activated (with -am
option), it works exactly the same as -I and -X
options, but apply to file compression, not file
selection. In other word, it matches only on the
file name, not on the path of files.
-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 size
unit is the byte (octet) and the same number
extensions as those used with -s or -S are
available here, if you want to specify the size in
kilobyte, megabyte, gigabyte etc.
-1, --sparse-file-min-size <number>
Define the minimum length of zeroed bytes to
replace by "holes". By default, this feature is
activated with a value of 15 bytes. To completely
disable it, set the size to zero. Disabling this
feature will bring some noticeable speed
improvement but will probably make the archive
slightly bigger (depending on the nature of the
data). Sparse files are files that contain so
called holes. On a filesystem, the portion of
zeroed bytes is not stored on disk, thus an
arbitrary large file with huge portion of zeros may
only require a few bytes of disk storage. While dar
cannot detect how is allocated a given file because
it makes a filesystem abstraction (it does not know
the implementation of any particular filesystem,
where from its portability), 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.
--nodump do not save files which have the 'd' flag set (see
chattr(1) lsattr(1) ext2 commands). This option may
not be available if the system dar has been
compiled on did not provide support for ext2 flags.
Note that this option does nothing with -+ option
(merging) as no filesystem is used for that
operation.
-5, --exclude-by-ea[=<extended attribute name>]
exclude inodes from backup that have been set with
the EA given in argument. If not argument is given
to that option the default EA used to exclude files
from backup is "user.libdar_no_backup". To set this
attribute to a given file, use the following
command: "setfattr -n user.libdar_no_backup
<filename>", to remove it: "setfattr -x
user.libdar_no_backup <filename>". Last, to check
the presence this EA: "getfattr <filename>"
-M, --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)
-/ , --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 on one side and file's Attributes
(Extended and Filesystem Specific) on the other
side. An action is thus a couple of action for Data
and for EA+FSA. Actions for Data are represented by
uppercase letters, while action for EA+FSA are
defined by lowercase letters. Both actions are
independent of each other:
P means 'Preserve'. When merging two archives,
the data of the resulting archive will be
taken from the 'in place' file. While when
extracting, the data of the inode in
filesystem will be preserved (thus no
overwriting will occur for the data).
O means 'Overwrite'. When merging two archives,
the data of the resulting archive will be
taken from the 'to be added' file. While when
extracting, the data of the inode in
filesystem will be overwritten by data from
the archive.
S means 'mark Saved and preserve'. When merging
two archives, the data of the resulting
archive will be marked as already saved in the
archive of reference (making thus a
differential archive, even if none of the
original archive were differential archives).
All data will be dropped in the resulting
archive, but the last modification date [aka
mtime] (used to detect change in file's data)
will be taken from the 'in place' file. This
action does not apply when extracting files,
it is thus considered equal to "Preserve" (P)
in that situation.
T means 'mark Saved and overwrite'. When merging
two archives, the data of the resulting
archive will be marked as already saved (same
as 'S' action): all data will be dropped in
the resulting archive, however the last
modification date [aka mtime] (used to detect
changes in a file's data) will be taken from
the 'to be added' file. This action does not
apply when extracting files, it is thus
considered equal to "Overwrite" (O) in that
situation.
R means 'Remove'. When merging two archives, the
resulting archive will not contain any entry
corresponding to the file that were in
conflict. This also implies that no EA will be
stored for that particular entry as the entry
will no more exist in the resulting archive
(as if it had never yet existed). When
extracting files, this will lead to file's
suppression.
p means 'Preserve', same as 'P' (but lowercase
letter) preserve the whole EA set and FSA.
When merging two archives, the Attributes set
of the resulting file will be the ones of the
'in place' file (whatever is the overwriting
action taken for its data). While when
extracting files to filesystem, the Attributes
of the file in filesystem will not be changed
(whatever is the overwriting action taken for
its data, unless the file is removed using the
'R' policy, which would remove the inode and
thus also any Attributes it had).
o means 'Overwrite', same as 'O' (but lowercase
letter) overwrite the whole EA set and FSA.
When merging two archives, the Attributes set
of the resulting file will be taken from the
'to be added' file. While when extracting
files, the Attributes set of the file in the
filesystem will have its Attributes erased and
replaced by those of the file in the archive
(still independent of what overwriting action
is taken for file's data).
s means 'mark Saved and preserve', same as 'S'
(but lowercase letter) for EA and FSA instead
of data. When merging two archives, the EA and
FSA of the resulting file are marked as
already saved in the archive of reference,
thus they are dropped but the date of last
inode change [aka ctime] (used to detect
changes in file's EA and FSA) will be taken
from the 'in place' file. This action does not
apply when extracting files, it is thus
considered equivalent to "Preserve" (p) in
that situation.
t means 'mark Saved and overwrite', same as 'T'
(but lowercase letter) for EA and FSA instead
of data. When merging two archives, the EA and
FSA of the resulting file are marked as
already saved in the archive of reference,
thus they are dropped but the date of last
inode change [aka ctime] (use to track changes
in EA) will be taken from the 'to be added'
file. This action does not apply when
extracting files, it is thus considered an
equivalent to "Overwrite" (o) in that
situation.
m means 'merge Attributes and preserve'. The
resulting file in the merged archive will have
Attribute entries from both the 'in place' and
the 'to be added' files. If both files share a
same Attribute entry (same FSA or for EA the
same key for a given association) the one of
the 'in place' file is kept (where from the
'preserve' notion). When extracting a file,
the file in the filesystem will have its EA
and FSA set enriched by the ones of the file
in the archive that do not exist on
filesystem, but its already existing
Attributes will stay untouched.
n means 'merge Attributes and overwrite'. The
resulting file in the merged archive will have
Attribute entries from both the 'in place' and
the 'to be added' files. If both files share a
same Attribute entry (same FSA or for EA the
same key for a given association) the one of
the 'to be added' file will be kept (where
from the 'overwrite' notion). When extracting
file, the file in the filesystem will have its
Attributes set enriched by ones of the file in
the archive with some of them possibly been
overwritten.
r means 'remove', same as 'R' but for the
Attribute set (thus all EA and FSA entries) of
a given file ('r' is lowercase letter here).
The file of the resulting archive during
merging operation will not own any EA nor any
FSA, even if the 'in place' and/or the 'to be
added' files did have some. For file
extraction, this means that the file in the
filesystem will loose all its EA set. The FSA
cannot be 'removed' from a filesystem and may
not always have a default value, thus this
action does not modify FSA at all in case of
archive extraction. But in case of merging the
FSA are removed as previously described. As
for all the previous tests, this Attribute
operation is independent of the operation
chosen for file's data (uppercase letters).
d means 'delete'. When a same EA or FSA entry is
found both in the 'in place' and 'to be added'
files, such entry will be absent in the
resulting archive. In other words, when
merging, the EA set and FSA will only contain
EA and FSA entries specific to the 'in place'
and those specific to the 'to be added' file.
Entries in common will not be present. When
extracting a file from an archive, the file on
filesystem will have its EA set enriched by
entries of the 'to be added' file that are new
to the 'in place' file. The other EA entries
(which are thus present in both archive and
filesystem) will be removed from the set,
which the other FSA will stay untouched (FSA
cannot be "removed" from a filesystem, nor
they always have a default value).
* is valid for both EA and data. It tells that
the action is not yet defined at this step of
the evaluation and that further evaluation is
required (see the 'chain' operator below).
A means 'Ask for user decision'. This uppercase
letter concerns Data overwriting. An
application interaction let the user define
the action for each file in conflict. Note,
that this action if used alone may become very
boring or painful. The idea is to use it in
conditional statements (which are described
below) to have dar ask for only non obvious
cases.
a means 'Ask for user decision'. This lowercase
letter is the equivalent for EA and FSA of the
'A' action. It is intended to be used in the
same conditional statements described below.
An action is thus a couple of letters, the first
being uppercase (for file's data) the second being
lowercase (for file's EA and FSA). When -/ option
is not given, the action is equivalent to '-/ Oo',
making dar proceed to file, EA and FSA 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 lead dar to remove any file from
filesystem that ought to be restored(!). Note
the action for EA/FSA is useless, the EA and
FSA will always be erased as well as data
using 'R'. Thus '-/ Rp' would lead to the same
result.
-/ Po
will keep data of the 'in place' file and EA
and FSA set from the 'to be added' file.
-/ Ss
Using this option when merging an archive with
itself (used both as archive of reference (-A
option) and auxiliary archive of reference (-@
option) ) will provide the same action as an
archive isolation of the archive of reference,
but using twice more memory (so keep using the
isolation operation as before! Here this is
just an illustration of the possibility)
As seem previously -u and -U options can be used to
filter which EA entry to consider and which to
ignore. The question here is to explain how this
filtering mechanism interacts with the different
policies we just presented above. For files that
are not in conflict (found only as 'in place' or as
'to be added'), only the EA entries matching the EA
filter are kept. For files in conflict, the
overwriting policy is evaluated first, then the
filtering mechanism is applied *after* it. Thus for
example, using the following [ -/ "Po" -u "*test"
], when merging two archives, only EA ending with
"test" will be retained, and when a conflict takes
place, this "*test" ending EA will be taken from
the 'to be added' file if it has some EA of that
type, its other EA entry will be ignored as well as
any EA entry of the 'in place' file even those
ending by "test". At restoration in using the same
options, file without conflict will get restored
but only EA entry ending with "test" will be
restored, and for file with conflict (already
present in filesystem), EA set of file in
filesystem will be removed and replaced the EA
entries of the file in archive that ends by "test",
if some exist.
the situation is similar with FSA family scope and
overwriting policy. Only FSA of a family present in
the scope will be retained, the overwriting policy
acts first then the FSA scope is applied. Note
however that any FSA present on filesystem and
excluded from the FSA scope are not touched.
Well, now let's see how to bring some more fun
using conditional statements in all these actions.
The structure to use is the following:
{<condition>}[<action if condition is true>]
This syntax let you place an action (as the
ones we saw just above) inside the brackets
'[' and ']' (for example [Pp]) that will take
effect only if the evaluation of the
<condition> is true. Stated that a such
statement is a new type of action, you may
have guessed that you may use it recursively:
{<condition1>}[{<condition2>}[<action>]).
Well so far it seems useless. But instead of the
"if <condition> then <action> else <action>"
paradigm common to programming languages, due to
the command line context it has been chosen to
instead use and implicit "OR" operator between
actions. Thus you can "stack" conditional
statements this way: {<condition1>}[<action1>]
{<condition2>}[<action2>] <action3>. In this
example, if <condition1> is true then <action1>
will be used, ELSE if <condition2> is true then
<action2> will be used ELSE <action3> will be used.
This leads to the same possibilities as what is
available with programming languages, but with a
slightly more simple syntax. Seen this, the
recursion of conditional syntax is more
interesting. For readability, you are allowed to
add any space or tab in the overwriting policy, but
the resulting overwriting policy must be given as a
single argument to dar, thus the use of quotes
(either simple 'arg' or double "arg") is necessary.
The last operator we will see is the 'chain'
operator. Once an expression is evaluated, the
resulting couple of action may contain an '*'
(undefined action for EA or data). Further
evaluation must be done. The chain operator which
is represented by a 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. Note that ~I can be
used to check the nature of the 'to be added'
object.
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.
By default a file can be re-saved up to 3 times
(this is the 'count' field), you can set it to zero
to disable this feature. In option the overall
maximum amount of byte allowed to be wasted due to
retry changing file's backup can be given after a
column charactrer (:), this is the 'max-byte'
field. By default (no --retry-on-change option
specified) a limit of 1 wasted byte is allowed
which is the mininum. Specifying zero for max-byte
set no limit on the amount of wasted bytes (same as
if no 'max-byte' was specified), each changing file
is then saved up to 'count' times if necessary.
A file is considered as changed when the last
modification time has changed between the time the
file has been opened for backup and the time it has
been completely read. In some situation it is not
possible to replace the already saved data for a
file (writing archive to a pipe for example), in
that situation only, a second copy of the file is
added just after the first previous try which leads
that previous try to becomes inaccessible, however
it holds some place in the archive, where from the
designation of "wasted bytes". You can remove all
wasted bytes from an archive using the
merging/fitering feature: dar -+ new_arch -A
old_arch -ak.
Note: since release 2.5.0, in normal condition no
byte is wasted when a file changed at the time it
was read for backup, except when doing a backup to
pipe (using '-c -' option), except if the beginning
of the modified file is located in a previous slice
and except if slice hashing or strong encryption is
used.
-ad, --alter=decremental
This flag is to be used only when merging two
archives. Instead of the usual merging where each
files of both archives are added to the resulting
archive with eventually a tie using the overwriting
policy (see -/ option), here the merging builds an
archive which corresponds to the decremental backup
done based on two full backups. the -A backup is
expected to receive the older archive while the -@
is expected to point to the more recent one. If
this option is used, the eventually overwriting
policy is ignored and replaced internally by -/
"{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 differential backup: If the ctime of an
plain file has changed since the archive of
reference was done while all other values stay
unchanged (inode type, ownership, permission, last
modification date), dar issues a "SECURITY
WARNING", as this may be the sign of the presence
of a rootkit. You should use the -asecu option to
disable this type of warning globally, if you are
doing a differential backup of a just restored data
(a differential backup with the archive used for
restoration taken as reference). Effectively in
that situation, as it is not possible to restore
ctime, the restored data's ctime will have changed
while other parameters will be unchanged for all
restored files, leading dar to issue a warning for
all restored files. This security check is disabled
(implicitly) if dar is run with -ac option. Last,
if a file has only its EA changed since the archive
of reference was done (new EA, removed EA, modified
EA), the security warning will show (false
positive).
-., --user-comment "<message>"
This option let the user add an arbitrary message
into the archive header. Warning! this message is
always stored in clear text, even if the archive is
encrypted. You can see the message inserted in an
archive displaying the archive summary (dar -l
<archive> -q). Some macro can be used inside the
<message>:
%c is replaced by the command line used. Note
that for security, any option related to
archive encryption is removed (-K, -J, -$, -#,
-*, -%). The command included from a DCF file
(see -B option) are never added by this macro.
As a consequence, if you do not want to see
--user-comment stored in user comments you can
add the --user-comment definition in an
included file like ~/.darrc for example.
%d this is the current date and time
%u this is the uid under which dar has been run
%g this is the gid under which dar has been run
%h the hostname on which the archive has been
created
%% the % character.
-3, --hash <algo> With this option set, when creating, isolating or
merging an archive, beside each generated slices an
on-fly hash file of the slice is created using the
specified algorithm. Available algorithm are "md5",
"sha1" and "sha512". By default no hash file is
generated. The hash file generated is named based
on the name of the slice with the .md5, .sha1 or
.sha512 extension added to it at the end. These
hash files can be processes by md5sum, sha1sum and
sha512sum usual commands (md5sum -c <hash file>) to
verify that the slice has not been corrupted. Note
that the result is different than generating the
hash file using md5sum or sha1sum once the slice is
created, in particular if the media is faulty:
calling md5sum or sha1sum on the written slice will
make you compute the hash result on a possibly
already corrupted file, thus the corruption will
not be seen when testing the file against the hash
at a later time. Note also that the creation of a
hash file is not available when producing the
archive on a pipe ("dar -c -").
-7, --sign email[,email[,...email]]
When creating an archive with public key encryption
(read -K option) it is also possible to sign it
with one or more of your private key(s). At the
difference of the hash feature above, only the
randomly generated key used to cipher the archive,
key that is dropped at the beginning and at the end
of the archive, is signed. If the archive is
modified at some place, that part will not be
possible to decipher, but signature verification
will stay quick and valid, unless the part that has
been tempered is the key inside the archive in
which case signature check will report a failure
and archive will not be readable at all. If the
signature is valid and the archive could be
extracted without error, the whole archive could be
assumed to be signed by the gnupg key owners, but
read below the security note. See also GNUPGHOME in
the ENVIRONMENT section at the end of this
document.
A summay information about the signature
information is displayed while listing an archive
in summary mode "dar -l <archive> -q". For any
operation involving a signed archive, a short
message only shows if the archive is signed an one
or more signature check failed, no message is
displayed in case of successful signature check.
This warning may be disabled using the
--alter=blind-to-signatures command.
-ab, --alter=blind-to-signatures
do not check whether an encrypted archive with
public key that has also been signed have correct
signatures.
-<, --backup-hook-include <mask>
The mask is applied to path+filename during backup
operation only. If a given file matches the mask, a
user command (see -= option below) will be run
before proceeding to the backup and once the backup
will be completed. See also -> option below.
IMPORTANT: if using the short option, you need to
enclose it between quotes: '-<' for the shell not
to interpret the < as a redirection.
-> --backup-hook-exclude <mask>
The mask is applied to path+filename during backup
operation only. If a given file matches the mask,
even if it matches a mask given after -< option, no
user command will be executed before and after its
backup. The -< and -> options act like -g and -P,
they can receive wildcard expression and thus have
their comportment driven by the --alter=globe and
--alter=regex expressions seen above, as well as
the --alter=mask option. Last the --alter=case and
--alter=no-case modify also the way case
sensitivity is considered for these masks. By
default, no -> or -< option, no file get selected
for backup hook. IMPORTANT: if using the short
option, you need to enclose it between quotes: '->'
for the shell not to interpret the > as a
redirection.
-=, --backup-hook-execute <string>
for files covered by the mask provided thanks to
the -< and -> options, the given string is executed
before the backup of that file starts and once it
has completed. Several macro can be used that are
substituted at run time:
%% will be replaced by a literal %
%p will be replaced by the full path under
backup
%f will be replaced by the filename (without
the path)
%u will be replaced by the UID of the file
%g will be replaced by the GID of the file
%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 is about to be backed
up, and restart it once the backup has completed. Note that the masks
seen above that drive the execution of this command can be applied to a
directory or a plain file for example. When a directory is selected for
this feature, the command is logically ran before starting (with the
context "start") to backup any file located in that directory or in a
subdirectory of it, and once all 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 SPECIFIC OPTIONS (to use with -x)
-k[{ignored|only}], --deleted[={ignore|only}]
Without argument or with the "ignore" argument,
this option leads dar at restoration time to not
delete files that have been deleted since the
backup of reference (file overwriting can still
occur). By default, files that have been destroyed
since the backup of reference are deleted during
restoration, but a warning is issued before
proceeding, except if -w is used. If -n is used, no
file will be deleted (nor overwritten), thus -k is
useless when using -n. If -/ option is used, this
option without argument is ignored! With the "only"
argument, this option only consider files marked as
to be removed in the archive to restore, no file
are restored but some file are removed. When -konly
(or --deleted=only) is used, the -/ option is
ignored (at the opposition of the "--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!
-D, --empty-dir At restoration time, if -D is not specified
(default) any file and directory is restored in
regard to the filtering mechanism specified (see
-I, -X, -P, -g, -[ and -] options). But if -D
option is provided the restoration skips directory
trees that do not contain saved files. This avoid
having a huge empty tree with a few restored files
especially when restoring a differential archive in
an empty place. Note: This feature cannot work when
--sequential-read is used, as it is not possible to
know whether a directory contains or not some saved
files at the time the directory inode is read from
the archive in sequential reading mode.
-2, --dirty-behavior { ignore | no-warn }
At restoration time, if a file in the archive is
flagged as "dirty" (meaning that it had changed at
the time it was saved), user is asked for
confirmation before restoring it. Specifying
"ignore" will skip those dirty files, while "no-
warn" will restore them without user confirmation.
This feature is incompatible with sequential
reading mode, in this mode dar cannot know whether
a file is dirty before having restored it. In
consequences, in --sequential-read, once a file has
been restored, if it is found to be dirty it will
be removed unless dirty-behavior is set to "no-
warn".
-/, --overwriting-policy <policy>
Overwriting policy can be used for archive
restoration to define when and how file overwriting
can occur. See above the description of this
option.
-A, --ref [<path>]/<basename>
The --ref option can be used with an isolated
catalogue to rescue an archive that has a
corruption in the catalogue part, see GENERAL
OPTIONS above for more details.
TESTING AND DIFFERENCE SPECIFIC OPTIONS (to use with -t or -d)
-ado-not-compare-symlink-mtime, --alter=do-not-compare-symlink-mtime
With this option set, when comparing a symlink, no
message shows when symlink in archive and symlink
on filesystem do only differ by their mtime. See
also -O option.
No other specific option, but all general options are available except
for example -w which is useless, as testing and comparing only read
data. -A option is available as described in GENERAL OPTIONS to backup
of internal catalogue of the archive (assuming you have a previously
isolated catalogue available).
Doing a difference in sequential read mode is possible but hard linked
inodes can only be compared to the filesystem the first time they are
met, next hard links to this same inode cannot obtain the corresponding
data because skipping backward in sequential read mode is forbidden. In
that situation, the hard links are reported as skipped, meaning that
data comparison could not be performed.
LISTING OPTIONS (to use with -l)
-T, --list-format=<normal | tree | xml | slicing>, --tree-format
By default, listing provides a tar-like output (the
'normal' output). You can however get a tree-like
output, an XML structured output or a output
focusing on slice(s) where each file's data, EA and
FSA is located in. 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)
the -Tslicing option can also be used with isolated
catalogue generated with dar 2.5.0 or above, as
isolated catalogues now contain a copy of the
slicing layout of the archive of reference.
However, if the archive of reference has been
resliced (using dar_xform) after the isolated
catalogue has been built, the slicing information
would not be correct. For that corner case, you can
use the -s and -S options with -Tslicing to specify
what are the new slice sizes of the archive of
reference.
-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.
From the general options it seems only -vm and -b stay useful here.
Note that -vm displays an archive summary first, where a detailed of
information about the archive can be obtained. If you want to display
only this summary use -q with -l option.
displayed fields
[data] possible values are [ ] or [Saved] or [InRef]
or[DIRTY]. [ ] 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.
[FSA] Each character represent a FSA Family:
"L" is the first character (L/l/-) representing
ext2/3/4 FSA family
"H" is the second character (H/h/-) representing
HFS+ FSA family
"-" the third character is reserved for future FSA
family and is always a dash for now.
Uppercase means the FSA set is saved, lowercase
means the FSA is present in the archive of
reference and has not changed since that time. Last
a dash (-) means no FSA of that family has been
saved for that file.
[compr] possible values are [....%] or [-----] or [ ]
or [worse]. Shows if the file has been compressed
([...%]) and the compression ratio reached
"(uncompressed-compressed)/uncompressed", for
example [ 33%] means that the compressed data uses
only 66% of the space required to store
uncompressed data (33% of space saved thanks to
compression), or if the file is stored without
compression ([ ] see -m, -Y and -Z options) or
if the file is not subject to compression because
it is not a saved regular file ([----]), or if the
file takes more space compressed than its original
size ([worse]), due to compression overhead. Note
that 1% compression ratio brings quite no data
reduction, while obviously 98% is a very performant
compression (compressed file takes only 2% of the
size required by the uncompressed date).
[S] possible values are [ ] or [X]. [X] only applies to
saved plain files, and tells that the file is
stored using sparse file data structure: not all
data is stored, long sequence of zeros are skipped.
This also means that at restoration time, if the
filesystem supports it, holes will be restored. To
store hole information libdar uses escape sequence
(special sequence of byte), but to avoid real data
to be considered as such escape sequence, a special
escape sequence is used when data looks like an
escape sequence. So if a data contains a such
escape sequence, it must be read as if it contains
holes to be able to restore back the data in its
original form. For that reason, in some rare
circumstances (saving an dar archive inside a dar
archive without compression or encryption, for
example) a file without hole may be marked [X] as
if it had holes and will be longer by on byte for
each data sequence looking like an escape sequence.
permission
see ls man page. Note that a star (*) is prepended
to the permission string if the corresponding inode
is linked several times to the directory structure
(hard link).
user owner of the file
group group owner of the file
size size in byte of the file (if compression is
enabled, the real size in the archive is
"compression rate" time smaller).
date the last modification date of the file. The last
access time is also saved and restored, but not
displayed.
filename The name of the file.
Extended Attributes
When using -alist-ea option, for hard linked inode,
the filename is followed by an integer between
braces: Entries with the same number do point the
the same inode.
Slice(s) In -Tslice mode, each file is given the range of
slices it is located in. If slice size is chosen
particularily small, some slices may contain no
file, EA, FSA data but only tape marks or the
internal catalogue, leading the aggregation of
reported slices not to cover all available slices
of the archive.
EXPLICIT OPTIONAL ARGUMENTS
When dar has not been compiled with GNU getopt, which is not present by
default on some systems like FreeBSD, you may lack the optional
arguments syntax. For example "-z" will create a parse error on
command-line, or in -B configuration files. The solution is to
explicitly give the argument. Here follows a list of explicit argument
to use in place of optional ones:
-z must be replaced by -z 9
-w must be replaced by -w d or -w default
-H must be replaced by -H 1
-0 must be replaced by -0 ref
-5 must be replaced by -5 ""
-p must be replaced by -p 1
-v must be replaced by -v all
-k must be replaced by -k ignore
-5 must be replaced by -5 user.libdar_no_backup
important ! When using GNU getopt(), optional arguments are available
by sticking the argument to the short option: "-z" for example is
available as well as "-z9". But "-z 9" is wrong, it will be read as
"-z" option and "9", a command line argument (not an argument to the -z
option). In the other side, when using a non GNU getopt this time, "-z"
becomes an option that always requires an argument, and thus "-z 9" is
read as "-z" option with "9" as argument, while "-z9" will be rejected
as a unknown option, and "-z" alone will generate an error as no
argument is provided. In consequences, you need a space between the
option (like "-z") and its argument (like "9"), when dar does not rely
on a GNU getopt() call, which also imply you to explicitly use
arguments to options listed just above.
EXIT CODES
dar exits with the following code:
0 Operation successful.
1 Syntax error on command-line or DCF included file
2 Error due to a hardware problem or a lack of memory.
3 Detection of a condition that should never happen, and which
is considered as a bug of the application.
4 Code issued when the user has aborted the program 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 from zero).
7 an error has occurred when calling a libdar routine. This
means the caller (dar program), did not respect the
specification of the API (and this can be considered as a
particular case of bug).
8 the version of dar used is based 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. The exception caching
code to take care of new exceptions has probably been
forgotten to be update ... this is a minor bug you are
welcome to report.
10 you have tried to use a feature that has been disabled at
compilation time.
11 some saved files have changed while dar was reading them,
this may lead the data saved for this file not correspond to
a valid state for this file. For example, if the beginning
and the end of the file have been modified at the same time
(while dar is reading it), only the change at the end will be
saved (the beginning has already been read), the resulting
state of the file as recorded by dar has never existed and
may cause problem to the application using it. This is known
as a "dirty" file in the archive.
SIGNALS
If dar receives a signal (see kill(2) man page) it will take the
default behavior which most of the time will abruptly abort the
program, except for the following signals:
SIGINT This signal is generated by the terminal when hitting CTRL-C
(with the terminal's default settings), it can also be
generated with the kill command
SIGTERM This signal is generated by the system when changing of run-
level in particular when doing a shutdown, it can also be
generated with the kill command
SIGHUP Depending on the system, this signal may be sent before the
SIGTERM signal at shutdown time, it can also be generated
with the kill command
SIGQUIT This signal is generated by the terminal when hitting CTRL-\
(with the terminal's default settings), it can also be
generated with the kill command
SIGUSR1 This signal can be generated by the kill command
SIGUSR2 This signal can be generated by the kill command
For those previous signals, two behavior exit. For SIGHUP, SIGINT,
SIGQUIT, SIGTERM and SIGUSR1, a delayed termination is done: the backup
or isolation operation is stopped, the catalogue is appended to the
archive and the archive is properly completed with the correct
terminator string, this way the generated archive is usable, and can be
used as reference for a differential backup at a later time. Note that
if an on-fly isolation had been asked, it will *not* be performed, and
no user command will be launched even if dar has been configured for
(-E option). For SIGUSR2 instead a fast termination is done: in case of
backup or isolation, the archive is not completed at all, only memory
and mutex are released properly.
For both type of termination and other operations than backup or
isolation, dar's behavior is the same: For restoration, all opened
directories are closed and permissions are set back to their original
values (if they had to be changed for restoration). For listing,
comparison, testing, the program aborts immediately.
Another point, when using one of the previous signals, dar will return
with the exist status 4 meaning that the user has aborted the
operation. Note that answering "no" to a question from dar may also
lead dar to exit this way. last, If before the end of the program the
same signal is received a second time, dar will abort immediately.
FILES
$HOME/.darrc and /etc/darrc if present are read for configuration
option. They share the same syntax as file given to -B option. If
$HOME/.darrc is not present and only in that case, /etc/darrc is
consulted. You can still launch /etc/darrc from .darrc using a
statement like -B /etc/darrc. None of these file need to be present,
but if they are they are parsed AFTER any option on the command line
and AFTER included files from the command line (files given to the -B
option). NOTE: if $HOME is not defined $HOME/.darrc default to /.darrc
(at the root of the filesystem).
Else you can see conditional syntax below, and -N option above that
leads dar to ignore the /etc/darrc and $HOME/.darrc files.
CONDITIONAL SYNTAX
configuration files (-B option, $HOME/.darrc and /etc/darrc) usually
contain a simple list of command-line arguments, split or not over
several lines, and eventually mixed with comments (see -B option for
more). But, you can also use make-like targets to ask for a particular
set of commands to be used in certain conditions.
A condition takes the form of reserved word immediately followed by a
colon ':'. This word + colon must stand alone on its line, eventually
with spaces or tabs beside it. The available conditions are:
extract: all 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, but they will be activated in starting the
next -B file. Here follows an examples of two DCF files, first.dcf and
second.dcf:
# cat first.dcf
target3:
-K toto
target1:
target2
-B second.dcf
target3
target2:
#never reached
-s 10k
# cat second.dcf
target2:
-v
target3:
-b
In that example, target1 activates both target2 and target3, but at the
time of the parsing of first.dcf, neither target2 nor target3 were yet
activated thus '-K toto' and '-s 10k' will never be given to dar
(unless activated beside target1 before first.dcf get parsed), however
when comes the time to parse second.dcf, target2 *and* target3 are
activated, thus both '-v' and '-b' will be passed to dar, even if
'target3' is located after '-B second.dcf' in the file first.dcf
ENVIRONMENT
DAR_DCF_PATH
if set, dar looks for Dar Configuration File (DCF files, see
-B option) that do not have an fully qualified path in the
directories listed in DAR_DCF_PATH environment variable. This
variable receives a 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.
GNUPGHOME for asymetric encryption and signature, the keyring used is
$HOME/.gnupg by default. You can change this default by
setting GNUPGHOME to the directory containing the keyring.
For example, if you are running dar as root and want to use
your unprivileged account keyring use the following:
export GNUPGHOME=~myaccount/.gnupg
dar -K gnupg:...@...,...@... --sign:...@... etc.
EXAMPLES
You can find some more examples of use in the tutorial, mini-howto,
sample scripts, and other related documentation. All these are
available in dar's source package, and are also installed beside dar in
the <--prefix>/share/dar directory. This documentation is also
available on-line at http://dar.linux.free.fr/doc/index.html
SEE ALSO
dar_xform(1), dar_slave(1), dar_manager(1), dar_cp(1), dar_split(1),
TUTORIAL and NOTES included in the source package and also available at
http://dar.linux.free.fr/doc/index.html
KNOWN LIMITATIONS
dar saves and restores atime, mtime, birthtime but cannot restore ctime
(last inode change), there does not seems to be a standard call to do
that under UNIX.
KNOWN BUGS
http://sourceforge.net/p/dar/bugs/
AUTHOR
http://dar.linux.free.fr/
Denis Corbin
France
Europe
3rd Berkeley Distribution October 4th, 2015 DAR(1)