git.gag.com Git - debian/amanda/blob - man/xml-source/amgtar.8.xml

   1 <?xml version="1.0" encoding="ISO-8859-1"?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
   3                    "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"
   4 [
   5   <!-- entities files to use -->
   6   <!ENTITY % global_entities SYSTEM 'global.entities'>
   7   %global_entities;
   8 ]>
   9
  10 <refentry id='amgtar.8'>
  11
  12 <refmeta>
  13 <refentrytitle>amgtar</refentrytitle>
  14 <manvolnum>8</manvolnum>
  15 &rmi.source;
  16 &rmi.version;
  17 &rmi.manual.8;
  18 </refmeta>
  19 <refnamediv>
  20 <refname>amgtar</refname>
  21 <refpurpose>Amanda Application to interface with GNU Tar</refpurpose>
  22 </refnamediv>
  23 <refentryinfo>
  24 &author.jlm;
  25 &author.dustin;
  26 </refentryinfo>
  27 <!-- body begins here -->
  28
  29 <refsect1><title>DESCRIPTION</title>
  30
  31 <para>Amgtar is an Amanda Application API script.  It should not be run
  32 by users directly.  It uses GNU Tar to backup and restore data.</para>
  33
  34 <para>The <emphasis remap='B'>diskdevice</emphasis> in the disklist (DLE)
  35 must be the directory to backup.</para>
  36
  37 </refsect1>
  38
  39 <refsect1><title>PROPERTIES</title>
  40
  41 <para>This section lists the properties that control amgtar's functionality.
  42 See <manref name="amanda-applications" vol="7"/>
  43 for information on application properties and how they are configured.</para>
  44
  45 <!-- PLEASE KEEP THIS LIST IN ALPHABETICAL ORDER -->
  46 <variablelist>
  47  <!-- ==== -->
  48  <varlistentry><term>ATIME-PRESERVE</term><listitem>
  49 If "YES" (the default), amgtar use the <emphasis>--atime-preserve=system</emphasis> 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".
  50 </listitem></varlistentry>
  51  <!-- ==== -->
  52  <varlistentry><term>CHECK-DEVICE</term><listitem>
  53 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 <emphasis>--no-check-device</emphasis> 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.
  54 </listitem></varlistentry>
  55  <!-- ==== -->
  56  <varlistentry><term>COMMAND-OPTIONS</term><listitem>
  57 <para>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.</para>
  58 Use:
  59 <programlisting>
  60   property "COMMAND-OPTIONS" "--foo" "bar"
  61 </programlisting>
  62 Do not use:
  63 <programlisting>
  64   property "COMMAND-OPTIONS" "--foo bar"
  65 </programlisting>
  66 </listitem></varlistentry>
  67  <!-- ==== -->
  68  <varlistentry><term>DIRECTORY</term><listitem>
  69 If set, gnutar will backup from that directory instead of the <emphasis>diskdevice</emphasis> set by the DLE. On restore, the data is restore in that directory instead of the current working directory.
  70 </listitem></varlistentry>
  71  <!-- ==== -->
  72  <varlistentry><term>GNUTAR-LISTDIR</term><listitem>
  73 The directory where gnutar stores the database it uses to generate incremental dumps.  The default is set when Amanda is built.
  74 </listitem></varlistentry>
  75  <!-- ==== -->
  76  <varlistentry><term>GNUTAR-PATH</term><listitem>
  77 The path to the gnutar binary.  The default is set when Amanda is built.
  78 </listitem></varlistentry>
  79  <!-- ==== -->
  80  <varlistentry><term>INCLUDE-LIST-GLOB</term><listitem>
  81 A filename containing include glob expression for the restore command.
  82 </listitem></varlistentry>
  83  <!-- ==== -->
  84  <varlistentry><term>EXCLUDE-LIST-GLOB</term><listitem>
  85 A filename containing exclude glob expression for the restore command.
  86 </listitem></varlistentry>
  87  <!-- ==== -->
  88  <varlistentry><term>ONE-FILE-SYSTEM</term><listitem>
  89 If "YES" (the default), do not allow gnutar to cross filesystem boundaries. If "NO", gnutar will cross filesystem boundaries.  This corresponds to the <emphasis>--one-filesystem</emphasis> option of gnutar.
  90 </listitem></varlistentry>
  91  <!-- ==== -->
  92  <varlistentry><term>TAR-BLOCKSIZE</term><listitem>
  93 Block size of Nx512 bytes (default N=20).  This corresponds to the <emphasis>--blocking-factor</emphasis> option of gnutar.
  94 </listitem></varlistentry>
  95  <!-- ==== -->
  96  <varlistentry><term>SPARSE</term><listitem>
  97 If "YES" (the default), gnutar will store sparse files efficiently. If "NO", then the <emphasis>--sparse</emphasis> option is not given to gnutar, and it will not try to detect sparse files.
  98 </listitem></varlistentry>
  99  <!-- ==== -->
 100  <varlistentry><term>NO-UNQUOTE</term><listitem>
 101 If "NO" (the default), gnutar doesn't get the <emphasis>--no-unquote</emphasis> option and the diskname can't have some characters, eg. '\'. If "YES", then the <emphasis>--no-unquote</emphasis> 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.
 102 </listitem></varlistentry>
 103  <!-- ==== -->
 104  <varlistentry><term>ACLS</term><listitem>
 105 Default "NO". If "YES", gnutar will preserve ACL extended attributes. This corresponds to the <emphasis>--acls</emphasis> gnutar option. Requires a GNU Tar with nonstandard extended attribute patches from the Fedora Project.
 106 </listitem></varlistentry>
 107  <!-- ==== -->
 108  <varlistentry><term>SELINUX</term><listitem>
 109 Default "NO". If "YES", gnutar will preserve SELinux extended attributes on Linux. This corresponds to the <emphasis>--selinux</emphasis> gnutar option. Requires a GNU Tar with nonstandard extended attribute patches from the Fedora Project.
 110 </listitem></varlistentry>
 111  <!-- ==== -->
 112  <varlistentry><term>XATTRS</term><listitem>
 113 Default "NO". If "YES", gnutar will preserve all extended attributes. This corresponds to the <emphasis>--xattrs</emphasis> 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.
 114 </listitem></varlistentry>
 115  <!-- ==== -->
 116  <varlistentry><term>EXIT-HANDLING</term><listitem>
 117 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.
 118 </listitem></varlistentry>
 119  <!-- ==== -->
 120  <varlistentry><term>NORMAL</term><listitem>
 121 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:
 122 <programlisting>
 123   "^could not open conf file"
 124   "^Elapsed time:"
 125   "^Throughput"
 126   ": socket ignored$"
 127   ": File .* shrunk by [0-9][0-9]* bytes, padding with zeros"
 128   ": Cannot add file .*: No such file or directory$"
 129   ": Error exit delayed from previous errors"
 130 </programlisting>
 131 <para>To treat one of these default patterns differently, specify it explicitly in a different property.</para>
 132 </listitem></varlistentry>
 133  <!-- ==== -->
 134  <varlistentry><term>IGNORE</term><listitem>
 135 List all regex (POSIX Extended Regular Expression syntax) that amanda ignore. These output are never in the email report. Default values:
 136 <programlisting>
 137   ": Directory is new$"
 138   ": Directory has been renamed"
 139 </programlisting>
 140 <para>To treat one of these default patterns differently, specify it explicitly in a different property.</para>
 141 </listitem></varlistentry>
 142  <!-- ==== -->
 143  <varlistentry><term>STRANGE</term><listitem>
 144 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.
 145 </listitem></varlistentry>
 146  <!-- ==== -->
 147  <varlistentry><term>VERBOSE</term><listitem>
 148 Default: "NO". If "YES", amgtar print more verbose debugging message and can leave temporary files in AMANDA_TMPDIR.
 149 </listitem></varlistentry>
 150 </variablelist>
 151
 152 </refsect1>
 153
 154 <refsect1><title>INCLUDE AND EXCLUDE LISTS</title>
 155
 156 <para>This application supplies exclude lists via the &gnutar;
 157 <option>--exclude-from</option> option.  This option accepts normal
 158 shell-style wildcard expressions, using <option>*</option> to match any
 159 number of characters and <option>?</option> to match a single character.
 160 Character classes are represented with <option>[..]</option>, which will
 161 match any of the characters in the brackets.  Expressions can be "anchored"
 162 to the base directory of the DLE by prefixing them with "./".  Without this
 163 prefix, they will match at any directory level.  Expressions that begin or
 164 end with a "/" will not match anything: to completely exclude a directory,
 165 do not include the trailing slash.  Example expressions:
 166 <programlisting>
 167   ./temp-files           # exclude top-level directory entirely
 168   ./temp-files/          # BAD: does nothing
 169   /temp-files            # BAD: does nothing
 170   ./temp-files/*         # exclude directory contents; include directory
 171   temp-files             # exclude anything named "temp-files"
 172   generated-*            # exclude anything beginning with "generated-"
 173   *.iso                  # exclude ISO files
 174   proxy/local/cache      # exclude "cache" in dir "local" in "proxy"
 175 </programlisting>
 176 </para>
 177
 178 <para>Similarly, include expressions are supplied to &gnutar;'s
 179 <option>--files-from</option> option.  This option ordinarily does not
 180 accept any sort of wildcards, but amgtar "manually" applies glob pattern
 181 matching to include expressions with only one slash.  The expressions must
 182 still begin with "./", so this effectively only allows expressions like
 183 "./[abc]*" or "./*.txt".</para>
 184
 185 </refsect1>
 186
 187 <refsect1><title>EXAMPLE</title>
 188 <para>
 189 <programlisting>
 190   define application-tool app_amgtar {
 191     plugin "amgtar"
 192
 193     property "ATIME-PRESERVE" "NO"
 194     property "CHECK-DEVICE" "YES"
 195     property "GNUTAR-LISTDIR" "/path/to/listdir"
 196     property "GNUTAR-PATH" "/bin/tar"
 197     property "ONE-FILE-SYSTEM" "YES"
 198     property "TAR-BLOCKSIZE" "20"
 199     property "SPARSE" "YES"
 200     property "ACLS" "NO"
 201     property "SELINUX" "NO"
 202     property "XATTRS" "NO"
 203     property "EXIT-HANDLING" "1=GOOD 2=BAD"
 204     # change a default NORMAL regex to a STRANGE regex.
 205     property "STRANGE" ": socket ignored$"
 206     # add three new IGNORE regex
 207     property "IGNORE" ": Directory is new$"
 208     property append "IGNORE" ": Directory has been renamed"
 209     property append "IGNORE" "file changed as we read it$"
 210   }
 211 </programlisting>
 212 A dumptype using this application might look like:
 213 <programlisting>
 214   define dumptype amgtar_app_dtyp {
 215     global
 216     program "APPLICATION"
 217     application "app_amgtar"
 218   }
 219 </programlisting>
 220 Note that the <emphasis>program</emphasis> parameter must be set to
 221 <emphasis>"APPLCIATION"</emphasis> to use the <emphasis>application</emphasis>
 222 parameter.
 223 </para>
 224 </refsect1>
 225
 226 <seealso>
 227 <manref name="tar" vol="1"/>,
 228 <manref name="amanda.conf" vol="5"/>,
 229 <manref name="amanda-applications" vol="7"/>
 230 </seealso>
 231
 232 </refentry>