+'\" t
.\" Title: amgtar
.\" Author: Jean-Louis Martineau <martineau@zmanda.com>
-.\" Generator: DocBook XSL Stylesheets v1.74.0 <http://docbook.sf.net/>
-.\" Date: 01/22/2009
+.\" Generator: DocBook XSL Stylesheets vsnapshot_8273 <http://docbook.sf.net/>
+.\" Date: 10/18/2010
.\" Manual: System Administration Commands
-.\" Source: Amanda 2.6.1
+.\" Source: Amanda 3.2.0
.\" Language: English
.\"
-.TH "AMGTAR" "8" "01/22/2009" "Amanda 2\&.6\&.1" "System Administration Commands"
-.\" -----------------------------------------------------------------
-.\" * (re)Define some macros
-.\" -----------------------------------------------------------------
-.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-.\" toupper - uppercase a string (locale-aware)
-.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-.de toupper
-.tr aAbBcCdDeEfFgGhHiIjJkKlLmMnNoOpPqQrRsStTuUvVwWxXyYzZ
-\\$*
-.tr aabbccddeeffgghhiijjkkllmmnnooppqqrrssttuuvvwwxxyyzz
-..
-.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-.\" SH-xref - format a cross-reference to an SH section
-.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-.de SH-xref
-.ie n \{\
-.\}
-.toupper \\$*
-.el \{\
-\\$*
-.\}
-..
-.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-.\" SH - level-one heading that works better for non-TTY output
-.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-.de1 SH
-.\" put an extra blank line of space above the head in non-TTY output
-.if t \{\
-.sp 1
-.\}
-.sp \\n[PD]u
-.nr an-level 1
-.set-an-margin
-.nr an-prevailing-indent \\n[IN]
-.fi
-.in \\n[an-margin]u
-.ti 0
-.HTML-TAG ".NH \\n[an-level]"
-.it 1 an-trap
-.nr an-no-space-flag 1
-.nr an-break-flag 1
-\." make the size of the head bigger
-.ps +3
-.ft B
-.ne (2v + 1u)
-.ie n \{\
-.\" if n (TTY output), use uppercase
-.toupper \\$*
-.\}
-.el \{\
-.nr an-break-flag 0
-.\" if not n (not TTY), use normal case (not uppercase)
-\\$1
-.in \\n[an-margin]u
-.ti 0
-.\" if not n (not TTY), put a border/line under subheading
-.sp -.6
-\l'\n(.lu'
-.\}
-..
-.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-.\" SS - level-two heading that works better for non-TTY output
-.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-.de1 SS
-.sp \\n[PD]u
-.nr an-level 1
-.set-an-margin
-.nr an-prevailing-indent \\n[IN]
-.fi
-.in \\n[IN]u
-.ti \\n[SN]u
-.it 1 an-trap
-.nr an-no-space-flag 1
-.nr an-break-flag 1
-.ps \\n[PS-SS]u
-\." make the size of the head bigger
-.ps +2
-.ft B
-.ne (2v + 1u)
-.if \\n[.$] \&\\$*
-..
-.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-.\" BB/BE - put background/screen (filled box) around block of text
-.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-.de BB
-.if t \{\
-.sp -.5
-.br
-.in +2n
-.ll -2n
-.gcolor red
-.di BX
-.\}
-..
-.de EB
-.if t \{\
-.if "\\$2"adjust-for-leading-newline" \{\
-.sp -1
-.\}
-.br
-.di
-.in
-.ll
-.gcolor
-.nr BW \\n(.lu-\\n(.i
-.nr BH \\n(dn+.5v
-.ne \\n(BHu+.5v
-.ie "\\$2"adjust-for-leading-newline" \{\
-\M[\\$1]\h'1n'\v'+.5v'\D'P \\n(BWu 0 0 \\n(BHu -\\n(BWu 0 0 -\\n(BHu'\M[]
-.\}
-.el \{\
-\M[\\$1]\h'1n'\v'-.5v'\D'P \\n(BWu 0 0 \\n(BHu -\\n(BWu 0 0 -\\n(BHu'\M[]
-.\}
-.in 0
-.sp -.5v
-.nf
-.BX
-.in
-.sp .5v
-.fi
-.\}
-..
-.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-.\" BM/EM - put colored marker in margin next to block of text
-.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-.de BM
-.if t \{\
-.br
-.ll -2n
-.gcolor red
-.di BX
-.\}
-..
-.de EM
-.if t \{\
-.br
-.di
-.ll
-.gcolor
-.nr BH \\n(dn
-.ne \\n(BHu
-\M[\\$1]\D'P -.75n 0 0 \\n(BHu -(\\n[.i]u - \\n(INu - .75n) 0 0 -\\n(BHu'\M[]
-.in 0
-.nf
-.BX
-.in
-.fi
-.\}
-..
+.TH "AMGTAR" "8" "10/18/2010" "Amanda 3\&.2\&.0" "System Administration Commands"
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
-.SH "Name"
+.SH "NAME"
amgtar \- Amanda Application to interface with GNU Tar
.SH "DESCRIPTION"
.PP
-Amgtar is an
-\fIAmanda\fR
-Application API script\&. It should not be run by users directly\&. It uses GNU Tar to backup and restore data\&.
+Amgtar is an Amanda Application API script\&. It should not be run by users directly\&. It uses GNU Tar to backup and restore data\&.
.SH "PROPERTIES"
.PP
This section lists the properties that control amgtar\'s functionality\&. See
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 \fI\-\-no\-check\-device\fR 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\&.
.RE
.PP
+COMMAND\-OPTIONS
+.RS 4
+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:
+.nf
+ property "COMMAND\-OPTIONS" "\-\-foo" "bar"
+.fi
+
+Do not use:
+.nf
+ property "COMMAND\-OPTIONS" "\-\-foo bar"
+.fi
+.RE
+.PP
DIRECTORY
.RS 4
-If set, gnutar will backup from that directory instead of the \fIdiskdevice\fR set by the DLE\&.
+If set, gnutar will backup from that directory instead of the \fIdiskdevice\fR set by the DLE\&. On restore, the data is restore in that directory instead of the current working directory\&.
.RE
.PP
GNUTAR\-LISTDIR
.RS 4
-The directory where gnutar stores the database it uses to generate incremental dumps\&. The default is set when \fIAmanda\fR is built\&.
+The directory where gnutar stores the database it uses to generate incremental dumps\&. The default is set when Amanda is built\&.
.RE
.PP
GNUTAR\-PATH
.RS 4
-The path to the gnutar binary\&. The default is set when \fIAmanda\fR is built\&.
+The path to the gnutar binary\&. The default is set when Amanda is built\&.
+.RE
+.PP
+INCLUDE\-LIST\-GLOB
+.RS 4
+
+A filename containing include glob expression for the restore command\&.
+.RE
+.PP
+EXCLUDE\-LIST\-GLOB
+.RS 4
+
+A filename containing exclude glob expression for the restore command\&.
.RE
.PP
ONE\-FILE\-SYSTEM
If "YES" (the default), gnutar will store sparse files efficiently\&. If "NO", then the \fI\-\-sparse\fR option is not given to gnutar, and it will not try to detect sparse files\&.
.RE
.PP
+NO\-UNQUOTE
+.RS 4
+
+If "NO" (the default), gnutar doesn\'t get the \fI\-\-no\-unquote\fR option and the diskname can\'t have some characters, eg\&. \'\e\'\&. If "YES", then the \fI\-\-no\-unquote\fR 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\&.
+.RE
+.PP
+ACLS
+.RS 4
+
+Default "NO"\&. If "YES", gnutar will preserve ACL extended attributes\&. This corresponds to the \fI\-\-acls\fR gnutar option\&. Requires a GNU Tar with nonstandard extended attribute patches from the Fedora Project\&.
+.RE
+.PP
+SELINUX
+.RS 4
+
+Default "NO"\&. If "YES", gnutar will preserve SELinux extended attributes on Linux\&. This corresponds to the \fI\-\-selinux\fR gnutar option\&. Requires a GNU Tar with nonstandard extended attribute patches from the Fedora Project\&.
+.RE
+.PP
+XATTRS
+.RS 4
+
+Default "NO"\&. If "YES", gnutar will preserve all extended attributes\&. This corresponds to the \fI\-\-xattrs\fR 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\&.
+.RE
+.PP
EXIT\-HANDLING
.RS 4
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\&.
.RE
+.PP
+VERBOSE
+.RS 4
+
+Default: "NO"\&. If "YES", amgtar print more verbose debugging message and can leave temporary files in AMANDA_TMPDIR\&.
+.RE
+.SH "INCLUDE AND EXCLUDE LISTS"
+.PP
+This application supplies exclude lists via the
+\fBGNU\-tar\fR
+\fB\-\-exclude\-from\fR
+option\&. This option accepts normal shell\-style wildcard expressions, using
+\fB*\fR
+to match any number of characters and
+\fB?\fR
+to match a single character\&. Character classes are represented with
+\fB[\&.\&.]\fR, 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:
+.sp
+.nf
+ \&./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"
+.fi
+.PP
+Similarly, include expressions are supplied to
+\fBGNU\-tar\fR\'s
+\fB\-\-files\-from\fR
+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"\&.
.SH "EXAMPLE"
+.PP
+
+.sp
.nf
define application\-tool app_amgtar {
+ plugin "amgtar"
+
property "ATIME\-PRESERVE" "NO"
property "CHECK\-DEVICE" "YES"
- property "GNUTAR\-LISTDIR" "
+ property "GNUTAR\-LISTDIR" "/path/to/listdir"
property "GNUTAR\-PATH" "/bin/tar"
property "ONE\-FILE\-SYSTEM" "YES"
- property "TAR_BLOCKSIZE" "20"
+ 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$"
property append "IGNORE" "file changed as we read it$"
}
.fi
+A dumptype using this application might look like:
+.sp
+.nf
+ define dumptype amgtar_app_dtyp {
+ global
+ program "APPLICATION"
+ application "app_amgtar"
+ }
+.fi
+Note that the
+\fIprogram\fR
+parameter must be set to
+\fI"APPLCIATION"\fR
+to use the
+\fIapplication\fR
+parameter\&.
.SH "SEE ALSO"
.PP
-
+\fBamanda\fR(8),
+\fBtar\fR(1),
\fBamanda.conf\fR(5),
\fBamanda-applications\fR(7)
-.SH "Authors"
+.PP
+The Amanda Wiki:
+: http://wiki.zmanda.com/
+.SH "AUTHORS"
.PP
\fBJean\-Louis Martineau\fR <\&martineau@zmanda\&.com\&>
.RS 4
-Zmanda, Inc\&. (\FChttp://www\&.zmanda\&.com\F[])
+Zmanda, Inc\&. (http://www\&.zmanda\&.com)
.RE
.PP
\fBDustin J\&. Mitchell\fR <\&dustin@zmanda\&.com\&>
.RS 4
-Zmanda, Inc\&. (\FChttp://www\&.zmanda\&.com\F[])
+Zmanda, Inc\&. (http://www\&.zmanda\&.com)
.RE