|
|
| |
DAR(1) |
FreeBSD General Commands Manual |
DAR(1) |
dar - creates, tests, lists, extracts, compares, merges, isolates dar archives
dar [-c | -t | -l | -x | -d | -+ | -C] [<path>/]<basename>
[<options>] [<user targets>]
dar -h
dar -V
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
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
- is equivalent to -vm -vs -vt, see also -Q and -q options below. Note: When
using dar from a script better use dar's exit status to know which way the
operation has ended (seen EXIT CODES at the end of this document).
- -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) each line must not exceed 20479 bytes. Note that this
option applies to any files and directory exactly as -g does, with an
important difference however: -g option only uses relative paths to the
root directory (the directory given with the -R option), while -[ can use
absolute path as well. 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. Note that having '-E
script1 -E script2' is totally equivalent to '-E "script1 ;
script2"'. In other words if script1 fails, script2 fill still be
executed and dar will only be notified of the exit status of the last -E
option. Exit status of previous -E given commands wll be ignored. If this does
not match your need, consider using a single -aduc option (see below). More
generally you can use any shell construction in the argument to -E, including
parenthesis, || and &&. Such files given to -E option are known as DUC
files (Dar User Command). See also the environment variable DAR_DUC_PATH in
the ENVIRONMENT section at the end of this document.
- -aduc, --alter=duc
- As described above for -E option, several -E/-F/-~ options (aka DUC
commands) are combined using the shell ";" operator, which
ignores the exit status of the first commands and only reports to dar the
exit status of the last command, leading all command to always being
executed. --aduc option combines the different DUC commands using the
shell "&&" operator, which execute the next command if
and only if the previous command succeeded. In other words, dar get
notified of an error in any given DUC command but due to an error not all
DUC command may be executed.
--aduc modifies the way the next DUC file is sticked to the
previous command, in other words:
- dar --aduc -E script1 -E script2 ...
- leads libdar to call a shell with the following line "script1
&& script2"
- dar -E script1 -script2 --aduc -E script3 ...
- leads libdar to call a shell with the following line "script1 ;
script2 && script3". In other words if you want to avoid the
";" use --aduc before any -E/-F/-~ option.
- -F, --ref-execute <string>
- same as -E but is applied between slices of the reference archive (-A
option). --execute-ref is a synonym.
- -~, --aux-execute <string>
- same as -E and -F but is applied between slices of the auxiliary archive
(-@ option).
- -K, --key [[<algo>]:]<string>
- -K, --key gnupg:[<algo>]: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.
About lzo compression, the compression levels of dar and
lzop program do not match. If you want to get the behavior of compression
level 1 of lzop, use the lzop-1 algorithm in place of lzo with dar/libdar. If
you want to get the behavior of lzop compression level 3, use the lzop-3
algorithm in place of the lzo algorithm. Lzop compression levels 2, 4, 5 and 6
are the same as level 3. last, there is no difference about compression level
7, 8 and 9 between dar and lzop. The lzop-1 and lzop-3 algorithms do not make
use of any compression level (compression level is ignored with these
algorithms).
- --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 SPECIFIC OPTIONS below).
- -Z, --exclude-compression <mask>
- Filenames covered by this mask are not compressed. It is only useful in
conjunction with -z option. By default, all 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 specific
options).
The given <policy> argument is composed of actions and
eventually of conditional expressions. Actions do define how to solve
overwriting conflict about file's data on one side and file's Attributes
(Extended and Filesystem Specific) on the other side. An action is thus a
couple of action for Data and for EA+FSA. Actions for Data are represented
by uppercase letters, while action for EA+FSA are defined by lowercase
letters. Both actions are independent of each other:
- P
- means 'Preserve'. When merging two archives, the data of the resulting
archive will be taken from the 'in place' file. While when extracting, the
data of the inode in filesystem will be preserved (thus no overwriting
will occur for the data).
- O
- means 'Overwrite'. When merging two archives, the data of the resulting
archive will be taken from the 'to be added' file. While when extracting,
the data of the inode in filesystem will be overwritten by data from the
archive.
- S
- means 'mark Saved and preserve'. When merging two archives, the data of
the resulting archive will be marked as already saved in the archive of
reference (making thus a differential archive, even if none of the
original archive were differential archives). All data will be dropped in
the resulting archive, but the last modification date [aka mtime] (used to
detect change in file's data) will be taken from the 'in place' file. This
action does not apply when extracting files, it is thus considered equal
to "Preserve" (P) in that situation.
- T
- means 'mark Saved and overwrite'. When merging two archives, the data of
the resulting archive will be marked as already saved (same as 'S'
action): all data will be dropped in the resulting archive, however the
last modification date [aka mtime] (used to detect changes in a file's
data) will be taken from the 'to be added' file. This action does not
apply when extracting files, it is thus considered equal to
"Overwrite" (O) in that situation.
- R
- means 'Remove'. When merging two archives, the resulting archive will not
contain any entry corresponding to the file that were in conflict. This
also implies that no EA will be stored for that particular entry as the
entry will no more exist in the resulting archive (as if it had never yet
existed). When extracting files, this will lead to file's
suppression.
- p
- means 'Preserve', same as 'P' (but lowercase letter) preserve the whole EA
set and FSA. When merging two archives, the Attributes set of the
resulting file will be the ones of the 'in place' file (whatever is the
overwriting action taken for its data). While when extracting files to
filesystem, the Attributes of the file in filesystem will not be changed
(whatever is the overwriting action taken for its data, unless the file is
removed using the 'R' policy, which would remove the inode and thus also
any Attributes it had).
- o
- means 'Overwrite', same as 'O' (but lowercase letter) overwrite the whole
EA set and FSA. When merging two archives, the Attributes set of the
resulting file will be taken from the 'to be added' file. While when
extracting files, the Attributes set of the file in the filesystem will
have its Attributes erased and replaced by those of the file in the
archive (still independent of what overwriting action is taken for file's
data).
- s
- means 'mark Saved and preserve', same as 'S' (but lowercase letter) for EA
and FSA instead of data. When merging two archives, the EA and FSA of the
resulting file are marked as already saved in the archive of reference,
thus they are dropped but the date of last inode change [aka ctime] (used
to detect changes in file's EA and FSA) will be taken from the 'in place'
file. This action does not apply when extracting files, it is thus
considered equivalent to "Preserve" (p) in that situation.
- t
- means 'mark Saved and overwrite', same as 'T' (but lowercase letter) for
EA and FSA instead of data. When merging two archives, the EA and FSA of
the resulting file are marked as already saved in the archive of
reference, thus they are dropped but the date of last inode change [aka
ctime] (use to track changes in EA) will be taken from the 'to be added'
file. This action does not apply when extracting files, it is thus
considered an equivalent to "Overwrite" (o) in that
situation.
- m
- means 'merge Attributes and preserve'. The resulting file in the merged
archive will have Attribute entries from both the 'in place' and the 'to
be added' files. If both files share a same Attribute entry (same FSA or
for EA the same key for a given association) the one of the 'in place'
file is kept (where from the 'preserve' notion). When extracting a file,
the file in the filesystem will have its EA and FSA set enriched by the
ones of the file in the archive that do not exist on filesystem, but its
already existing Attributes will stay untouched.
- n
- means 'merge Attributes and overwrite'. The resulting file in the merged
archive will have Attribute entries from both the 'in place' and the 'to
be added' files. If both files share a same Attribute entry (same FSA or
for EA the same key for a given association) the one of the 'to be added'
file will be kept (where from the 'overwrite' notion). When extracting
file, the file in the filesystem will have its Attributes set enriched by
ones of the file in the archive with some of them possibly been
overwritten.
- r
- means 'remove', same as 'R' but for the Attribute set (thus all EA and FSA
entries) of a given file ('r' is lowercase letter here). The file of the
resulting archive during merging operation will not own any EA nor any
FSA, even if the 'in place' and/or the 'to be added' files did have some.
For file extraction, this means that the file in the filesystem will loose
all its EA set. The FSA cannot be 'removed' from a filesystem and may not
always have a default value, thus this action does not modify FSA at all
in case of archive extraction. But in case of merging the FSA are removed
as previously described. As for all the previous tests, this Attribute
operation is independent of the operation chosen for file's data
(uppercase letters).
- d
- means 'delete'. When a same EA or FSA entry is found both in the 'in
place' and 'to be added' files, such entry will be absent in the resulting
archive. In other words, when merging, the EA set and FSA will only
contain EA and FSA entries specific to the 'in place' and those specific
to the 'to be added' file. Entries in common will not be present. When
extracting a file from an archive, the file on filesystem will have its EA
set enriched by entries of the 'to be added' file that are new to the 'in
place' file. The other EA entries (which are thus present in both archive
and filesystem) will be removed from the set, which the other FSA will
stay untouched (FSA cannot be "removed" from a filesystem, nor
they always have a default value).
- *
- is valid for both EA and data. It tells that the action is not yet defined
at this step of the evaluation and that further evaluation is required
(see the 'chain' operator below).
- A
- means 'Ask for user decision'. This uppercase letter concerns Data
overwriting. An application interaction let the user define the action for
each file in conflict. Note, that this action if used alone may become
very boring or painful. The idea is to use it in conditional statements
(which are described below) to have dar ask for only non obvious
cases.
- a
- means 'Ask for user decision'. This lowercase letter is the equivalent for
EA and FSA of the 'A' action. It is intended to be used in the same
conditional statements described below.
An action is thus a couple of letters, the first being uppercase
(for file's data) the second being lowercase (for file's EA and FSA). When
-/ option is not given, the action is equivalent to '-/ 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 (and has
no mtime available for comparison), it is here too assumed to be more
recent.
- R(<date>)
- true if the 'in place' entry is more recent than or of the same date as
the fixed <date> given in argument. No consideration is done toward
the 'to be added' element. The <date> format is the same as the one
used with -af option. If an entry has no mtime (it is not an inode for
example) it is assumed an virtual mtime of zero.
- B
- true only if both 'in place' and 'to be added' are plain file (hard linked
or not) and if the 'in place' file's data is larger or equal to the 'to be
added' file's data. If one or both entry are not plain files (or hard link
to plain file) and thus the file size comparison is not possible, the 'in
place' entry is assumed to be 'bigger' than the 'to be added' entry.
- S
- true only if the 'in place' data is saved in the archive (not marked as
unchanged 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
- %t
- will be replaced by a letter corresponding to the type of inode: 'f' for
plain file, 'l' for symlink, 'd' for directory, 'c' for char devices, 'b'
for block devices, 's' for sockets, 'p' for pipes, 'o' for doors.
- %c
- and most interesting, %c (c for context), will be replaced by
"start" or by "end" when the command is executed
before or after the backup respectively.
This way, one can 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.
- -az, --alter=zeroing-negative-dates
- dar/libdar saves dates as a number of seconds since the beginning of year
1970, the well known "Unix time" (plus a positive fraction for
sub-second time-stamping). Some systems may return a negative number as
the Unix time of a given file (files having dates before 1970), in that
situation by default and since release 2.5.12 dar pauses and asks the user
whether to assume the date as being zero. But with -az option, dar/libdar
automatically assumes such negative dates to be zero and just issue a
warning about the problem met.
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 an 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.
- -ay, --alter=byte, --alter=bytes
- by default files size is displayed to occupy the shortest number of
characters by using the largest unit possible (KiB, MiB, GiB, and so on).
With this option instead, the size is displayed with maximum precision
using the exact number of bytes used for each file.
- -I, -X, -P, -g, -[, -]
- can be used to filter file to list base on their name or path.
- -aheader
- displays the header (when --sequential-read is used) or the trailer of the
archive and then stops. This archive header/trailer is always in clear
text even when the archive is ciphered. This option is here to let you
access to these fields without providing the encryption key.
From the general options it seems only -vm and -b stay useful
here. Note that -vm displays an archive summary first, where a detailed of
information about the archive can be obtained. If you want to display only
this summary use -q with -l option.
- displayed
- fields
- [data]
- possible values are [ ] or [Saved] or [InRef] or[DIRTY]. [ ] 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.
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.
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.
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.
$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.
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 command has been used
- create:
- all option listed after this condition get used if previously on command
line or file (-B option) the -c command has been used
- list: (or listing:)
- if -l command has been used
- test:
- if -t command has been used
- diff:
- if -d command has been used
- isolate:
- if -C command has been used
- merge:
- if -+ command has been used
- 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 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
- 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.
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
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
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.
http://sourceforge.net/p/dar/bugs/
http://dar.linux.free.fr/
Denis Corbin
France
Europe
Visit the GSP FreeBSD Man Page Interface. Output converted with ManDoc. |