git.gag.com Git - debian/amanda/blob - docs/exclude.txt

   1
   2          Chapter 3. Excluding
   3 Prev  Part I. Installation  Next
   4
   5 -------------------------------------------------------------------------------
   6
   7 Chapter 3. Excluding
   8
   9
  10 Andrew Hall
  11
  12 Original text
  13
  14 Stefan G. Weichinger
  15
  16 XML-conversion;Updates
  17 AMANDA Core Team
  18 <sgw@amanda.org>
  19 Table of Contents
  20
  21
  22   Introduction
  23
  24   Please_Read
  25
  26   Before_We_Begin
  27
  28   Choosing_an_exclude_mechanism
  29
  30
  31         Exclude_Mechanisms
  32
  33
  34   Expression
  35
  36   Wildcard_Expansion
  37
  38   Troubleshooting
  39
  40
  41         Broken_gnutar?
  42
  43         The_ps_command_is_your_friend.
  44
  45
  46
  47 Note
  48
  49 Refer to http://www.amanda.org/docs/exclude.html for the current version of
  50 this document.
  51
  52  Introduction
  53
  54 There are times when data needs to be excluded from a backup. When these times
  55 arise be confident that AMANDA has this capability. (Actually it's not AMANDA,
  56 it's tar.) There are three ways of excluding data in an AMANDA backup:
  57
  58 * Exclude an individual item explicitly in the dumptype
  59 * Utilize an "Exclude List"
  60 * Do not include the data in the disklist
  61
  62 This document is based on AMANDA 2.4.2 and some of this might not work with
  63 older versions. This was compiled from my personal experience and with help
  64 from the members of the amanda-users mailing list (mailto://amanda-
  65 users@amanda.org) when I was originally setting this up, to whom I wish to
  66 thank for all of their support.
  67
  68  Please Read
  69
  70 As far as I am able to tell the only way to exclude files or directories with
  71 AMANDA is to use GNU-tar as the dump program (others?). The file system dump
  72 programs provided with unix systems (e.g. dump, ufsdump) get data at a raw
  73 drive level and generally do not allow exclusion of specific files or
  74 directories.
  75 The GNU version of tar, (GNU-tar or gtar), reads its data at a file system, (or
  76 higher), level and does include the option to exclude specific files and/or
  77 directories. It should be mentioned here that tar will change the access times
  78 on files. Tar has the ability to preserve the access times however, doing so
  79 effectively disables incremental backups since resetting the access time alters
  80 the inode change time, which in turn causes the file to look like it needs to
  81 be archived again.
  82 The only exception that I am aware of is to just not include the data in
  83 question in the disklist. This option may not be suitable for everyone's needs
  84 and can confuse the issue some, so I have elected to include this mechanism in
  85 its own section named Do_not_include_the_data_in_the_disklist.
  86 For the purpose of this document an AMANDA backup configuration named "exclude-
  87 test" will be used. The machine that contains the tape drive which receives
  88 data to be archived will be referred to as "SERVER". The machine that data is
  89 being archived from will be referred to as "CLIENT". These two systems are
  90 usually different machines but are not required to be, and may be the same
  91 machine. Parts of this setup are on the server and some are on the client.
  92
  93 Note
  94
  95 When AMANDA attempts to exclude a file or directory it does so relative to the
  96 area being archived. For example if /var is in your disklist and you want to
  97 exclude /var/log/somefile, then your exclude file would contain ./log/somefile.
  98 You may use one exclude file in multiple dumptypes without any restriction.
  99
 100  Before We Begin
 101
 102 The first step that should be taken is to verify that backups are currently
 103 working. Connect to SERVER and run amcheck as your AMANDA user, to verify that
 104 there are no errors in the current setup.
 105
 106   $ amcheck -cl CLIENT
 107
 108 Output should look something like below for success:
 109
 110         AMANDA Tape Server Host Check
 111         -----------------------------
 112
 113         /path/to/holding-disk: 4771300 KB disk space available, that's plenty.
 114         AMANDA Backup Client Hosts Check
 115         --------------------------------
 116         Client check: 1 host checked in 0.084 seconds, 0 problems found.
 117
 118 Next make sure that GNU-tar is the dump program currently in use. The easiest
 119 way to tell if your dumptype is using gnutar is to run the following:
 120
 121   $ amadmin exclude-test disklist CLIENT
 122
 123 Among all the output is the "program" value currently in use. This value is
 124 also specified with the "program" option in the dumptype. If the dumptype has
 125 the line "program GNUTAR" your setup should be ready to exclude data.
 126 If GNU-tar is not in use add the line "program GNUTAR" to the dumptype, and
 127 then run amcheck again to verify that backups should work. The capitalization
 128 of GNUTAR is required.
 129 The dumptype should look something like:
 130
 131   define dumptype exclude-test {
 132   comment "test dumptype for documentation"
 133   priority high
 134   program "GNUTAR"
 135   }
 136
 137
 138  Choosing an exclude mechanism
 139
 140 If the need is to exclude only one file or directory then the easiest way to
 141 accomplish this is to exclude an individual item explicitly in the dumptype. If
 142 the need is to exclude multiple files or directories then use an Exclude List.
 143
 144  Exclude Mechanisms
 145
 146
 147  Exclude an individual item explicitly in the dumptype
 148
 149 The easiest way to exclude a file or directory is to specify it with the
 150 "exclude" option in the dumptype. This option accepts an argument of the file
 151 or directory to be excluded. AMANDA allows only one exclude option in any
 152 dumptype at a time.
 153
 154 Note
 155
 156 UPDATE: Recent AMANDA-releases bring the option "exclude append" which enables
 157 the administrator to define more than one exclusion-pattern within one dumptype
 158 without using a exclude-list. Please look at the amanda.8-manpage for details.
 159 Any path specified to be excluded must be encapsulated with quotes. Continuing
 160 with our example from above /var/log/somefile and using the same dumptype as
 161 above, the dumptype would now look like:
 162
 163   define dumptype exclude-test {
 164   comment "test dumptype for documentation"
 165   priority high
 166   program "GNUTAR"
 167   exclude "./log/somefile"
 168   }
 169
 170 Next run amcheck again to verify that there are no problems with the revised
 171 AMANDA configuration. If the data is not being excluded as expected please see
 172 the Troubleshooting section below. This completes the setup of excluding an
 173 individual item in the dumptype.
 174
 175  Utilize an Exclude List
 176
 177 An exclude list is a file that resides on the CLIENT machine and contains paths
 178 to be excluded, one per line. This file can be in any location on the CLIENT so
 179 long as the same path is specified in the dumptype. Some find /usr/local/etc/
 180 amanda an appropriate location, but it is up to you. I personally like to have
 181 a subdirectory for exclude files but it is up to you where you place this file.
 182 The exclude file may also be placed in the area being archived. This is an easy
 183 way to have a different exclusion file for each disklist entry without needing
 184 separate dumptype definitions. To use this technique, enter a path relative to
 185 the area being archived as the exclude file below instead of an absolute path.
 186 Connect to CLIENT and create the exclude directory as root. For example:
 187
 188   $ mkdir -p /usr/local/etc/amanda/exclude
 189   $ cd /usr/local/etc/amanda/exclude
 190
 191 Next create the exclude list for AMANDA to use. You can name the exclude file
 192 anything you wish it to be. Create a file, and in this file place all paths to
 193 files and directories that are to be excluded. Keeping with the /var example,
 194 assume that /var/log/XFree86.0.log, and /var/log/maillog need to be excluded.
 195 Remember that all paths are relative. The exclude list would look like:
 196
 197   ./log/XFree86.0.log
 198   ./log/maillog
 199
 200 Make sure that permissions are restricted on this file. Run the following as
 201 root, where exclude-filename is the name of the file you just created. For
 202 example:
 203
 204   $ chmod 644 /usr/local/etc/amanda/exclude/exclude-filename
 205
 206 This concludes the necessary configuration on the client.
 207 Connect to SERVER and cd to the exclude-test AMANDA configuration directory.
 208 Edit the AMANDA configuration file e.g. amanda.conf. Add an entry similar to
 209 the following line, to the dumptype for the client in question, where the
 210 exclude-filename is the file that was created on CLIENT in the step above
 211 including the quotes. For example:
 212
 213   exclude list "/usr/local/etc/amanda/exclude/exclude-filename"
 214
 215 The new dumptype should look something like:
 216
 217   define dumptype exclude-test{
 218   comment "test dumptype for documentation"
 219   priority high
 220   program "GNUTAR"
 221   exclude list "/usr/local/etc/amanda/exclude/exclude-filename"
 222   }
 223
 224 Save the file. Run amcheck again to verify that there are no problems with the
 225 revised AMANDA configuration. If amcheck succeeds then run amdump to verify the
 226 data is being excluded correctly. If the data is not being excluded as expected
 227 please see the Troubleshooting section below. This completes the setup of an
 228 exclude list.
 229
 230  Do not include the data in the disklist
 231
 232 AMANDA uses disklist entries to define which directories or partitions should
 233 be archived. This allows us to exclude data by just not placing the data in
 234 question in the disklist. Assume that there is a disk mounted on /example. The
 235 directory /example has five subdirectories "a", "b", "c", "d", and "e". The
 236 directories "a", "b", and "c" need to be archived, while "d" and "e" should
 237 not. This can be accomplished by not specifying "d" and "e" in the disklist.
 238 Using the same dumptype and host in the above examples the disklist would
 239 contain:
 240
 241   CLIENT /examples/a    exclude-test
 242   CLIENT /examples/b    exclude-test
 243   CLIENT /examples/c    exclude-test
 244
 245 Run amcheck to verify that AMANDA is working correctly. If the data is not
 246 being excluded as expected please see the Troubleshooting section below. This
 247 completes the setup of using a disklist to exclude data.
 248
 249  Expression
 250
 251 Quiz: what is the difference between the following entries in an exclude list?
 252
 253   ./foo
 254   ./foo/
 255   ./foo/*
 256
 257 case 1 : directory ./foo won't be in the backup image (that's what you want)
 258 case 2 : matches nothing (don't use it) case 3 : directory ./foo will be in the
 259 backup image but nothing below it.
 260
 261  Wildcard Expansion
 262
 263 AMANDA has the ability to use wildcard expansion while excluding data as
 264 implemented by tar(1). The only places that wildcard expansion is allowed is in
 265 the "exclude" option in the dumptype, or in the exclude list. Some simple
 266 examples:
 267 Exclude any file or directory that ends in ".log" e.g. ppp.log, XFree86.0.log
 268
 269   ./*.log
 270
 271 Exclude any file or directory with the string "log" e.g. logfile, maillog,
 272 syslog, ppp.log, XFree86.0.log
 273
 274   */*log*
 275
 276 Exclude any file or directory that starts with string "cron" and ends in ".gz"
 277 e.g. cron.1.gz, cron.2.gz, log/cron.1.gz
 278
 279   ./*cron*.gz
 280
 281 The question mark can be used to specify a single character. e.g. log.1, log.2,
 282 etc
 283
 284   ./log.?
 285
 286
 287  Troubleshooting
 288
 289 If you find that you are having trouble getting the exclude patterns to match
 290 correctly, check out this really cool script written by John R. Jackson.
 291 ftp://gandalf.cc.purdue.edu/pub/amanda/gtartest-exclude
 292 This script allows you to test your patterns before placing them in an exclude
 293 list or in the dumptype. Instructions on how to run the script are included in
 294 the script.
 295
 296  Broken gnutar?
 297
 298 There are versions of GNU-tar that do not correctly exclude data. Version 1.12
 299 (plus the AMANDA patches from http://www.amanda.org) are known to work
 300 correctly, as does version 1.13.19 (and later). Anything else is questionable.
 301
 302 Note
 303
 304 UPDATE:Using GNU-tar 1.13.25 is recommended.
 305
 306  The ps command is your friend.
 307
 308 Connect to CLIENT and run a
 309
 310   ps ax | grep tar
 311
 312 (or
 313
 314   ps ef | grep tar
 315
 316 on Solaris)
 317 to see exactly how the tar command is running. Look in the output for the --
 318 exclude or --exclude-from options in the running tar process. For example:
 319
 320   $ ps ax | grep tar
 321
 322   ?        R      0:37 /bin/tar --create --directory /var
 323   --listed-incremental /var/lib/amanda/gnutar-lists/CLIENTvar_0.new
 324   --sparse --one-file-system --ignore-failed-read --totals --file
 325   /dev/null --exclude-from=/usr/local/etc/amanda/exclude-test/exclude.var
 326   .
 327
 328 In the above output notice the string "--exclude-from=". The string following
 329 the "=" is the exclude file currently in use. If the string was "--exclude"
 330 then the string following the "=" is the file or directory that is currently
 331 set to be excluded.
 332 Contact the amanda-users mailing list: mailto://amanda-users@amanda.org.
 333 Subscription information is available at http://www.amanda.org.
 334 -------------------------------------------------------------------------------
 335
 336 Prev                                   Up                              Next
 337 Chapter 2. AMANDA Installation Notes  Home  Chapter 4. Indexing with AMANDA
 338