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

   1
   2 Chapter 15. How to use a wrapper
   3 Prev  Part III. HOWTOs      Next
   4
   5 -------------------------------------------------------------------------------
   6
   7 Chapter 15. How to use a wrapper
   8
   9
  10 Bert de Ridder
  11
  12 Original text
  13
  14 Paul Bijnens
  15
  16 Original text
  17
  18 Stefan G. Weichinger
  19
  20 XML-conversion; Updates
  21 AMANDA Core Team
  22 <sgw@amanda.org>
  23 Table of Contents
  24
  25
  26   Bert_de_Ridder's_suggestions
  27
  28   Paul_Bijnens's_suggestions
  29
  30
  31 Note
  32
  33 The script used in this document is not part of the official Amanda release.
  34 The Amanda core team does not take any responsibility for this script.
  35
  36 Bert de Ridder's suggestions
  37
  38 This is a mini-howto explaining how to control other running tasks on a server
  39 where the Amanda software is used to backup data.
  40 Problem : Lots of software is picky about their datafiles being backed up while
  41 the files are in use. It sometimes is even necessary to know the state of the
  42 datafiles at the moment of backup so that when restoring you know exactly
  43 *what* you are restoring. And most of the time there are dependencies between
  44 the datafiles as well (for instance, the pure datafiles and the controlfiles of
  45 an Oracle database.)
  46 The solution is actually quite simple; you just use a custom made backupscript
  47 instead of the standard tar command. Inside this tar command, you do some
  48 necessary processing before executing the tar command and - if necessary - do
  49 some more processing. This way, you can easily stop an Oracle database, tar the
  50 files, send them to the tape server and restart the Oracle database. This of
  51 course is just an example, anything you can do in a shell script can be done.
  52
  53   1. Create the script
  54      This is the most important step, this script is the work horse of the
  55      solution. I've called it /bin/amandatar. You can call it whatever you want
  56      though. It's a Perl script, it may not be very pretty code, but it does
  57      the job. In the script, an example is given for the backup of a Lotus
  58      Notes Domino server.
  59
  60        #!/usr/bin/perl
  61
  62        # Tar wrapper for Amanda's tar.
  63        #
  64
  65        use Getopt::Long qw(:config pass_through);
  66
  67        # Obtain directory and file information from the command line.
  68
  69        $result = GetOptions (
  70         'directory=s' => \$dir,
  71         'file=s' => \$file
  72        );
  73
  74        # Check whether Amanda wants to do some administrative task (eg.
  75        indexinfo
  76        # or obtain the number of bytes to be backed up)
  77        # if file = /dev/null it's an administrative task and most of the time,
  78        no extra
  79        #   processing is necessary.
  80
  81        # What you see here is just a log of the backup start time, and more
  82        important
  83        #   the stopping of the domino server
  84
  85        if ( $file ne '/dev/null' )
  86        {
  87          if ( $dir eq '/local/notesdata' )
  88          {
  89            system "echo 'Start backup notes at ' >> /var/lib/amanda/runtime" ;
  90            system "date >> /var/lib/amanda/runtime";
  91            system ( "/etc/init.d/domino stop >> /var/lib/amanda/runtime" );
  92          }
  93        }
  94
  95        # The command line is being 'reconstructed'. Necessary because the
  96        GetOptions
  97        #   call above has stripped the file and directory information.
  98        # This is what I meant with 'ugly'  code ;-)
  99
 100        while ( $ARGV[0] ne '' )
 101        {
 102          $val = $ARGV[0] ;
 103          unshift ( @NEWARGV, $val, ) ;
 104          shift @ARGV;
 105        }
 106
 107        while ( $NEWARGV[0] ne '' )
 108        {
 109          $val = $NEWARGV[0] ;
 110          unshift ( @ARGV, $val ) ;
 111          shift @NEWARGV;
 112        }
 113
 114        if ( $dir ne '' )
 115        {
 116          unshift ( @ARGV, '--directory', $dir );
 117        }
 118        if ( $file ne '' )
 119        {
 120          unshift ( @ARGV, '--file', $file );
 121        }
 122
 123        if ( $file ne '/dev/null' )
 124        {
 125          system "echo 'Backing up directory ' $dir >> /var/lib/amanda/runtime"
 126        ;
 127        }
 128
 129        # And finally make sure tar is called :-)
 130        #   (path may differ on your installation)
 131        unshift ( @ARGV , "/bin/tar" ) ;
 132
 133        system ( @ARGV ) ;
 134
 135        # Postprocessing
 136        #
 137        # If Notes backup was requested, restart the server.
 138        # Log the backup end time.
 139        #
 140
 141        if ( $file ne '/dev/null' )
 142        {
 143          if ( $dir eq '/local/notesdata' )
 144          {
 145            system ( "/etc/init.d/domino start >> /var/lib/amanda/runtime" );
 146            system "echo 'End backup notes at ' >> /var/lib/amanda/runtime" ;
 147            system "date >> /var/lib/amanda/runtime";
 148          }
 149        }
 150
 151        exit 0;
 152
 153        # End script
 154
 155      On some systems it may be necessary to setuid root the script.
 156   2. Rebuild Amanda so that it uses your newly created script.
 157      Download the sources, untar them to a directory. I'm sure there are lots
 158      of documents already available on how to do this, so I won't go into too
 159      much detail. (Refer to Amanda_Installation_Notes).
 160      fast path :
 161
 162        /usr/local/src # tar -xvzf amanda-source.tar.gz
 163        /usr/local/src # cd amanda-version
 164        /usr/local/src/amanda-version # ./configure \
 165          --with-user=amanda \
 166          --prefix=/usr/local \
 167          --exec-prefix=/usr \
 168          --bindir=/usr/bin \
 169          --sbindir=/usr/sbin \
 170          --libexecdir=/usr/lib/amanda \
 171          --with-configdir=/etc/amanda \
 172          --with-group=disk \
 173          --with-gnutar=/bin/amandatar \
 174          --with-gnutar-listdir=/var/lib/amanda/gnutar-lists \
 175          --with-tmpdir=/tmp/amanda \
 176          --with-smbclient=/usr/bin/smbclient \
 177          --mandir=/usr/local/man
 178
 179      Here, it may be necessary to adjust some paths to match your installation.
 180      This setup works on SuSE Linux (also SLES) and MacOSX although you may
 181      have to use another binary tar.
 182      As you see, you may also "replace" the smbclient if necessary. I haven't
 183      yet tested it though. I'll leave it as an exercise for the reader <g>.
 184
 185        /usr/local/src/amanda-version # make
 186        /usr/local/src/amanda-version # make install
 187
 188      Now proceed as with a "normal" installation.
 189
 190
 191 Paul Bijnens's suggestions
 192
 193 How do I run pre- and post dump programs, e.g. database stop/start?
 194 Currently (Amanda 2.4.5) there is no direct support to run a program before or
 195 after a backup on a client. But there is an easy workaround by using a wrapper
 196 for GNU-tar that does the additional tasks.
 197 Let's suppose you want to stop a database before the backup, and start it up
 198 again when the backup is finished. You have already two scripts "shutdb" and
 199 "startdb" to shutdown and startup the database.
 200 First you have to configure Amanda on the client to use the gnutar-wrapper
 201 instead of the real GNU-tar:
 202
 203   ./configure ... --with-gnutar=/usr/local/bin/amgtar ...
 204
 205 and re-compile Amanda. The program "amgtar" can be a simple link to the real
 206 GNU-tar-binary on clients that don't need special handling, or it can be a
 207 script.
 208 Amanda expects that the bytestream on stdout is the backup image, and the
 209 bytestream on stderr are messages. The stderr messages are filtered against a
 210 known set of strings, and anything unexpected is flagged as "STRANGE" in the
 211 Amanda report. The return-codes of the program should be the same as the
 212 return-codes of GNU-tar:
 213
 214 * 0 = ok (backup image will be put on tape)
 215 * 1 = not ok (backup image will not be put on tape, same level will be tried
 216   next time).
 217
 218 The arguments passed to the program are pretty static (see in the sources
 219 client-src/sendbackup-gnutar.c, line 483). To decide if you need to stop/start
 220 the database you have to check if:
 221
 222 * this run makes a backup and not a restore: look for "--create"
 223 * this it is not an estimate run: look for "--file /dev/null" (estimate) or "--
 224   file -" (real run)
 225 * this run is for the database directory: look for "--directory /my/data/base"
 226
 227 In all other cases, we just pass the args and run the real GNU-tar.
 228 Here is an example script in Bourne shell:
 229 Example 15.1.
 230
 231   #!/bin/sh
 232
 233   # # uncomment next block to follow the flow
 234   # LOG=/tmp/amanda/mytar.debug
 235   # date >> $LOG
 236   # echo "$@" >> $LOG
 237   # if [ "$3" = "/dev/null" ]
 238   # then echo "Estimate only" >> $LOG
 239   # else echo "Real backup" >> $LOG
 240   # fi
 241
 242   # - Avoid output to stdout! (the backup stream by tar)
 243   # - Any output to stderr is flagged as "strange" by amanda
 244   #   and may be used to pass error messages into the report
 245
 246   if [ "$1" = "--create"  -a  "$3" = "-"  -a  "$5" = "/my/dir" ]
 247   then
 248       # echo "/my/dir: want to execute some progs first" >>$LOG
 249       /usr/local/bin/shutdb thedb >&2
 250       /usr/local/bin/gtar "$@"
 251       rc=$?
 252       # echo "Finished the real backup; some postprocessing" >>$LOG
 253       /usr/local/bin/startdb thedb >&2
 254       exit $rc
 255   else
 256       /usr/local/bin/gtar "$@"
 257   fi
 258
 259
 260 Here is an example script in perl:
 261 Example 15.2.
 262
 263   #!/usr/bin/perl -w
 264
 265   use Getopt::Long qw(:config pass_through);
 266
 267   my @saveopts = @ARGV;
 268   GetOptions (
 269           'create' => \$create,
 270           'directory=s' => \$dir,
 271           'file=s' => \$file,
 272   );
 273   @ARGV = @saveopts;
 274
 275   my $postproc = 0;
 276   if ($create  &&  $dir eq '/my/data/base' &&  $file ne '/dev/null') {
 277       system '/usr/local/bin/dbshut thedb >/tmp/amanda/dbshut.debug 2>&1';
 278       $postproc = 1;
 279   }
 280
 281   unshift(@ARGV, "/usr/local/bin/gtar");
 282   system @ARGV;
 283
 284   my $rc = $? >> 8;
 285
 286   if ($postproc) {
 287       system '/usr/local/bin/dbstart thedb >/tmp/amanda/dbstart.debug 2>&1';
 288   }
 289
 290   exit $rc;
 291
 292
 293
 294 Note
 295
 296 Refer to http://www.amanda.org/docs/howto-wrapper.html for the current version
 297 of this document.
 298 -------------------------------------------------------------------------------
 299
 300 Prev                    Up                                            Next
 301 Chapter 14. AFS HOWTO  Home  Chapter 16. How to do Amanda-server-side gpg-
 302                                                         encrypted backups.
 303