1AMGTAR(8)               System Administration Commands               AMGTAR(8)
2
3
4

NAME

6       amgtar - Amanda Application to interface with GNU Tar
7

DESCRIPTION

9       Amgtar is an Amanda Application API script. It should not be run by
10       users directly. It uses GNU Tar to backup and restore data.
11
12       The diskdevice in the disklist (DLE) must be the directory to backup.
13

PROPERTIES

15       This section lists the properties that control amgtar's functionality.
16       See amanda-applications(7) for information on application properties
17       and how they are configured.
18
19       ATIME-PRESERVE
20
21           If "YES" (the default), amgtar use the --atime-preserve=system
22           option of gnutar to not update the atime of all files accessed; if
23           "NO", gnutar will updates the atime for all files accessed. This
24           property works only if you have gnutar 1.15.90 or newer, if not,
25           you must set ATIME_PRESERVE to "NO".
26
27       CHECK-DEVICE
28
29           If "YES" (the default), amgtar checks that the device number
30           doesn't change for each file. If "NO", changes in device number are
31           ignored.  To ignore device numbers, tar must support the
32           --no-check-device option (gnutar 1.19.90 and newer). This option is
33           needed for some filesystems and devices on which device numbers
34           change frequently, such as LVM or FiberChannel.
35
36       COMMAND-OPTIONS
37           If set, theses options are passed asis to gtar. Each option must be
38           a different value of the property. Some option can break how amanda
39           do backup, use it with care.
40
41           Use:
42             property "COMMAND-OPTIONS" "--foo" "bar"
43
44           Do not use:
45             property "COMMAND-OPTIONS" "--foo bar"
46
47       DIRECTORY
48
49           If set, gnutar will backup from that directory instead of the
50           diskdevice set by the DLE. On restore, the data is restore in that
51           directory instead of the current working directory.
52
53       GNUTAR-LISTDIR
54
55           The directory where gnutar stores the database it uses to generate
56           incremental dumps.  The default is set when Amanda is built.
57
58       GNUTAR-PATH
59
60           The path to the gnutar binary.  The default is set when Amanda is
61           built.
62
63       IGNORE-ZEROS
64
65           If "YES" (the default), use the --ignore-zeros argument of gtar on
66           recovery, set it to "NO" if you do not want that argument.
67
68       INCLUDE-LIST-GLOB
69
70           A filename containing include glob expression for the restore
71           command.
72
73       EXCLUDE-LIST-GLOB
74
75           A filename containing exclude glob expression for the restore
76           command.
77
78       ONE-FILE-SYSTEM
79
80           If "YES" (the default), do not allow gnutar to cross filesystem
81           boundaries. If "NO", gnutar will cross filesystem boundaries.  This
82           corresponds to the --one-filesystem option of gnutar.
83
84       TAR-BLOCKSIZE
85
86           Block size of Nx512 bytes (default N=20).  This corresponds to the
87           --blocking-factor option of gnutar.
88
89       SPARSE
90
91           If "YES" (the default), gnutar will store sparse files efficiently.
92           If "NO", then the --sparse option is not given to gnutar, and it
93           will not try to detect sparse files.
94
95       NO-UNQUOTE
96
97           If "NO" (the default), gnutar doesn't get the --no-unquote option
98           and the diskname can't have some characters, eg. '\'. If "YES",
99           then the --no-unquote option is given to gnutar and the diskname
100           can have any characters.  This option is available only if you are
101           using tar-1.16 or newer.
102
103       ACLS
104
105           Default "NO". If "YES", gnutar will preserve ACL extended
106           attributes. This corresponds to the --acls gnutar option. Requires
107           a GNU Tar with nonstandard extended attribute patches from the
108           Fedora Project.
109
110       SELINUX
111
112           Default "NO". If "YES", gnutar will preserve SELinux extended
113           attributes on Linux. This corresponds to the --selinux gnutar
114           option. Requires a GNU Tar with nonstandard extended attribute
115           patches from the Fedora Project.
116
117       XATTRS
118
119           Default "NO". If "YES", gnutar will preserve all extended
120           attributes. This corresponds to the --xattrs gnutar option. If
121           enabled, this option also implies the ACLS and SELINUX properties,
122           regardless of their settings, as they are implemented as extended
123           attributes. Requires a GNU Tar with nonstandard extended attribute
124           patches from the Fedora Project.
125
126       EXIT-HANDLING
127
128           List which exit status of gtar are good or bad. eg. "1=GOOD 2=BAD",
129           exit status of 1 will produce a good backup, exit status of 2 will
130           give an error.
131
132       NORMAL
133
134           List all regex (POSIX Extended Regular Expression syntax) that are
135           normal output from gtar. These output are in the "FAILED DUMP
136           DETAILS" section of the email report if the dump result is STRANGE
137           or FAILED. Default values:
138             "^could not open conf file"
139             "^Elapsed time:"
140             "^Throughput"
141             ": socket ignored$"
142             ": File .* shrunk by [0-9][0-9]* bytes, padding with zeros"
143             ": Cannot add file .*: No such file or directory$"
144             ": Error exit delayed from previous errors"
145             ": directory is on a different filesystem; not dumped"
146           To treat one of these default patterns differently, specify it
147           explicitly in a different property.
148
149       IGNORE
150
151           List all regex (POSIX Extended Regular Expression syntax) that
152           amanda ignore. These output are never in the email report. Default
153           values:
154             ": Directory is new$"
155             ": Directory has been renamed"
156           To treat one of these default patterns differently, specify it
157           explicitly in a different property.
158
159       STRANGE
160
161           List all regex (POSIX Extended Regular Expression syntax) that are
162           strange output from gtar. All gtar output that doesn't match a
163           normal or ignore regex are strange by default. The result of the
164           dump is STRANGE if gtar produce a strange output. These output are
165           in the "FAILED DUMP DETAILS" section of the email report.
166
167       VERBOSE
168
169           Default: "NO". If "YES", amgtar print more verbose debugging
170           message and can leave temporary files in AMANDA_TMPDIR.
171

INCLUDE AND EXCLUDE LISTS

173       This application supplies exclude lists via the GNU-tar--exclude-from
174       option. This option accepts normal shell-style wildcard expressions,
175       using * to match any number of characters and ?  to match a single
176       character. Character classes are represented with [..], which will
177       match any of the characters in the brackets. Expressions can be
178       "anchored" to the base directory of the DLE by prefixing them with
179       "./". Without this prefix, they will match at any directory level.
180       Expressions that begin or end with a "/" will not match anything: to
181       completely exclude a directory, do not include the trailing slash.
182       Example expressions:
183
184         ./temp-files           # exclude top-level directory entirely
185         ./temp-files/          # BAD: does nothing
186         /temp-files            # BAD: does nothing
187         ./temp-files/*         # exclude directory contents; include directory
188         temp-files             # exclude anything named "temp-files"
189         generated-*            # exclude anything beginning with "generated-"
190         *.iso                  # exclude ISO files
191         proxy/local/cache      # exclude "cache" in dir "local" in "proxy"
192
193       Similarly, include expressions are supplied to GNU-tar's --files-from
194       option. This option ordinarily does not accept any sort of wildcards,
195       but amgtar "manually" applies glob pattern matching to include
196       expressions with only one slash. The expressions must still begin with
197       "./", so this effectively only allows expressions like "./[abc]*" or
198       "./*.txt".
199

EXAMPLE

201         define application-tool app_amgtar {
202           plugin "amgtar"
203
204           property "ATIME-PRESERVE" "NO"
205           property "CHECK-DEVICE" "YES"
206           property "GNUTAR-LISTDIR" "/path/to/listdir"
207           property "GNUTAR-PATH" "/bin/tar"
208           property "ONE-FILE-SYSTEM" "YES"
209           property "TAR-BLOCKSIZE" "20"
210           property "SPARSE" "YES"
211           property "ACLS" "NO"
212           property "SELINUX" "NO"
213           property "XATTRS" "NO"
214           property "EXIT-HANDLING" "1=GOOD 2=BAD"
215           # change a default NORMAL regex to a STRANGE regex.
216           property "STRANGE" ": socket ignored$"
217           # add three new IGNORE regex
218           property "IGNORE" ": Directory is new$"
219           property append "IGNORE" ": Directory has been renamed"
220           property append "IGNORE" "file changed as we read it$"
221         }
222       A dumptype using this application might look like:
223
224         define dumptype amgtar_app_dtyp {
225           global
226           program "APPLICATION"
227           application "app_amgtar"
228         }
229       Note that the program parameter must be set to "APPLICATION" to use the
230       application parameter.
231

SEE ALSO

233       amanda(8), tar(1), amanda.conf(5), amanda-applications(7)
234
235       The Amanda Wiki: : http://wiki.zmanda.com/
236

AUTHORS

238       Jean-Louis Martineau <martineau@zmanda.com>
239           Zmanda, Inc. (http://www.zmanda.com)
240
241       Dustin J. Mitchell <dustin@zmanda.com>
242           Zmanda, Inc. (http://www.zmanda.com)
243
244
245
246Amanda 3.5.1                      12/01/2017                         AMGTAR(8)
Impressum