Ubuntu Manpage: amgtar - Amanda Application to interface with GNU Tar

Provided by: amanda-common_3.5.1-11_amd64

NAME

       amgtar - Amanda Application to interface with GNU Tar

DESCRIPTION

       Amgtar is an Amanda Application API script. It should not be run by users directly. It
       uses GNU Tar to backup and restore data.

       The diskdevice in the disklist (DLE) must be the directory to backup.

PROPERTIES

This section lists the properties that control amgtar's functionality. See amanda-
applications(7) for information on application properties and how they are configured.

ATIME-PRESERVE

If "YES" (the default), amgtar use the --atime-preserve=system option of gnutar to not
update the atime of all files accessed; if "NO", gnutar will updates the atime for all
files accessed. This property works only if you have gnutar 1.15.90 or newer, if not,
you must set ATIME_PRESERVE to "NO".

CHECK-DEVICE

If "YES" (the default), amgtar checks that the device number doesn't change for each
file. If "NO", changes in device number are ignored. To ignore device numbers, tar
must support the --no-check-device option (gnutar 1.19.90 and newer). This option is
needed for some filesystems and devices on which device numbers change frequently,
such as LVM or FiberChannel.

COMMAND-OPTIONS
If set, theses options are passed asis to gtar. Each option must be a different value
of the property. Some option can break how amanda do backup, use it with care.

Use:
property "COMMAND-OPTIONS" "--foo" "bar"

Do not use:
property "COMMAND-OPTIONS" "--foo bar"

DIRECTORY

If set, gnutar will backup from that directory instead of the diskdevice set by the
DLE. On restore, the data is restore in that directory instead of the current working
directory.

GNUTAR-LISTDIR

The directory where gnutar stores the database it uses to generate incremental dumps.
The default is set when Amanda is built.

GNUTAR-PATH

The path to the gnutar binary. The default is set when Amanda is built.

IGNORE-ZEROS

If "YES" (the default), use the --ignore-zeros argument of gtar on recovery, set it to
"NO" if you do not want that argument.

INCLUDE-LIST-GLOB

A filename containing include glob expression for the restore command.

EXCLUDE-LIST-GLOB

A filename containing exclude glob expression for the restore command.

ONE-FILE-SYSTEM

If "YES" (the default), do not allow gnutar to cross filesystem boundaries. If "NO",
gnutar will cross filesystem boundaries. This corresponds to the --one-filesystem
option of gnutar.

TAR-BLOCKSIZE

Block size of Nx512 bytes (default N=20). This corresponds to the --blocking-factor
option of gnutar.

SPARSE

If "YES" (the default), gnutar will store sparse files efficiently. If "NO", then the
--sparse option is not given to gnutar, and it will not try to detect sparse files.

NO-UNQUOTE

If "NO" (the default), gnutar doesn't get the --no-unquote option and the diskname
can't have some characters, eg. '\'. If "YES", then the --no-unquote option is given
to gnutar and the diskname can have any characters. This option is available only if
you are using tar-1.16 or newer.

ACLS

Default "NO". If "YES", gnutar will preserve ACL extended attributes. This corresponds
to the --acls gnutar option. Requires a GNU Tar with nonstandard extended attribute
patches from the Fedora Project.

SELINUX

Default "NO". If "YES", gnutar will preserve SELinux extended attributes on Linux.
This corresponds to the --selinux gnutar option. Requires a GNU Tar with nonstandard
extended attribute patches from the Fedora Project.

XATTRS

Default "NO". If "YES", gnutar will preserve all extended attributes. This corresponds
to the --xattrs gnutar option. If enabled, this option also implies the ACLS and
SELINUX properties, regardless of their settings, as they are implemented as extended
attributes. Requires a GNU Tar with nonstandard extended attribute patches from the
Fedora Project.

EXIT-HANDLING

List which exit status of gtar are good or bad. eg. "1=GOOD 2=BAD", exit status of 1
will produce a good backup, exit status of 2 will give an error.

NORMAL

List all regex (POSIX Extended Regular Expression syntax) that are normal output from
gtar. These output are in the "FAILED DUMP DETAILS" section of the email report if the
dump result is STRANGE or FAILED. Default values:
"^could not open conf file"
"^Elapsed time:"
"^Throughput"
": socket ignored$"
": File .* shrunk by [0-9][0-9]* bytes, padding with zeros"
": Cannot add file .*: No such file or directory$"
": Error exit delayed from previous errors"
": directory is on a different filesystem; not dumped"
To treat one of these default patterns differently, specify it explicitly in a
different property.

IGNORE

List all regex (POSIX Extended Regular Expression syntax) that amanda ignore. These
output are never in the email report. Default values:
": Directory is new$"
": Directory has been renamed"
To treat one of these default patterns differently, specify it explicitly in a
different property.

STRANGE

List all regex (POSIX Extended Regular Expression syntax) that are strange output from
gtar. All gtar output that doesn't match a normal or ignore regex are strange by
default. The result of the dump is STRANGE if gtar produce a strange output. These
output are in the "FAILED DUMP DETAILS" section of the email report.

VERBOSE

Default: "NO". If "YES", amgtar print more verbose debugging message and can leave
temporary files in AMANDA_TMPDIR.

INCLUDE AND EXCLUDE LISTS

This application supplies exclude lists via the GNU-tar--exclude-from option. This option
accepts normal shell-style wildcard expressions, using * to match any number of characters
and ? to match a single character. Character classes are represented with [..], which
will match any of the characters in the brackets. Expressions can be "anchored" to the
base directory of the DLE by prefixing them with "./". Without this prefix, they will
match at any directory level. Expressions that begin or end with a "/" will not match
anything: to completely exclude a directory, do not include the trailing slash. Example
expressions:

./temp-files # exclude top-level directory entirely
./temp-files/ # BAD: does nothing
/temp-files # BAD: does nothing
./temp-files/* # exclude directory contents; include directory
temp-files # exclude anything named "temp-files"
generated-* # exclude anything beginning with "generated-"
*.iso # exclude ISO files
proxy/local/cache # exclude "cache" in dir "local" in "proxy"

Similarly, include expressions are supplied to GNU-tar's --files-from option. This option
ordinarily does not accept any sort of wildcards, but amgtar "manually" applies glob
pattern matching to include expressions with only one slash. The expressions must still
begin with "./", so this effectively only allows expressions like "./[abc]*" or "./*.txt".

EXAMPLE

         define application-tool app_amgtar {
           plugin "amgtar"

           property "ATIME-PRESERVE" "NO"
           property "CHECK-DEVICE" "YES"
           property "GNUTAR-LISTDIR" "/path/to/listdir"
           property "GNUTAR-PATH" "/bin/tar"
           property "ONE-FILE-SYSTEM" "YES"
           property "TAR-BLOCKSIZE" "20"
           property "SPARSE" "YES"
           property "ACLS" "NO"
           property "SELINUX" "NO"
           property "XATTRS" "NO"
           property "EXIT-HANDLING" "1=GOOD 2=BAD"
           # change a default NORMAL regex to a STRANGE regex.
           property "STRANGE" ": socket ignored$"
           # add three new IGNORE regex
           property "IGNORE" ": Directory is new$"
           property append "IGNORE" ": Directory has been renamed"
           property append "IGNORE" "file changed as we read it$"
         }
       A dumptype using this application might look like:

         define dumptype amgtar_app_dtyp {
           global
           program "APPLICATION"
           application "app_amgtar"
         }
       Note that the program parameter must be set to "APPLICATION" to use the application
       parameter.

AUTHORS