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

   1 '\" t
   2 .\"     Title: amgtar
   3 .\"    Author: Jean-Louis Martineau <martineau@zmanda.com>
   4 .\" Generator: DocBook XSL Stylesheets vsnapshot_8273 <http://docbook.sf.net/>
   5 .\"      Date: 10/18/2010
   6 .\"    Manual: System Administration Commands
   7 .\"    Source: Amanda 3.2.0
   8 .\"  Language: English
   9 .\"
  10 .TH "AMGTAR" "8" "10/18/2010" "Amanda 3\&.2\&.0" "System Administration Commands"
  11 .\" -----------------------------------------------------------------
  12 .\" * set default formatting
  13 .\" -----------------------------------------------------------------
  14 .\" disable hyphenation
  15 .nh
  16 .\" disable justification (adjust text to left margin only)
  17 .ad l
  18 .\" -----------------------------------------------------------------
  19 .\" * MAIN CONTENT STARTS HERE *
  20 .\" -----------------------------------------------------------------
  21 .SH "NAME"
  22 amgtar \- Amanda Application to interface with GNU Tar
  23 .SH "DESCRIPTION"
  24 .PP
  25 Amgtar is an Amanda Application API script\&. It should not be run by users directly\&. It uses GNU Tar to backup and restore data\&.
  26 .SH "PROPERTIES"
  27 .PP
  28 This section lists the properties that control amgtar\'s functionality\&. See
  29 \fBamanda-applications\fR(7)
  30 for information on application properties and how they are configured\&.
  31 .PP
  32 ATIME\-PRESERVE
  33 .RS 4
  34
  35 If "YES" (the default), amgtar use the \fI\-\-atime\-preserve=system\fR 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"\&.
  36 .RE
  37 .PP
  38 CHECK\-DEVICE
  39 .RS 4
  40
  41 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\&.
  42 .RE
  43 .PP
  44 COMMAND\-OPTIONS
  45 .RS 4
  46 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\&.
  47
  48 Use:
  49 .nf
  50   property "COMMAND\-OPTIONS" "\-\-foo" "bar"
  51 .fi
  52
  53 Do not use:
  54 .nf
  55   property "COMMAND\-OPTIONS" "\-\-foo bar"
  56 .fi
  57 .RE
  58 .PP
  59 DIRECTORY
  60 .RS 4
  61
  62 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\&.
  63 .RE
  64 .PP
  65 GNUTAR\-LISTDIR
  66 .RS 4
  67
  68 The directory where gnutar stores the database it uses to generate incremental dumps\&.  The default is set when Amanda is built\&.
  69 .RE
  70 .PP
  71 GNUTAR\-PATH
  72 .RS 4
  73
  74 The path to the gnutar binary\&.  The default is set when Amanda is built\&.
  75 .RE
  76 .PP
  77 INCLUDE\-LIST\-GLOB
  78 .RS 4
  79
  80 A filename containing include glob expression for the restore command\&.
  81 .RE
  82 .PP
  83 EXCLUDE\-LIST\-GLOB
  84 .RS 4
  85
  86 A filename containing exclude glob expression for the restore command\&.
  87 .RE
  88 .PP
  89 ONE\-FILE\-SYSTEM
  90 .RS 4
  91
  92 If "YES" (the default), do not allow gnutar to cross filesystem boundaries\&. If "NO", gnutar will cross filesystem boundaries\&.  This corresponds to the \fI\-\-one\-filesystem\fR option of gnutar\&.
  93 .RE
  94 .PP
  95 TAR\-BLOCKSIZE
  96 .RS 4
  97
  98 Block size of Nx512 bytes (default N=20)\&.  This corresponds to the \fI\-\-blocking\-factor\fR option of gnutar\&.
  99 .RE
 100 .PP
 101 SPARSE
 102 .RS 4
 103
 104 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\&.
 105 .RE
 106 .PP
 107 NO\-UNQUOTE
 108 .RS 4
 109
 110 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\&.
 111 .RE
 112 .PP
 113 ACLS
 114 .RS 4
 115
 116 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\&.
 117 .RE
 118 .PP
 119 SELINUX
 120 .RS 4
 121
 122 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\&.
 123 .RE
 124 .PP
 125 XATTRS
 126 .RS 4
 127
 128 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\&.
 129 .RE
 130 .PP
 131 EXIT\-HANDLING
 132 .RS 4
 133
 134 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\&.
 135 .RE
 136 .PP
 137 NORMAL
 138 .RS 4
 139
 140 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:
 141 .nf
 142   "^could not open conf file"
 143   "^Elapsed time:"
 144   "^Throughput"
 145   ": socket ignored$"
 146   ": File \&.* shrunk by [0\-9][0\-9]* bytes, padding with zeros"
 147   ": Cannot add file \&.*: No such file or directory$"
 148   ": Error exit delayed from previous errors"
 149 .fi
 150 To treat one of these default patterns differently, specify it explicitly in a different property\&.
 151 .RE
 152 .PP
 153 IGNORE
 154 .RS 4
 155
 156 List all regex (POSIX Extended Regular Expression syntax) that amanda ignore\&. These output are never in the email report\&. Default values:
 157 .nf
 158   ": Directory is new$"
 159   ": Directory has been renamed"
 160 .fi
 161 To treat one of these default patterns differently, specify it explicitly in a different property\&.
 162 .RE
 163 .PP
 164 STRANGE
 165 .RS 4
 166
 167 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\&.
 168 .RE
 169 .PP
 170 VERBOSE
 171 .RS 4
 172
 173 Default: "NO"\&. If "YES", amgtar print more verbose debugging message and can leave temporary files in AMANDA_TMPDIR\&.
 174 .RE
 175 .SH "INCLUDE AND EXCLUDE LISTS"
 176 .PP
 177 This application supplies exclude lists via the
 178 \fBGNU\-tar\fR
 179 \fB\-\-exclude\-from\fR
 180 option\&. This option accepts normal shell\-style wildcard expressions, using
 181 \fB*\fR
 182 to match any number of characters and
 183 \fB?\fR
 184 to match a single character\&. Character classes are represented with
 185 \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:
 186 .sp
 187 .nf
 188   \&./temp\-files           # exclude top\-level directory entirely
 189   \&./temp\-files/          # BAD: does nothing
 190   /temp\-files            # BAD: does nothing
 191   \&./temp\-files/*         # exclude directory contents; include directory
 192   temp\-files             # exclude anything named "temp\-files"
 193   generated\-*            # exclude anything beginning with "generated\-"
 194   *\&.iso                  # exclude ISO files
 195   proxy/local/cache      # exclude "cache" in dir "local" in "proxy"
 196 .fi
 197 .PP
 198 Similarly, include expressions are supplied to
 199 \fBGNU\-tar\fR\'s
 200 \fB\-\-files\-from\fR
 201 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"\&.
 202 .SH "EXAMPLE"
 203 .PP
 204
 205 .sp
 206 .nf
 207   define application\-tool app_amgtar {
 208     plugin "amgtar"
 209
 210     property "ATIME\-PRESERVE" "NO"
 211     property "CHECK\-DEVICE" "YES"
 212     property "GNUTAR\-LISTDIR" "/path/to/listdir"
 213     property "GNUTAR\-PATH" "/bin/tar"
 214     property "ONE\-FILE\-SYSTEM" "YES"
 215     property "TAR\-BLOCKSIZE" "20"
 216     property "SPARSE" "YES"
 217     property "ACLS" "NO"
 218     property "SELINUX" "NO"
 219     property "XATTRS" "NO"
 220     property "EXIT\-HANDLING" "1=GOOD 2=BAD"
 221     # change a default NORMAL regex to a STRANGE regex\&.
 222     property "STRANGE" ": socket ignored$"
 223     # add three new IGNORE regex
 224     property "IGNORE" ": Directory is new$"
 225     property append "IGNORE" ": Directory has been renamed"
 226     property append "IGNORE" "file changed as we read it$"
 227   }
 228 .fi
 229 A dumptype using this application might look like:
 230 .sp
 231 .nf
 232   define dumptype amgtar_app_dtyp {
 233     global
 234     program "APPLICATION"
 235     application "app_amgtar"
 236   }
 237 .fi
 238 Note that the
 239 \fIprogram\fR
 240 parameter must be set to
 241 \fI"APPLCIATION"\fR
 242 to use the
 243 \fIapplication\fR
 244 parameter\&.
 245 .SH "SEE ALSO"
 246 .PP
 247 \fBamanda\fR(8),
 248 \fBtar\fR(1),
 249 \fBamanda.conf\fR(5),
 250 \fBamanda-applications\fR(7)
 251 .PP
 252 The Amanda Wiki:
 253 : http://wiki.zmanda.com/
 254 .SH "AUTHORS"
 255 .PP
 256 \fBJean\-Louis Martineau\fR <\&martineau@zmanda\&.com\&>
 257 .RS 4
 258 Zmanda, Inc\&. (http://www\&.zmanda\&.com)
 259 .RE
 260 .PP
 261 \fBDustin J\&. Mitchell\fR <\&dustin@zmanda\&.com\&>
 262 .RS 4
 263 Zmanda, Inc\&. (http://www\&.zmanda\&.com)
 264 .RE