2 Chapter 15. How to use a wrapper
3 Prev Part III. HOWTOs Next
5 -------------------------------------------------------------------------------
7 Chapter 15. How to use a wrapper
20 XML-conversion; Updates
26 Bert_de_Ridder's_suggestions
28 Paul_Bijnens's_suggestions
33 Refer to http://www.amanda.org/docs/howto-wrapper.html for the current version
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.
41 Bert de Ridder's suggestions
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
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.
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
67 # Tar wrapper for Amanda's tar.
70 use Getopt::Long qw(:config pass_through);
72 # Obtain directory and file information from the command line.
74 $result = GetOptions (
75 'directory=s' => \$dir,
79 # Check whether Amanda wants to do some administrative task (eg.
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,
84 # processing is necessary.
86 # What you see here is just a log of the backup start time, and
\96 more
88 # the stopping of the domino server
90 if ( $file ne '/dev/null' )
92 if ( $dir eq '/local/notesdata' )
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" );
100 # The command line is being 'reconstructed'. Necessary because the
102 # call above has stripped the file and directory information.
103 # This is what I meant with 'ugly' code ;-)
105 while ( $ARGV[0] ne '' )
108 unshift ( @NEWARGV, $val, ) ;
112 while ( $NEWARGV[0] ne '' )
115 unshift ( @ARGV, $val ) ;
121 unshift ( @ARGV, '--directory', $dir );
125 unshift ( @ARGV, '--file', $file );
128 if ( $file ne '/dev/null' )
130 system "echo 'Backing up directory ' $dir >> /var/lib/amanda/runtime"
134 # And finally make sure tar is called :-)
135 # (path may differ on your installation)
136 unshift ( @ARGV , "/bin/tar" ) ;
142 # If Notes backup was requested, restart the server.
143 # Log the backup end time.
146 if ( $file ne '/dev/null' )
148 if ( $dir eq '/local/notesdata' )
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";
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).
167 /usr/local/src # tar -xvzf amanda-source.tar.gz
168 /usr/local/src # cd amanda-version
169 /usr/local/src/amanda-version # ./configure \
171 --prefix=/usr/local \
174 --sbindir=/usr/sbin \
175 --libexecdir=/usr/lib/amanda \
176 --with-configdir=/etc/amanda \
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
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>.
190 /usr/local/src/amanda-version # make
191 /usr/local/src/amanda-version # make install
193 Now proceed as with a "normal" installation.
196 Paul Bijnens's suggestions
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:
208 ./configure ... --with-gnutar=/usr/local/bin/amgtar ...
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
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:
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
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:
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 "--
230 * this run is for the database directory: look for "--directory /my/data/base"
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:
238 # # uncomment next block to follow the flow
239 # LOG=/tmp/amanda/mytar.debug
242 # if [ "$3" = "/dev/null" ]
243 # then echo "Estimate only" >> $LOG
244 # else echo "Real backup" >> $LOG
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
251 if [ "$1" = "--create" -a "$3" = "-" -a "$5" = "/my/dir" ]
253 # echo "/my/dir: want to execute some progs first" >>$LOG
254 /usr/local/bin/shutdb thedb >&2
255 /usr/local/bin/gtar "$@"
257 # echo "Finished the real backup; some postprocessing" >>$LOG
258 /usr/local/bin/startdb thedb >&2
261 /usr/local/bin/gtar "$@"
264 Here is an example script in perl:
269 use Getopt::Long qw(:config pass_through);
271 my @saveopts = @ARGV;
273 'create' => \$create,
274 'directory=s' => \$dir,
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';
285 unshift(@ARGV, "/usr/local/bin/gtar");
291 system '/usr/local/bin/dbstart thedb >/tmp/amanda/dbstart.debug 2>&1';
296 -------------------------------------------------------------------------------
299 Chapter 14. AFS HOWTO Home Chapter 16. How to do Amanda-server-side gpg-