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 </refsect1>
  35
  36 <refsect1><title>PROPERTIES</title>
  37
  38 <para>This section lists the properties that control amgtar's functionality.
  39 See <manref name="amanda-applications" vol="7"/>
  40 for information on application properties and how they are configured.</para>
  41
  42 <!-- PLEASE KEEP THIS LIST IN ALPHABETICAL ORDER -->
  43 <variablelist>
  44  <!-- ==== -->
  45  <varlistentry><term>ATIME-PRESERVE</term><listitem>
  46 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".
  47 </listitem></varlistentry>
  48  <!-- ==== -->
  49  <varlistentry><term>CHECK-DEVICE</term><listitem>
  50 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.
  51 </listitem></varlistentry>
  52  <!-- ==== -->
  53  <varlistentry><term>COMMAND-OPTIONS</term><listitem>
  54 <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>
  55 Use:
  56 <programlisting>
  57   property "COMMAND-OPTIONS" "--foo" "bar"
  58 </programlisting>
  59 Do not use:
  60 <programlisting>
  61   property "COMMAND-OPTIONS" "--foo bar"
  62 </programlisting>
  63 </listitem></varlistentry>
  64  <!-- ==== -->
  65  <varlistentry><term>DIRECTORY</term><listitem>
  66 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.
  67 </listitem></varlistentry>
  68  <!-- ==== -->
  69  <varlistentry><term>GNUTAR-LISTDIR</term><listitem>
  70 The directory where gnutar stores the database it uses to generate incremental dumps.  The default is set when Amanda is built.
  71 </listitem></varlistentry>
  72  <!-- ==== -->
  73  <varlistentry><term>GNUTAR-PATH</term><listitem>
  74 The path to the gnutar binary.  The default is set when Amanda is built.
  75 </listitem></varlistentry>
  76  <!-- ==== -->
  77  <varlistentry><term>INCLUDE-LIST-GLOB</term><listitem>
  78 A filename containing include glob expression for the restore command.
  79 </listitem></varlistentry>
  80  <!-- ==== -->
  81  <varlistentry><term>EXCLUDE-LIST-GLOB</term><listitem>
  82 A filename containing exclude glob expression for the restore command.
  83 </listitem></varlistentry>
  84  <!-- ==== -->
  85  <varlistentry><term>ONE-FILE-SYSTEM</term><listitem>
  86 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.
  87 </listitem></varlistentry>
  88  <!-- ==== -->
  89  <varlistentry><term>TAR-BLOCKSIZE</term><listitem>
  90 Block size of Nx512 bytes (default N=20).  This corresponds to the <emphasis>--blocking-factor</emphasis> option of gnutar.
  91 </listitem></varlistentry>
  92  <!-- ==== -->
  93  <varlistentry><term>SPARSE</term><listitem>
  94 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.
  95 </listitem></varlistentry>
  96  <!-- ==== -->
  97  <varlistentry><term>NO-UNQUOTE</term><listitem>
  98 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.
  99 </listitem></varlistentry>
 100  <!-- ==== -->
 101  <varlistentry><term>ACLS</term><listitem>
 102 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.
 103 </listitem></varlistentry>
 104  <!-- ==== -->
 105  <varlistentry><term>SELINUX</term><listitem>
 106 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.
 107 </listitem></varlistentry>
 108  <!-- ==== -->
 109  <varlistentry><term>XATTRS</term><listitem>
 110 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.
 111 </listitem></varlistentry>
 112  <!-- ==== -->
 113  <varlistentry><term>EXIT-HANDLING</term><listitem>
 114 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.
 115 </listitem></varlistentry>
 116  <!-- ==== -->
 117  <varlistentry><term>NORMAL</term><listitem>
 118 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:
 119 <programlisting>
 120   "^could not open conf file"
 121   "^Elapsed time:"
 122   "^Throughput"
 123   ": socket ignored$"
 124   ": File .* shrunk by [0-9][0-9]* bytes, padding with zeros"
 125   ": Cannot add file .*: No such file or directory$"
 126   ": Error exit delayed from previous errors"
 127 </programlisting>
 128 <para>To treat one of these default patterns differently, specify it explicitly in a different property.</para>
 129 </listitem></varlistentry>
 130  <!-- ==== -->
 131  <varlistentry><term>IGNORE</term><listitem>
 132 List all regex (POSIX Extended Regular Expression syntax) that amanda ignore. These output are never in the email report. Default values:
 133 <programlisting>
 134   ": Directory is new$"
 135   ": Directory has been renamed"
 136 </programlisting>
 137 <para>To treat one of these default patterns differently, specify it explicitly in a different property.</para>
 138 </listitem></varlistentry>
 139  <!-- ==== -->
 140  <varlistentry><term>STRANGE</term><listitem>
 141 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.
 142 </listitem></varlistentry>
 143  <!-- ==== -->
 144  <varlistentry><term>VERBOSE</term><listitem>
 145 Default: "NO". If "YES", amgtar print more verbose debugging message and can leave temporary files in AMANDA_TMPDIR.
 146 </listitem></varlistentry>
 147 </variablelist>
 148
 149 </refsect1>
 150
 151 <refsect1><title>INCLUDE AND EXCLUDE LISTS</title>
 152
 153 <para>This application supplies exclude lists via the &gnutar;
 154 <option>--exclude-from</option> option.  This option accepts normal
 155 shell-style wildcard expressions, using <option>*</option> to match any
 156 number of characters and <option>?</option> to match a single character.
 157 Character classes are represented with <option>[..]</option>, which will
 158 match any of the characters in the brackets.  Expressions can be "anchored"
 159 to the base directory of the DLE by prefixing them with "./".  Without this
 160 prefix, they will match at any directory level.  Expressions that begin or
 161 end with a "/" will not match anything: to completely exclude a directory,
 162 do not include the trailing slash.  Example expressions:
 163 <programlisting>
 164   ./temp-files           # exclude top-level directory entirely
 165   ./temp-files/          # BAD: does nothing
 166   /temp-files            # BAD: does nothing
 167   ./temp-files/*         # exclude directory contents; include directory
 168   temp-files             # exclude anything named "temp-files"
 169   generated-*            # exclude anything beginning with "generated-"
 170   *.iso                  # exclude ISO files
 171   proxy/local/cache      # exclude "cache" in dir "local" in "proxy"
 172 </programlisting>
 173 </para>
 174
 175 <para>Similarly, include expressions are supplied to &gnutar;'s
 176 <option>--files-from</option> option.  This option ordinarily does not
 177 accept any sort of wildcards, but amgtar "manually" applies glob pattern
 178 matching to include expressions with only one slash.  The expressions must
 179 still begin with "./", so this effectively only allows expressions like
 180 "./[abc]*" or "./*.txt".</para>
 181
 182 </refsect1>
 183
 184 <refsect1><title>EXAMPLE</title>
 185 <para>
 186 <programlisting>
 187   define application-tool app_amgtar {
 188     plugin "amgtar"
 189
 190     property "ATIME-PRESERVE" "NO"
 191     property "CHECK-DEVICE" "YES"
 192     property "GNUTAR-LISTDIR" "/path/to/listdir"
 193     property "GNUTAR-PATH" "/bin/tar"
 194     property "ONE-FILE-SYSTEM" "YES"
 195     property "TAR-BLOCKSIZE" "20"
 196     property "SPARSE" "YES"
 197     property "ACLS" "NO"
 198     property "SELINUX" "NO"
 199     property "XATTRS" "NO"
 200     property "EXIT-HANDLING" "1=GOOD 2=BAD"
 201     # change a default NORMAL regex to a STRANGE regex.
 202     property "STRANGE" ": socket ignored$"
 203     # add three new IGNORE regex
 204     property "IGNORE" ": Directory is new$"
 205     property append "IGNORE" ": Directory has been renamed"
 206     property append "IGNORE" "file changed as we read it$"
 207   }
 208 </programlisting>
 209 A dumptype using this application might look like:
 210 <programlisting>
 211   define dumptype amgtar_app_dtyp {
 212     global
 213     program "APPLICATION"
 214     application "app_amgtar"
 215   }
 216 </programlisting>
 217 Note that the <emphasis>program</emphasis> parameter must be set to
 218 <emphasis>"APPLCIATION"</emphasis> to use the <emphasis>application</emphasis>
 219 parameter.
 220 </para>
 221 </refsect1>
 222
 223 <seealso>
 224 <manref name="tar" vol="1"/>,
 225 <manref name="amanda.conf" vol="5"/>,
 226 <manref name="amanda-applications" vol="7"/>
 227 </seealso>
 228
 229 </refentry>