SYNOPSIS
dar [-c | -x | -l | -d | -t | -C | -+] [<path>/]<basename> [options]
dar -h
dar -V
DESCRIPTION
dar is a full featured backup tool, aimed for disks (floppy, CD-R(W),
DVD-R(W), zip, jazz, etc.)
dar can store a backup in several files (called "slices" in the follow-
ing) of a given size, eventually pausing or running a user com-
mand/script before starting the next slice. This can allow for example,
the burning of the last generated slice on a CD-R, or changing a floppy
disk before continuing on the next one. Like its grand-brother, the
great "tar" command, dar may also use compression, at the difference
that compression is used inside the archive to be able to have com-
pressed slices of the defined size. But the most important feature of
dar is its ability to make differential backups. In other words, back-
ups that contain only new files or files that have changed from a
backup of reference. Moreover with differential backup, dar also
stores files that have been deleted since the backup of reference.
Thus, when restoring, first a full backup, then additional differential
backups, at each restoration you get the exact state of the filesystem
at the time of the backup. And of course, the reference backup may be a
full or a differential backup itself.
dar is the first backup program I know that can also remove files dur-
ing restoration! By the way, in this document, "archive" and "backup"
mean the same thing, and are used interchangeably.
Unlike the tar command, dar is not suited for directly writing to
tapes. So keep using tar for tape archives. Because, even when using
dar to write a slice on a tape, you will loose all the interest of
another feature of dar which is its ability to directly access any of
the archived files, even when compression is used. This way, and in
contrast to the tar command, dar is able to extract a given file much
faster from a backup and to also recover files that follow a data cor-
ruption (loosing only the file in which data corruption has occurred).
This, of course, has its limitations, in particular when data corrup-
tion occurs in the vital part of the backup, i.e. the few first bytes
of each slice or the last part of the archive (the catalogue). In case
you need to store archives on a bad quality medium, you could protect
each slice with a Parchive recovery file. (see NOTES for more informa-
tion about Parchive, and how to transparently run Parchive from dar)
Slices have a base name given on the command line, which is completed
by a dot, a number, a dot and the extension (dar) to form a filename.
On the command line you will never have to give the full file name of a
Important note: Not all system actually support long options (Solaris,
FreeBSD, ...). For example --create will not be available on theses
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.
-c, --create [<path>/]<basename>
creates a backup with the name based on <basename>.
All the slices will be created in the directory
<path> if specified, else in the current directory.
If the destination filesystem is too small to con-
tain all the slices of the backup, the -p option
(pausing before starting new slices) might be of
interest. Else, in the case the filesystem is full,
dar will suspend the operation, asking for the user
to make free space, then continue its operation. To
make free space, the only thing you cannot do is to
touch the slice being written. If the filename is
"-" *and* no slice 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.
-x, --extract [<path>/]<basename>
extracts files from the given backup. Slices are
expected to be in the current directory or in the
directory given by <path>. It is also possible to
use symbolic links to gather slices that are not in
the same directory. Path may also point to a remov-
able device (floppy, CD, etc.), in this case, to be
able to mount/unmount the device, you must not
launch dar from that directory. In other words, the
current directory must not be that directory (see
tutorial for details).
-l, --list [<path>/]<basename>
lists the contents of the given backup. In general
dar will only require the first and the last slice
of the archive.
-t, --test [<path>/]<basename>
checks the backup integrity. Even without compres-
sion, dar is able to detect at least one error per
file in the archive, thanks to a 16 bits CRC
recorded per file in the catalogue. If one error
has occurred in a file stored in the archive, dar
will report it in 100% of all cases. If two errors
have occurred, dar will see them in 93,8% of the
the filename is "-" *and* no slice is asked (no -s
option) the catalogue is produced on the standard
output, allowing the user to send the resulting
catalogue through a pipe. Note that there is no
difference in concept between a catalogue and an
archive. Thus you can do all operation on a cata-
logue, in particular take it as reference for a
differential archive. A catalogue produced with -C
is just like a differential archive done right
after a full backup, (no data in it).
-+, --merge [<path>/]<basename>
create a subset archive from one or two existing
archives (the resulting archive name is the argu-
ment to this command). The dar file selection mech-
anism (see below) let the user decide which files
will be present in the resulting archive and which
one will be ignored. This option thus let the user
merge two archives in a single one (with a filter-
ing mechanism that accepts all files), as well as
this option let the user create a smaller archive
which data is taken from one or two archives of
reference. Note that at no time the contents of the
archives of reference is extracted to real files
and directories: this is an archive to archive
transfer, thus you may lack support for Extended
Attribute while you will be able to fully manipu-
late files with their Extended Attributes from one
archive to the resulting one. If the basename is
"-" *and* no slice is asked (no -s option), the ar-
chive is produced on standard output allowing the
user to send the resulting archive through a pipe.
The first mandatory archive of reference if pro-
vided thanks to the -A option, while the second
"auxiliary" (and optional) archive of reference is
provided thanks to the -@ option. Note that in the
current status, the resulting archive contains all
files from the mandatory archive of reference (that
matched the file selection mechanism) plus those
file of the auxiliary archive that are not already
present in the mandatory archive of reference. In
other words, no overwriting is possible, a more
complex way to solve conflicts will take place in a
future version. Last by default, archive data
selected for merging is uncompressed, and re-com-
pressed. Thus the merging operation can be used to
change compression algorithm of given archive as
well as change its encryption. But, for better per-
formance it is also possible thanks to the -ak
option (see below the -ak option for usage restric-
tions) to merge files keeping them compressed, thus
no decompression/re-compression is performed at
-b, --beep makes the terminal ring when user action is
required (like for example the creation of a new
slice using the -p option)
-n, --no-overwrite do not allow overwriting of any file or slice.
-w, --no-warn Do not warn before overwriting file or slice. By
default (no -n and no -w) overwriting is allowed
but a warning is issued before proceeding. This
option may receive 'a' as argument:
-wa, --no-warn=all This implies the -w option, and means that over
avoiding warning for file overwriting, DAR also
avoid signaling a file about to be removed when its
type is not the expected one. File are removed when
they have been recorded as deleted since the ar-
chive of reference. At restoration of the differen-
tial archive, if a file of the given name exists,
it is remove, but if the type does not match the
file that was present at the time of the archive of
reference (directory, plain file, fifo, socket,
char or block device, etc.), a warning is normally
issued to prevent the accidental removal of data
that was not saved in the backup of reference. (See
also -k option)
-R, --fs-root <path>
The path points to the directory tree containing
all the files that will be enrolled in the opera-
tion (backup, restoration or comparison). By
default the current directory is used. All other
paths used in -P or -g options on the command line
are and must be relative to this path (or to cur-
rent directory if -R is not present). Note that -R
is useless for testing (-t option) isolation (-C
option) and merging (-+ option)
-X, --exclude <mask>
The mask is a string with wild cards (like * and ?)
which is applied to filenames which are not direc-
tories. 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 con-
sidered for the given operation if it matches at
least one -X mask.
-I, --include <mask>
The mask is applied to filenames which are not
directories. If a given file matches the mask and
does not match any mask given with -X, the file is
command-line), no sub-tree or file is excluded from
the operation, and all the directory tree (as indi-
cated by -R option) is considered. Note that <path>
may contains wild-cards like * or ? see glob(7) man
page for more informations.
-g, --go-into <path>
Files or directory to only take in account, as
opposed to -P. -g may be present several time on
command-line. Same thing here, the difference with
-I is that the mask is applied to the path+filename
and also concerns directories. By default all files
under the -R directory are considered. Else, if one
or more -g option is given, just those are selected
(if they do not match any -P option). All paths
given this way must be relative to the -R direc-
tory. This is equivalent as giving <path> out of
any option. Warning, -g option cannot receive
wild-cards, theses would not be interpreted.
-[, --include-from-file <listing_file>
Files listed in the listing file are included for
the operation. No wild card expression is inter-
preted in the listing file, the null character is
not allowed and the carriage return is used to sep-
arate file names (one file name per line). Note
that this option applies to any files and directory
exactly as -g does, with an important difference
however: -g option only uses relative paths to the
root directory (the directory given with the -R
option), while -[ can use absolute path as well.
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
not save files out of the -R given root directory
tree.
-], --exclude-from-file <listing_file>
Files listed in the listing file are excluded from
the operation. If a directory is listed in the file
all its contents is excluded (unless using ordered
method and another mask includes some of its sub-
files or subdirectories). This option is the oppo-
site of -[ and acts the same was as -P option does
(in particular it is compared to the whole
path+filename and applies to files and directo-
ries). As for -[ option, -] listing file can con-
tain absolute paths, but wild cards are not
expanded, neither.
File selection in brief:
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 wild-cards).
the ordered method (when -am option is given on command-line):
The ordered method takes care of the order of presence
between -X and -I in one hand and of -P, -g, -[ and -] in
the other hand (note that it has also the same action con-
cerning EA selection when using -u and -U options, but
that's no more file selection). In the ordered method the
last argument take precedence over all the previous ones,
let's take an example:
-X "*.mp?" -I "*.mp3" -I "toto*"
Here dar will include all files except file of name
"*.mp?" (those ending with "mpX" where X is any char-
acter), but it will however include those ending with
".mp3". It will also include files which name begin by
"toto" whatever they end with. This way, "toto.mp2"
will be saved (while it matches "*.mp?" it also begins
by "toto") as well as "toto.txt" as well as "joe.mp3"
(while it matches "*.mp?" it also ends by "mp3"). But
will not be saved "joe.mp2" (because it does not begin
by "toto", nor ends by "mp3", and match "*.mp?" mask).
As we see the last option (-I or -X) overcomes the
previous one. -P, -g, -[ and -] act together the same
but as seen above they do not only act on filename,
but on the whole path+filename. Note that (-g, -P, -[,
-]) and (-X , -I) are independent concerning their
relative order. You can mix -X -I -g -P -] -[ in any
order, what will be important is the relative posi-
tions of -X options compared to -I options, and the
relative positions of -g -[ -] and -P options between
them.
In logical terms, if <prev_mask> is the mask generated by all
previous mask on the command line, -I <mask> generates the new
following mask: <prev_mask> or <mask> . While -X <mask> gener-
ates the new following mask: <prev_mask> and not <mask>. This is
recursive each time you add a -I or -X option. Things work the
same with -P, -g, -[ and -] options.
This ends the file selection explication let's continue with other
options.
-u, --exclude-ea <mask>
Do not consider the Extended Attributes (EA) that
are matched by the given mask. By default, no EA
are excluded, if the support for EA has been acti-
vated at compilation time. This option can be used
figure script tries to do so if your system has all the required
support for that). Thus you can get two binaries of dar (of the
same version), one supporting EA and another which does not (dar
-V to see whether EA support is activated). The archives they
produce are the same and can be read by each other. The only
difference is that the binary without EA support is not able to
save or restore EAs, but is still able to test them and list
their presence.
Since version 2.3.x the name of EA 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
names written in the following form namespace.name where "names-
pace" is for example "user". Note that the mask may or may not
include the dot (.) and match arbitrary part of the EA names-
pace+name, just remind that masks will be applied to the "names-
pace.name" global string.
the -am flag here also enables the ordered method, for EA selec-
tion too. The ordered versus normal method have been explained
above in the file selection note, with some examples using -X
and -I. Here this is the same with -U and -u, (just replace -X
by -u and -I by -U and remember that the corresponding mask will
apply to Extended Attribute selection in place of file selec-
tion).
Another point, independently of the -am option the -ae option
can be used at restoration time only. If set, when a file is
about to be overwritten, all EA will be first erased before
restoring those selected for restoration in the archive (accord-
ing to the -U and -u options given). If not set, the EA of the
existing file will be overwritten, those extra EA that are not
in the archive or are not selected for restoration in regard to
the -u and -U options will be preserved. If you have not used
any -u/-U option at backup time and want to restore from a set
of full/differential backups the EA exactly as the were you have
to use -ae for dar removes the EA that have been removed along
the time, else you could get an EA that has been removed in a
intermediate differential backup not been removed at restoration
time.
Last point the -acase and -an options alters the case sensitiv-
ity of the -U and -u masks that follow them on the command-
line/included files as they do for -I, -X, -P, -g, -[ and -] as
well. Very last point ;-), by default 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 slide effect, you can use the -ac option.
is used). When reading from pipe, standard output
is used to send request to dar_slave, but with this
option, the file <path> (usually a named pipe) is
used instead. When standard output is used, all
messages goes to standard error (not only interac-
tive messages). See doc/NOTES for examples of use.
-O, --comparison-field[=<flag>]
When comparing with the archive of reference (-c
-A) during a differential backup, when extracting
(-x) or when comparing (-d) do only consider cer-
tain fields. The available flags are:
ignore-owner all fields are considered except
ownership. This is useful when dar
is used by a non-privileged user. It
will not consider a file has changed
just because of a uid or gid mis-
match and at restoration dar will
not even try to set the file owner-
ship.
mtime only inode type and last modifica-
tion date is considered as well as
inode specific attributes like file
size for plain files. Ownership is
ignored, permission is ignored. Dur-
ing comparison, difference on owner-
ship or permission is ignored and at
restoration time dar will not try to
set the inode permission and owner-
ship.
inode-type Only the inode type is considered.
Ownership, permission and dates are
ignored. Inode specific attributes
are still considered (like file size
for plain files). Thus comparison
will ignore differences for owner-
ship, permission, and dates and at
restoration dar will not try to set
the ownership, permission and dates.
When no flag is provided to this option, -O option acts as if the
"ignore-owner" flag was set, which is the behavior in older releases (<
2.3.0). Note also that for backward compatibility, --ignore-owner
option still exists and is now 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
or -x options), the command is executed before the
slice is read or even asked, for writing instead
(thus using -c, -C or -+ option), the command is
executed once the slice has been completed. Some
substitution string can be used in the string:
%% will be replaced by %
%p will be replaced by the slice path
%b will be replaced by the slice basename
%n will be replaced by the slice number (to
be read or just written). For reading,
dar often needs the last slice, but ini-
tially it does not know its number. If it
cannot be found in the current directory,
the user command-line is then called with
%n equal to 0. This is a convenient way
to inform the user command to provide the
last slice. If after it is still not
present, dar asks the user (as usually)
with a message on the terminal. Once the
last slice is found, the user command-
line is called a second time, with %n
equal to the value of the last slice num-
ber.
%e will be replaced by the slice extension
(always substituted by "dar")
%c will be replaced by the context. Actually
three possible values exist: "init",
"operation" and "last_slice". When read-
ing an archive for (testing, extraction,
diff, listing, or while reading the ar-
chive of reference, see below the -F
option), the "init" context takes place
from the beginning up to the time the
catalogue is retrieved. On a multiple
slice archive this correspond to the
first slice request and to the last slice
requests. After, that point comes the
"operation" context. While creating an
archive, the context is always "opera-
tion" except when the last slice has been
created, in which case the context is set
to "last_slice".
Several -E option can be given, given commands will then be called in
the order they appear on the command line, and included files.
-F, --execute-ref <string>
If the <string> is empty the pass phrase will be
asked at execution time. Thus, the smallest argu-
ment that -K can receive is ':' which means blow-
fish cipher with the pass phrase asked at execution
time.
With release 2.3.4 a better implementation of the blowfish algorithm
has been used within dar, while recent version can transparently read
older implementation (using 'bf' cipher) you can create new archive
with this old weakened blowfish implementation using the 'blow-
fish_weak' or 'bfw' cipher. Note that this way of encryption is strong
but weakened by frequent IV collision (same Initial Vectors used
often). This feature is kept available for those using old openssl
library that do not provide all the header required to implement the
new blowfish implementation.
Note that giving the pass phrase as argument to -K (or -J see below)
may let other users learn pass phrase (thanks to the ps, or top program
for examples). It is thus wise to either use an empty pass which will
make dar ask the pass phrase at when needed, or use -K (or -J option)
from an Dar Command File (see -B option), assuming it has the appropri-
ated permission to avoid other users reading it.
-J, --key-ref [[<algo>]:]<string>
same as -K but the given key is used to decrypt the
archive of reference (given with -A option).
-#, --crypto-block <size>
to be able to randomly access data in an archive,
it is not encrypted globally but block by block.
You can define the encryption block size thanks to
this argument which default to 10240 bytes. Note
that syntax used for -s option is also available
here. Note also that crypto-block is stored as a 32
bits integer thus value larger than 4GB will cause
an error. Note last, that the block size given here
must be provided when reading this resulting ar-
chive (through the -* or -# options). If it is not
the correct one, the archive will not be possible
to decrypt, it is thus safe to keep the default
value (and not use at all the -# option).
-*, --crypto-block-ref <size>
same as --crypto-block but for the archive of ref-
erence (same default value).
-B, --batch <filename>
You can put in the file any option or argument as
used on command line, that will be parsed as if
they were in place of the "-B <filename>" option.
This way you can overcome the command line size
limitation. Commands in the file may be disposed on
-e, --empty Do not perform any action (backup, restoration or
merging), displays all messages as if it was for
real ("dry run" action).
-aSI, --alter=SI[-unit[s]]
when using k M G T E Z Y prefixes to define a size,
use the SI meaning: multiple of 10^3 (a Mega is
1,000,000).
-abinary, --alter=binary[-unit[s]]
when using k M G T E Z Y prefixes to define a size,
use the historical computer science meaning: multi-
ple of 2^10 (a Mega is 1,048,576).
The --alter=SI and --alter=binary options can be used several times on
the command line. They affect all prefixes which follow, even those
found in files included by the -B option, up to the next --alter=binary
or --alter=SI occurrence. Note that if in a file included by the -B
option, an --alter=binary or --alter=SI is encountered, it affects all
the following prefixes, even those outside the included files. For
example, when running with the parameters "-B some.dcf -s 1K", 1K may
be equal to 1000 or 1024, depending on --alter=binary or --alter=SI
being present in the some.dcf file. By default (before any
--alter=SI/binary option is reached), binary interpreration of prefixes
is done, for compatibility with older versions.
-Q Do not display an initial warning on stderr when
not launched from a terminal (when launched from a
cronjob for example). This means that all questions
to the user will be answered with 'no', which most
of the time will abort the program. Please note
that this option cannot be used in the configura-
tion file, it must be given on the command line.
Since version 2.2.2, giving this option also forces
the non-interactive mode, even if dar is launched
from a terminal. This makes it possible for dar to
run in the background. When you do, it's recom-
mended to redirect stdout and/or sterr to files.
-aa, --alter=atime when reading a filesystem, while doing a backup (-c
option) or comparing (-d option) by default dar
tries to be as much transparent as possible, and
set back the last access time (atime) of read files
and directories, as if they have not been read.
But, preserving atime of read files, make their
ctime to be changed (last inode change). There is
no possibility to preserve both atime and ctime. If
you want to overcome the default original behavior
of dar and want to keep ctime unchanged, the
--alter=atime is for you. Some security software
rely on the ctime to be preserved, some other soft-
-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.
-an, --alter=no-case
set the filters in case insensitive mode. This con-
cerns only masks specified after this option (see
also -acase option below). This changes the behav-
ior of -I, -X, -g, -P, -Z, -Y, -u and -U options.
-acase, --alter=case
set back to case sensitive mode for filters. All
following masks are case sensitive, up to end of
parsing or up to the next -an option. This changes
the behavior of -I, -X, -g, -P, -Z, -Y, -u and -U
options.
-ar, --alter=regex set the filters to be interpreted as regular
expressions (man regex(7) ) instead of the default
glob expression (man glob(7) ) This modifies the
-I, -X, -g, -P, -Z, -Y, -u and -U options that fol-
lows up to an eventual -ag option (see just below).
Note that for -P and -g options, 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).
-j, --jog when virtual memory is exhausted, ask user to make
room before trying to continue. By default, when
memory is exhausted dar aborts. Note that on sev-
eral system, when memory is exhausted the kernel is
likely to kill the process that failed to obtain
virtual memory, thus on some systems, dar may not
be able to ask user for what to do when memory is
exhausted.
SAVING, ISOLATION AND MERGING OPTIONS (to use with -c, -C or -+)
-z[level], --gzip[=level]
compresses within slices using gzip algorithm (if
not specified, no compression is performed). The
respectively. Example: "20M" means 20 megabytes, by
default, it is the same as giving 20971520 as argu-
ment (see also -aSI and -abinary options). If -s is
not present the backup will be written to a single
slice whatever the size of the backup may be (there
is probably some filesystem limitation, thus you
might expect problems for file size over 2 giga-
bytes, depending on your filesystem, but this is
not a limitation of dar).
-S, --first-slice <number>
-S gives the size of the first slice which may be
chosen independently of the size of following
slices. This option needs -s and by default, the
size of the first slice is the same as the one of
the following slices.
-p [<integer>], --pause[=<integer>]
pauses before writing to a new slice (this requires
-s). By default there is no pause, all slices are
written in the same directory, up to the end of the
backup or until the filesystem is full. In this
later case, the user is informed of the lack of
disk space and dar stops for user action. As soon
as some disk space is available, the user can con-
tinue the backup. The optional integer that this
option can receive tells dar to only pause very 'n'
slice. Giving 3 for 'n' will make dar pause only
after slices 3, 6, 9 and so on. If this integer is
not specified, the behavior is as if '1' was given
as argument which makes dar pause after each slice.
-A, --ref [<path>]/<basename>
specifies the archive to use as reference (manda-
tory with -C). By default (default is only possible
with -c option) no archive is used and all files
are saved (in regards to -I -X -P and -g options).
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
first and the last slice are required to extract
the catalogue of reference. If necessary the use of
symbolic links is also possible here to gather
slices that do not reside in the same directory.
You can also point <path> to a floppy or any other
mounted directory, because dar will pause and ask
the user for required slices if they are not
present. The argument to -A may be of four types:
- An existing archive basename, which will be
taken as reference
- a dash ("-") which implies the use of -o and -i
options, this allows the archive of reference to be
-B option). For more about that feature see -af
option below.
-@, --aux-ref [<path>]/<basename>
specifies an auxiliary archive of reference. This
option is only available with -+ option (merging).
Over -A option which is mandatory with -+ option,
you may give a second archive of reference thanks
to the -% option. This allows one to merge two ar-
chive in a single one. See also -$, -~ and -% for
other options concerning auxiliary archive of ref-
erence.
-$, --aux-key [[<algo>]:]<string>
same as -J but for the auxiliary archive of refer-
ence (-@ option).
-~, --aux-execute <string>
same as -F but for the auxiliary archive of refer-
ence (-@ option).
-%, --aux-crypto-block <size>
same as -* but for the auxiliary archive of refer-
ence (-@ option).
-D, --empty-dir 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 theses. 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 theses directories (if necessary).
This option has no meaning with -C and is ignored
in that case.
-Z, --exclude-compression <mask>
Filenames covered by this mask are not compressed.
It is only useful with -z or -y. 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.
-Y, --include-compression <mask>
Filenames covered by this mask (and not covered by
-Z) are the only to be compressed. It is only
available with -z no -y. 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
-ak, --alter=keep-compressed
During merging operation, keep files compressed,
this has several restrictions : -z, -y, -Z, -Y, -m
are ignored, if two archives have to be merged,
both must use the same compression algorithm or one
of them must not use compression at all (this last
restriction will probably disappear in a next ver-
sion). The advantage of this option is a greater
speed of execution (compression is usually CPU
intensive).
-af, --alter=fixed-date
Modify the -A option behavior, making it receiving
a <date> as argument in place of the
[<path>]/<basename> default argument. The <date> is
used to define which file to save (file which modi-
fication is newer or equal to <date>) and which to
consider unchanged (those older than <date>). This
option has only a sense when creating an archive
(not when merging or isolating).
<date> must be a date in the following possible formats:
- a number of second since Jan 1st, 1970
- a date in the following form [[[year/]month/]day-]hour:minute[:sec-
ond]
Here are some examples of date:
91836383927108078
2005/11/19-19:38:48 Which is 38 past 7 PM and 48 seconds, the
19th of November 2005
20:20 Which is 8 PM of the current day
2-00:08 Which is 8 past noon, the second day of the current
month
2/2-14:59 Which is 1 to 3 PM, the 2nd of February in the current
year
--nodump do not save files which have the 'd' flag set (see
chattr(1) lsattr(1) ext2 commands). This option may
not be available if the system dar has been com-
piled on did not provide support for ext2 flags.
Note that this option does nothing with -+ option
(merging) as no filesystem is used for that opera-
tion.
-G, --on-fly-isolate [<path>]/<basename>
When creating a backup (-c option) or merging two
backups (-+ option), -G option perform a catalogue
to change slices size (this is faster as no decom-
pression/re-compression is done).
-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 (useless with -+
option)
-, , --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)
RESTORATION OPTIONS (to use with -x)
-k, --no-deleted Do not delete files that have been deleted since
the backup of reference (file overwriting can still
occur). By default, files that have been destroyed
since the backup of reference are deleted during
restoration, but a warning is issued before pro-
ceeding, except if -w is used. If -n is used, no
file will be deleted (nor overwritten), thus -k is
useless when using -n.
-r, --recent restore only files that are absent or more recent
than those present in filesystem. -r is useless if
-n is present.
-f, --flat do not restore directory structure. All file will
be restored in the directory given to -R, if two
files of the same name have to be restored, the
usual scheme for warning (-w option) and overwrit-
ing (-n option) is used. No rename scheme is
planned actually. When this option is set, dar does
not remove files that have been stored as deleted
since last backup. (-f implicitly implies -k).
-ae, --alter=erase_ea
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 over-
written 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 behav-
ior.
argument gives the same as providing the 'tree'
argument to it. The option --tree-format is an
alias to --list-format=tree (backward compatibil-
ity). Note that the files doc/dar-catalog-*.dtd
define the format of the XML output listing (This
file is also installed under $PREFIX/share/doc)
-as, --alter=saved list only saved files
-I and -X can be used to filter file to list base on their
name (is ignored when --list-format=tree is used).
Note that -P and -g options are not available while
listing.
Else only -v and -b from general options are useful. Note that -v dis-
plays an archive summary first, where a lot of information about the
archive can be obtained.
displayed fields
[data] possible values are [ ] or [Saved] or [InRef] .
[ ] means that the data has not been saved
because there is no change since backup of refer-
ence. [Saved] means that the data has been saved,
and thus this archive is able to restore the file.
[InRef] is used when isolating a catalogue from an
archive and means that the file was saved in the
reference archive.
[EA] possible values are " " (empty string) or [ ]
or [InRef] or [Saved]. It Shows if Extended
Attributes are present and saved ([Saved]), are
present but not saved ([ ]) which means there
is no change since backup of reference, or if there
is no EA saved for this file (empty string).
[InRef] is used when isolating a catalogue from an
archive and means that the file was saved in the
reference archive.
[compr] possible values are [....%] or [-----] or [ ]
or [worse]. Shows if the file has been compressed
and the compression rate reached ([...%]), or if
the file is stored without compression ([ ] see
-Y and -Z options) or if the file is not subject to
compression because it is not a saved regular file
([----]), or if the file takes more space com-
pressed than its original size ([worse]), due to
compression overhead.
permission
see ls man page.
EXPLICIT OPTIONAL ARGUMENTS
When dar has not been compiled with GNU getopt, which is not present by
default on some systems like FreeBSD, you may lack the optional argu-
ments 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
-y must be replaced by -y 9
-w must be replaced by -w d or -w default
-H must be replaced by -H 1
important ! When using GNU getopt(), optional arguments are available
by sticking the argument to the short option: "-z" for example is
available as well as "-z9". But "-z 9" is wrong, it will be read as
"-z" option and "9", a command line argument (not an argument to the -z
option). In the other side, when using a non GNU getopt this time, "-z"
becomes an option that always requires an argument, and thus "-z 9" is
read as "-z" option with "9" as argument, while "-z9" will be rejected
as a unknown option, and "-z" alone will generate an error as no argu-
ment is provided. In consequences, you need a space between the option
(like "-z") and its argument (like "9"), when dar does not rely on a
GNU getopt() call, which also imply you to explicitly use arguments to
options listed just above.
EXIT CODES
dar exits with the following code:
0 Operation successful.
1 Syntax error on command-line.
2 Error due to a hardware problem or a lack of memory.
3 Detection of a condition that should never happen, and which
is considered as a bug of the application.
4 Code issued when the user has aborted the program upon dar
question from dar. This also happens when dar is not run from
a terminal (for example launched from crontab) and dar has a
question to the user. In that case, dar aborts the same way
as if the user pressed the escape key at the question prompt.
5 is returned when an error concerning the treated data has
been detected. While saving, this is the case when a file
could not be opened or read. While restoring, it is the case
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 infinint) to avoid this error.
9 this code indicates an unknown error. I have probably forgot-
ten to update the exception caching code to take care of new
exceptions... this is a minor bug you are welcome to report.
10 you have tried to use a feature that has been disabled at
compilation time.
11 some saved files have changed while dar was reading them,
this may lead the data saved for this file not correspond to
a valid state for this file. For example, if the beginning
and the end of the file have been modified at the same time
(while dar is reading it), only the change at the end will be
saved (the beginning has already been read), the resulting
state of the file as recorded by dar has never existed and
may cause problem to the application using it.
SIGNALS
If dar receives a signal (see kill(2) man page) it will take the
default behavior which most of the time will abruptly abort the pro-
gram, except for the following signals:
SIGINT This signal is generated by the terminal when hitting CTRL-C
(with the terminal's default settings), it can also be gener-
ated with the kill command
SIGTERM This signal is generated by the system when changing of run-
level in particular when doing a shutdown, it can also be
generated with the kill command
SIGHUP Depending on the system, this signal may be sent before the
SIGTERM signal at shutdown time, it can also be generated
with the kill command
SIGQUIT This signal is generated by the terminal when hitting CTRL-\
(with the terminal's default settings), it can also be gener-
ated with the kill command
SIGUSR1 This signal can be generated by the kill command
SIGUSR2 This signal can be generated by the kill command
For those previous signals, two behavior exit. For SIGHUP, SIGINT,
SIGQUIT, SIGTERM and SIGUSR1, a delayed termination is done: the backup
or isolation operation is stopped, the catalogue is appended to the ar-
Another point, when using one of the previous signals, dar will return
with the exist status 4 meaning that the user has aborted the opera-
tion. Note that answering "no" to a question from dar may also lead dar
to exit this way. last, If before the end of the program the same sig-
nal is received a second time, dar will abort immediately.
FILES
$HOME/.darrc and /etc/darrc if present are read for configuration
option. They share the same syntax as file given to -B option. If
$HOME/.darrc is not present and only in that case, /etc/darrc is con-
sulted. You can still launch /etc/darrc from .darrc using a statement
like -B /etc/darrc. None of theses file need to be present, but if
they are they are parsed AFTER any option on the command line and AFTER
included files from the command line (files given to the -B option).
NOTE: if $HOME is not defined $HOME/.darrc default to /.darrc (at the
root of the filesystem).
Else you can see conditional syntax bellow, and -N option above that
leads dar to ignore the /etc/darrc and $HOME/.darrc files.
CONDITIONAL SYNTAX
configuration files (-B option, $HOME/.darrc and /etc/darrc) usually
contain a simple list of command-line arguments, split or not over sev-
eral lines, and eventually mixed with comments (see -B option for
more). But, you can also use make-like targets to ask for a particular
set of commands to be used in certain conditions.
A condition takes the form of reserved word immediately followed by a
colon ':'. This word + colon must stand alone on its line, eventually
with spaces or tabs beside it. The available conditions are:
extract: all option listed after this condition get used if
previously on command line or file the -x option
has been used
create: all option listed after this condition get used if
previously on command line or file (-B option) the
-c option has been used
listing: (or list:) if -l option has been used
test: if -t option has been used
diff: if -d option has been used
isolate: if -C option has been used
merge: if -+ option has been used
# 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.
SEE ALSO
dar_xform(1), dar_slave(1), dar_manager(1), dar_cp(1)
see also TUTORIAL and NOTES files in the documentation.
KNOWN BUGS
dar cannot restore time of symbolic links. Many (all ?) UNIX do not
provide any way to do that, the utime() system call changes the file
pointed to by the link rather than the date of the link itself.
dar saves and restores atime and mtime, but cannot restore ctime (last
inode change), there does not seems to be a standard call to do that
under UNIX.
AUTHOR
http://dar.linux.free.fr/
Denis Corbin
France
Europe
3rd Berkeley Distribution AUG 28th, 2007 DAR(1)
Man(1) output converted with
man2html