Typos in man page
Graham Cobb <[email protected]>
| Newsgroups | gmane.comp.sysutils.backup.dar.support |
|---|---|
| Message-ID | <[email protected]> |
I found a small error in the dar man page: In the description of --retry-on-change, it says: "...can be given after a column charactrer...". This should be "...can be given after a colon character..." (note: two changes). But then I decided it would be more useful if I took a few mins to spell-check the whole dar manpage to catch other typos. My proposed patch is attached. By the way, I am a native British English speaker but I have tried to use US forms as that is most common in these pages. Graham
dar.1.diff
(text/x-patch, 75.1 KB)
--- /tmp/a/dar.1 2021-04-26 16:35:38.613747603 +0100 +++ /tmp/b/dar.1 2021-04-26 16:35:48.669987338 +0100 @@ -37,12 +37,12 @@ .PP 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, a first time all along the archive used for tar-like behavior suitable for sequential access media (tapes) and a second time at the end for faster access, suitable for random access media (disks). However note that tar archive and dar archive are not compatible. 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) and since release 2.6.0 such truncated archive can be repaired to become a normal archive (the "catalogue" is rebuilt from inlined information). .PP -Dar is able to save and restore to a cloud storage by mean of ftp or sftp network protocols. It can also leverage ssh protocol using dar_slave and dar_xform two auxilliary programs provided beside dar. +Dar is able to save and restore to a cloud storage by mean of ftp or sftp network protocols. It can also leverage ssh protocol using dar_slave and dar_xform two auxiliary programs provided beside dar. .PP 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. .PP .B 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. +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 pair 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. .PP .B 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. @@ -86,7 +86,7 @@ LISTING OPTIONS A set of options that are specific to archive listing operation .TP 5 -EXPICIT OPTIONAL ARGUMENTS +EXPLICIT OPTIONAL ARGUMENTS Some system do not allow optional arguments to options, this chapter explain how to overcome this restriction .TP 5 EXIT CODES @@ -124,7 +124,7 @@ .PP .TP 20 -c, --create [[<URL>]<path>/]<basename> -creates a backup with the name based on <basename>. All the slices will be created in the directory <path> if specified, details about the <URL> syntaxe is explained below at +creates a backup with the name based on <basename>. All the slices will be created in the directory <path> if specified, details about the <URL> syntax is explained below at .B Remote repository syntax paragraph. Without <path> nor <URL> the current directory is used. 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). @@ -148,13 +148,13 @@ 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. .TP 20 -C, --isolate [[<URL>]<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). +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 detect 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). .TP 20 -+, --merge [[<URL>]<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. .TP 20 -y, --add-missing-catalogue [[<URL>]<path>/]<basename> -create a "repaired" archive based on the archive given with -A option. The repairing only concerns the case where an archive has been interrupted and dar could not cleanly end the archive creation process (lack of disk space, power outage, and so on). This operation consists in reading the tape marks in sequential reading mode to gather the content of the archive and once its end is reached, to recreate the missing table of content (aka catalogue) located at the end of the archive. Note that the damaged archive is not modified but a repaired copy is built beside it. Why not just appending the catalogue to the archive? Because first it was simpler to implement allowing to reuse routines of the merging operation, second by precaution for dar to not mess an existing archive due to a bug and last, it would not be compatible with archive signing and gpg encryption under certains conditions (several recipients or the archive is signed and you are not the one who signed it). +create a "repaired" archive based on the archive given with -A option. The repairing only concerns the case where an archive has been interrupted and dar could not cleanly end the archive creation process (lack of disk space, power outage, and so on). This operation consists in reading the tape marks in sequential reading mode to gather the content of the archive and once its end is reached, to recreate the missing table of content (aka catalogue) located at the end of the archive. Note that the damaged archive is not modified but a repaired copy is built beside it. Why not just appending the catalogue to the archive? Because first it was simpler to implement allowing to reuse routines of the merging operation, second by precaution for dar to not mess an existing archive due to a bug and last, it would not be compatible with archive signing and gpg encryption under certain conditions (several recipients or the archive is signed and you are not the one who signed it). .P .RS During the repairing operation, the repaired archive may have a different slicing (-s and -S options), a different encryption (-K and associated options, including gpg encryption and signing), a different repository slices permissions and ownership (--slice-mode option), user comment (--user-comment), generated hash (--hash) and min digits in slice number (--min-digits), but compression cannot be changed and tape marks cannot be removed (you can do it once reparation has completed using the merging operation). Last, file filtering is not allowed during archive repairing. @@ -169,7 +169,7 @@ .B Remote repository syntax for [<URL>]<path> .PP .RS -for all commands described above as well as some options detailes below (-A and -@ options), the <path> optional argument can be a Unix path like /var/tmp when the archive is located on the host dar runs on. But it can also make use of <URL> to define the remote host the archive is to be read or written to. "<URL><path>" follows the usual syntax: +for all commands described above as well as some options detailed below (-A and -@ options), the <path> optional argument can be a Unix path like /var/tmp when the archive is located on the host dar runs on. But it can also make use of <URL> to define the remote host the archive is to be read or written to. "<URL><path>" follows the usual syntax: .PP .RS .B @@ -186,10 +186,10 @@ login is optional, if not provided it defaults to .B anonymous. -If the login string comports an @ it need to be escaped by \\\\ (a pair of backshashes) to avoid libdar considering it the hostname starting part. Exemple: login is [email protected] host is www.example.org gives: sftp://me\\\\@[email protected]/some/file. You may also need to escape the same way any other special characters like for exampl ecolumn (:) slash (/) if they are part of the login string. +If the login string comports an @ it need to be escaped by \\\\ (a pair of backslashes) to avoid libdar considering it the hostname starting part. Example: login is [email protected] host is www.example.org gives: sftp://me\\\\@[email protected]/some/file. You may also need to escape the same way any other special characters like for example colon (:) slash (/) if they are part of the login string. .TP 3 password -if login is provided, the associated password may be given after a column (:) but this exposes the secret password to other +if login is provided, the associated password may be given after a colon (:) but this exposes the secret password to other users of the current system having access the table of process (using top, ps, /proc or other ways). If the login is given without password, the password will be asked interactively by dar at run time, which is much more secure. Alternatives are either to rely on ~/.netrc for FTP and also SFTP (!) transfers for that you need to use the --alter=file-authentication option (see below), or for SFTP only on public key authentication (you can also use --alter=file-authentication in that case to avoid a password being asked interactively). Note that passphrase support for sftp key is not (yet) supported. .TP 3 hostname @@ -256,7 +256,7 @@ 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 & +stdout and/or stderr to files: dar -Q ... &> /dev/null & .TP 20 -n, --no-overwrite do not allow overwriting @@ -278,7 +278,7 @@ .TP 5 - An existing archive basename, which will be taken as reference .TP 5 -- 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-read 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 dash ("-") in direct access mode (default mode, when --sequential-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-read 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. .TP 5 - 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. .TP 5 @@ -319,7 +319,7 @@ 2/2-14:59 Which is 1 to 3 PM, the 2nd of February in the current year .RE .PP -Note that the provided date is relative to the system timezone which is overriden if the TZ environement variable is set (see tzselect(1) for more details) +Note that the provided date is relative to the system timezone which is overridden if the TZ environment variable is set (see tzselect(1) for more details) .RE .TP 20 -@, --aux [[<URL>]<path>]/<basename>, --on-fly-isolate [<path>]/<basename> @@ -533,14 +533,14 @@ -K, --key gnupg:[<algo>]:email[,email[...]] .RS .B 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 aes256 cipher is assumed (default was blowfish up to 2.5.x). 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 aes256 cipher with the pass phrase asked at execution time. +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 aes256 cipher is assumed (default was blowfish up to 2.5.x). If your password contains a colon ':' 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 aes256 cipher with the pass phrase asked at execution time. .PP 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. .PP -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). +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 omit -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). .PP .B 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::[email protected],[email protected]" will generate an aes256 encrypted archive which passprhase randomly chosen by libdar will be encrypted with the public keys of [email protected] and [email protected] To use blowfish in place of ars256 one could use "--key gnupg:bf:[email protected],[email protected]". 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. +starts with the word "gnupg" followed by a colon ':' . In that situation, the same set or symmetric encryption algorithms as described above is available after the colon, 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::[email protected],[email protected]" will generate an aes256 encrypted archive which passphrase randomly chosen by libdar will be encrypted with the public keys of [email protected] and [email protected] To use blowfish in place of ars256 one could use "--key gnupg:bf:[email protected],[email protected]". Note that no check is done about the trust you have set in GPG keyring that a particular public key is owned by the physical person you expect. See also --sign option below. .PP 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. .PP @@ -592,7 +592,7 @@ 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 +changes is flaky 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. @@ -645,7 +645,7 @@ .PP .TP 20 -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. +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 processing 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. .PP .RS 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). @@ -682,13 +682,13 @@ 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. .TP 20 -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), 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 non 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 (a page), 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. +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), 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 non 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 vice-versa, 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 (a page), 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. .TP 20 -ak, --alter=keep-compressed During merging and repairing 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). .TP 20 -ah, --alter=holes-recheck -For merging and repairing, 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 and reparing --sparse-file-min-size can be used as described above for archive creation. In addition, you can have files stored as sparse file in the archive of reference be stored as normal files in the merged archive using -ah and passing to --sparse-file-min-size an value larger than all file sizes, for example as of today in year 2018, passing +For merging and repairing, 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 and repairing --sparse-file-min-size can be used as described above for archive creation. In addition, you can have files stored as sparse file in the archive of reference be stored as normal files in the merged archive using -ah and passing to --sparse-file-min-size an value larger than all file sizes, for example as of today in year 2018, passing .B -ah --sparse-file-min-size 1E (1E for one exabyte) should be large enough. @@ -706,7 +706,7 @@ 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) .TP 20 -/ , --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. This option does not apply to archive reparing. +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. This option does not apply to archive repairing. .RS .PP 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). @@ -789,7 +789,7 @@ 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. .PP -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: +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-colon ';' 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: .TP 5 -/ "{<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. @@ -868,24 +868,24 @@ In this case instead, if entry are of the same type, the user will be asked what to. .TP 5 -/ "{!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. +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-colon ';') 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. .RE .TP 20 -^, --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. .TP 20 -_, --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. +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 colon character (:), 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 minimum. 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. .RS .PP -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. +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/filtering feature: dar -+ new_arch -A old_arch -ak. .PP 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. .RE .PP .TP 20 -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. Note that decremental backup is not compatible with delta binary. +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 in 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. Note that decremental backup is not compatible with delta binary. .TP 20 -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). @@ -920,7 +920,7 @@ When creating, isolating, merging or repairing 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. .RS .PP -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. +A summary 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. .RE .TP 20 -<, --backup-hook-include <mask> @@ -969,7 +969,7 @@ --delta sig the resulting archive will hold no delta signature. Note that delta signature transfer is not possible when the archive of reference is read in sequential mode, thus delta signature is disabled when the archive of reference is read in sequential mode. .P -For isolation and merging operations, the behavior is sligthly different: +For isolation and merging operations, the behavior is slightly different: .B --delta sig option let dar transfer existing delta signatures from the original archive to the isolated/merged one but does not lead dar to compute delta signatures for files that do not have one, unless one of the @@ -978,18 +978,18 @@ or .B --exclude-delta-sig -option is specified; in that case the delta signatures are transfered/dropped and if not present calculated accordingly to these mask options. However note that it is not possible to calculate delta signature for unsaved files in the archive of reference (because the archive of reference does not hold their data) as well as for fully saved files when merging is performed keeping files compressed (see -ak option). Another restriction while merging concernes sparse files, it is not possible to calculate binary signature for file stored as sparse files, but if sparse file detection mechanism is activated at merging time, delta signature can be calculated for sparse files too even if it is missing in the reference archive. In short: if you want recalculation of delta signature while merging, do not keep file compressed (do not use -ak option) and if you want to avoid having sparse files excluded from the delta signature recalcutation, activate sparse file detection (use -ah option). Delta signature transfer is not possible for on-fly isolation, you need to do normal atchive isolation to obtain an isolated catalogue with delta signatures. +option is specified; in that case the delta signatures are transferred/dropped and if not present calculated accordingly to these mask options. However note that it is not possible to calculate delta signature for unsaved files in the archive of reference (because the archive of reference does not hold their data) as well as for fully saved files when merging is performed keeping files compressed (see -ak option). Another restriction while merging concerns sparse files, it is not possible to calculate binary signature for file stored as sparse files, but if sparse file detection mechanism is activated at merging time, delta signature can be calculated for sparse files too even if it is missing in the reference archive. In short: if you want recalculation of delta signature while merging, do not keep file compressed (do not use -ak option) and if you want to avoid having sparse files excluded from the delta signature recalculation, activate sparse file detection (use -ah option). Delta signature transfer is not possible for on-fly isolation, you need to do normal archive isolation to obtain an isolated catalogue with delta signatures. .RE .TP 20 -8, --delta sig:<function>:<multiplier>[:<divisor>[:<min>[:<max>]]] -this variant of '--delta sig' option let you specify the block len used to build delta signatures. Larger values reduce CPU load required to build delta signature, but also lead to less accuracy when computing delta binary, which means larger delta patch and more data saved when a file has changed. The block length is calculated following the formula: +this variant of '--delta sig' option let you specify the block length used to build delta signatures. Larger values reduce CPU load required to build delta signature, but also lead to less accuracy when computing delta binary, which means larger delta patch and more data saved when a file has changed. The block len is calculated following the formula: .B block_len = function(filesize)*multiplier/divisor -If this calculated value is lower than "min", it is set to min. If the calculated value is greater than "max" it is set to max unless max is set to zero in which case the value is kept as is. Of course "divisor" cannot be null. The avalaible functions are: +If this calculated value is lower than "min", it is set to min. If the calculated value is greater than "max" it is set to max unless max is set to zero in which case the value is kept as is. Of course "divisor" cannot be null. The available functions are: .RS .TP 5 fixed -always returns 1, in other terms, the block size is indepent from the file size to build delta signature for +always returns 1, in other terms, the block size is independent from the file size to build delta signature for .TP linear returns the filesize. here, you will most of the time use 1 for multiplier and increase divisor to at least 10 for it makes sense @@ -998,7 +998,7 @@ returns the upper rounded power of 2 to the file size (base 2 logarithm). .TP square2 -returns the approximated value of the square root of the file size. Note that for better performance and as accurary is not important here, this function is implemented as exp2(log2(filesize)/2) where exp2 and log2 are based ont the integer left and right bit shift operations. +returns the approximated value of the square root of the file size. Note that for better performance and as accuracy is not important here, this function is implemented as exp2(log2(filesize)/2) where exp2 and log2 are based on the integer left and right bit shift operations. .TP square3 returns the approximated value of the cube root of filesize, implemented as exp2(log(filesize)/3) @@ -1034,7 +1034,7 @@ For merging or isolation operations, when .B --delta sig -is used no delta signature is computed only existing ones are transfered as is without restriction. To change that behavior and thus either drop or add delta signature to files that did not have one in the archive of reference, specify an combination of +is used no delta signature is computed only existing ones are transferred as is without restriction. To change that behavior and thus either drop or add delta signature to files that did not have one in the archive of reference, specify an combination of .B --include-delta-sig or @@ -1065,14 +1065,14 @@ option to be set. By default, this minimum size is 10 kio. The same option suffixes (k for kilo, M for mega, G for giga, T, ...) as the ones available with --slice option can be used here too. Using zero as argument gives the same result as not specifying this option at all (default size). .TP 20 -8, --delta no-patch -In the context of differential backup, this option leads dar to never consider files for delta binary even if delta signatures are present. By default delta binary (rsync-like) operation is performed when a file has changed since the archive of reference was made *and* if a delta signature could be found in the archive of reference for that file (or in the isolated catalogue used as reference for the incremental/differential backup). If no delta signature could be found or if --delta no-patch is used, the normal behavoir is done, which consist of saving that whole file in the archive. Note that if the archive of reference is read in sequential mode, the +In the context of differential backup, this option leads dar to never consider files for delta binary even if delta signatures are present. By default delta binary (rsync-like) operation is performed when a file has changed since the archive of reference was made *and* if a delta signature could be found in the archive of reference for that file (or in the isolated catalogue used as reference for the incremental/differential backup). If no delta signature could be found or if --delta no-patch is used, the normal behavior is done, which consist of saving that whole file in the archive. Note that if the archive of reference is read in sequential mode, the .B --delta no patch -is implicitely used as reading in sequential mode an archive does not let skipping backward to fetch the delta signature necessary to setup a delta patch. +is implicitly used as reading in sequential mode an archive does not let skipping backward to fetch the delta signature necessary to setup a delta patch. .P Binary delta options usage and best practices: .RS -First it must be understood that binary delta has advantages (less storage requirement) and drawbacks: data corruption has a wider impact on the ability to restore a given file, restoration of incrementaly backed up file may ask much more than one archive to be used. To limit the impact of the first drawback, dar binary delta is done per file, not globally on the total amount of saved data. You are also strongly encoraged to protect your backups with parity data using par2 (see dar_par.dcf file in the examples section of the documentation). Adding par2 data will increase storage requirement by a little, but usually much less than the amount gained using binary delta. Last drawback, binary delta relies on checksum (contained in the delta signature) and not on the real data to build the binary delta. There is chances that two different files provide the same checksum, even if the chances are very low, probability is not null. The consequence is that using binary delta the risk exists that the restored data do not match the original data and this will not be noticed by the librsync library on which libdar relies for that feature. Dar adds a second level of checksum, to detect data corruption inside the archive and to check that the file the delta patch is about to be applied is the expected base file, this reduces the risk of "collision" but does not remove it completely. After these warnings, let's now see the best practices about binary delta: +First it must be understood that binary delta has advantages (less storage requirement) and drawbacks: data corruption has a wider impact on the ability to restore a given file, restoration of incrementally backed up file may ask much more than one archive to be used. To limit the impact of the first drawback, dar binary delta is done per file, not globally on the total amount of saved data. You are also strongly encouraged to protect your backups with parity data using par2 (see dar_par.dcf file in the examples section of the documentation). Adding par2 data will increase storage requirement by a little, but usually much less than the amount gained using binary delta. Last drawback, binary delta relies on checksum (contained in the delta signature) and not on the real data to build the binary delta. There is chances that two different files provide the same checksum, even if the chances are very low, probability is not null. The consequence is that using binary delta the risk exists that the restored data do not match the original data and this will not be noticed by the librsync library on which libdar relies for that feature. Dar adds a second level of checksum, to detect data corruption inside the archive and to check that the file the delta patch is about to be applied is the expected base file, this reduces the risk of "collision" but does not remove it completely. After these warnings, let's now see the best practices about binary delta: .P Once a full backup has been done using --delta sig, any differential backup made based on this archive will use binary diff for file having a delta signature present in the full backup. If you always make differential (not incremental) backups based on such full backup you have nothing more specific to do in regard to binary delta, dar will handle it transparently. In particular you do not need to invoke --delta sig at subsequent backup, this saves space in differential archives as well as CPU cycles. .P @@ -1091,17 +1091,17 @@ 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. .TP 20 -\\, --ignored-as-symlink <absolute path>[:<absolute path>[:...]] -When dar reach an inode which is part of this provided column separated list, if this inode is not a symlink this option has no effect, but if it is a symlinks dar saves the file the symlink points to and not the symlink itself as dar does by default. In particular, if the pointed to inode is a directory dar recurses in that directory. You can also pass this list as argument to the DAR_IGNORED_AS_SYMLINK environment instead of using --ignored-as-symlink (which takes precedence over the environment variable). +When dar reach an inode which is part of this provided colon-separated list, if this inode is not a symlink this option has no effect, but if it is a symlinks dar saves the file the symlink points to and not the symlink itself as dar does by default. In particular, if the pointed to inode is a directory dar recurses in that directory. You can also pass this list as argument to the DAR_IGNORED_AS_SYMLINK environment instead of using --ignored-as-symlink (which takes precedence over the environment variable). .TP 20 -'\\'', --modified-data-detection=any-inode-change, --modified-data-detection=mtime-and-size -Before release 2.6.0, during a differential/incremental backup if any part of a file's inode metadata changed (ownership, permission, ...) even if the mtime (last modification time) and file size stood the same, dar had no choice than resaving the whole file for backup to record the metadata changes. This lead to a waste of backup time and space if in fact and for example only the ownership had been modified. You can still keep this historical behavior by invoking the +Before release 2.6.0, during a differential/incremental backup if any part of a file's inode metadata changed (ownership, permission, ...) even if the mtime (last modification time) and file size stood the same, dar had no choice than re-saving the whole file for backup to record the metadata changes. This lead to a waste of backup time and space if in fact and for example only the ownership had been modified. You can still keep this historical behavior by invoking the .B --modified-data-detection=any-inode-change option. -Since release 2.6.0 a new entry status ("inode-only") has been added. Dar can now resave only metadata when the inode change does not concern the data. To know whether the data has changed or not, by default (no --modified-data-detection option given) dar looks at mtime and at file's size only. Specifying --modified-data-detection=mtime-and-size (which is the default behavior) can be used to revert the action of --modified-data-detection=any-inode-change for example when playing with included files (DCF files): the latest met takes precedence. +Since release 2.6.0 a new entry status ("inode-only") has been added. Dar can now re-save only metadata when the inode change does not concern the data. To know whether the data has changed or not, by default (no --modified-data-detection option given) dar looks at mtime and at file's size only. Specifying --modified-data-detection=mtime-and-size (which is the default behavior) can be used to revert the action of --modified-data-detection=any-inode-change for example when playing with included files (DCF files): the latest met takes precedence. .TP 20 -T, --kdf-param <integer>[:<hash algo>] -At the difference of the listing context (see below), in the context of archive creation, merging and isolation, -T option let you define the interation count used to derive the archive key from the passphrase you provided (archive encryption context) and the hash algorithm used for that. The default value is 200,000 iterations and sha1 algorithm. -T has another older meaning when doing archive listing, but due to the lack of free character to create a new CLI option, there was no other choice than recycling an existing option not used in the context of archive creation/merging/isolation. The consequence is that the -T option must appear after the -+/-c/-C options for the operational context to be known at the time the -T option is met and its --kdf-param meaning to be taken into account. As --kdf-param is an alias to -T, this long form of this option must also be found after the use of either -c, -C or -+ option. The suffixes described for -s option are also available here (k, M, G, T, P, ...) however pay attention to the -aSI/-abinary mode which default to binary, in which case "-T 1k" is equivalent to "-T 1024". +At the difference of the listing context (see below), in the context of archive creation, merging and isolation, -T option let you define the iteration count used to derive the archive key from the passphrase you provided (archive encryption context) and the hash algorithm used for that. The default value is 200,000 iterations and sha1 algorithm. -T has another older meaning when doing archive listing, but due to the lack of free character to create a new CLI option, there was no other choice than recycling an existing option not used in the context of archive creation/merging/isolation. The consequence is that the -T option must appear after the -+/-c/-C options for the operational context to be known at the time the -T option is met and its --kdf-param meaning to be taken into account. As --kdf-param is an alias to -T, this long form of this option must also be found after the use of either -c, -C or -+ option. The suffixes described for -s option are also available here (k, M, G, T, P, ...) however pay attention to the -aSI/-abinary mode which default to binary, in which case "-T 1k" is equivalent to "-T 1024". .PP .PP .B RESTORATION SPECIFIC OPTIONS (to use with -x) @@ -1149,7 +1149,7 @@ .RS 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. 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) .PP -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. Last, -Tslicing and --sequential-read options are not compatible except for isolated catalogues. +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 re-sliced (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. Last, -Tslicing and --sequential-read options are not compatible except for isolated catalogues. .RE .TP 20 -as, --alter=saved @@ -1226,7 +1226,7 @@ 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. .TP 10 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. +In -Tslice mode, each file is given the range of slices it is located in. If slice size is chosen particularly 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. .PP .SH EXPLICIT OPTIONAL ARGUMENTS @@ -1504,13 +1504,13 @@ .SH ENVIRONMENT .TP 10 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. +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 colon (:) separated list of paths and look in each of them in turn, up to the first file found under the requested name. .TP 10 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. +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 colon (:) separated list of paths and looks in each of them in turn, up to the first file found under the requested name. .TP 10 DAR_SFTP_KNOWNHOSTS_FILE -if set, dar will not use the $HOME/.ssh/known_hosts file to check sftp remote server authenticity but the file given as value for this environment variable. Note that setting this variable to an empty string completely disable host validation, which is not recommended. Dar, the command line interface program for disk archive relies on libdar for archive format management which relies on libcurl for network transfer which in turn relies on libssh2 for all that concerns ssh/sftp protocol. In the known_hosts file, libssh2 does not support recent lines like those with "ecdsa-sha2-nistp256" in second argument before its release 1.9.0 (you will also need curl/libcurl 7.69.1 or more recent), in these old versions you only have support for "ssh-rsa" lines. Check libssh2 and libcurl documentations and litterature for more details about that limitation. The workaround, if you have not yet libssh2 1.9.0 or more recent, is to disable known hosts validation or set up a restricted known hosts file without any "ecdsa*" entry and have DAR_SFTP_KNOWNHOSTS_FILE pointing to it. +if set, dar will not use the $HOME/.ssh/known_hosts file to check sftp remote server authenticity but the file given as value for this environment variable. Note that setting this variable to an empty string completely disable host validation, which is not recommended. Dar, the command line interface program for disk archive relies on libdar for archive format management which relies on libcurl for network transfer which in turn relies on libssh2 for all that concerns ssh/sftp protocol. In the known_hosts file, libssh2 does not support recent lines like those with "ecdsa-sha2-nistp256" in second argument before its release 1.9.0 (you will also need curl/libcurl 7.69.1 or more recent), in these old versions you only have support for "ssh-rsa" lines. Check libssh2 and libcurl documentations and literature for more details about that limitation. The workaround, if you have not yet libssh2 1.9.0 or more recent, is to disable known hosts validation or set up a restricted known hosts file without any "ecdsa*" entry and have DAR_SFTP_KNOWNHOSTS_FILE pointing to it. .TP 10 DAR_SFTP_PUBLIC_KEYFILE by default dar will fetch the public key file in $HOME/.ssh/id_rsa.pub file. If you use the former id_dsa.pub or more recent key types you need to set this environment variable to point to the appropriated filename @@ -1519,10 +1519,10 @@ by default dar will fetch the public key file in $HOME/.ssh/id_rsa file. If you use the former id_dsa.pub or more recent key types you need to set this environment variable to point to the appropriated filename .TP 10 DAR_IGNORED_AS_SYMLINK -receive a column separated list of absolute paths, which if they are symlinks are not saved as symlink but as the inode they point to. For more details see the --ignored-as-symlink option above. +receive a colon separated list of absolute paths, which if they are symlinks are not saved as symlink but as the inode they point to. For more details see the --ignored-as-symlink option above. .TP 10 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: +for asymmetric 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: .RS .PP export GNUPGHOME=~myaccount/.gnupg