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