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