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