Update README

[bacula/bacula] / regress / README

             Bacula Regression
               Kern Sibbald

This is Bacula's regression script directory.

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
Warning!!!! Make sure not to run it on the same system 
with your production Catalog because the tables will all
be cleared. You can run it on the your production system
if you use a different database. E.g. if your production
system uses MySQL, you can use SQLite here.
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!


To set it up, create your personal configuration file, by
copying prototype.conf to config or simply editing prototype.conf
directly then copying it to the file config.

You must end up with a file named config in the main regress 
directory that has all the specifications that correspond to
your system.

If you are using SQLite, make sure that depkgs is pre-built if it
isn't already: (cd your-depkgs; make sqlite).

Note, if you use any database other than SQLite, be sure it is not              
your production database because Bacula will delete all the tables
and recreate them.  With SQLite, a new different database is created,
so it will not affect your production system.

Using the .conf file, you can now select between any Catalog type:
SQLite, SQLite3, MySQL, or PostgreSQL.  Be aware, however, if you
use an installed database on a production server, running these
tests will delete all the tables !!!!!!!!!!!!!!!!!!  I run my
tests on a non-production machine, and in addition, I normally use
SQLite as the database, while my production uses MySQL.

Then do:

   make setup

You run the above one time.  This will build a Makefile from
Makefile.in and your xxx.conf file, copy the Bacula source,
configure, build it, and configure all the Bacula scripts
and conf files.  If you change your source, you will need to
redo this command.

Then you can run any of the tests in the tests subdirectory.
Each test whose name ends in -root requires you to be root for
a resonable run.  Each test is totally independent of any other
test. Aside from the required "make setup", each test is totally
self-initalizing and should clean up after itself.

All the tests expect you to execute them from the main regress 
directory!               

Running the disk based tests:

You can run all the disk based tests by doing:

  ./do_file

The disk based tests are totally separate from any production
system, provided you have configured the database appropriately     
as noted above.

Running all the "standard" tests:

You can run all the disk and most of the tape tests by doing:

  ./do_all

======== Important !!! ============
When running the tape tests, Bacula will write on any tape that
is in the tape drive that you have configured.  If it is a production
Bacula tape, it will be destroyed.  If you have configured an Autochanger,
Bacula will write on the tapes in slots 1 and 2 thus destroying any
information on those tapes, even if they are Bacula production tapes.
=================================== 

Each of the above calls one or more scripts. By looking at the
scripts available in this directory, you can see that there are a number
of options for running tests.

You can run them individually as:

   tests/two-jobs-test

or all non-root tests (my normal testing under my account)

  ./all-non-root-tests

or all tests (I only run these before a production release):

   su
   ./all-tests


after running the root tests, while still root, it is a good idea
to do:

   make reset

this cleans up any files that may be created with root permissions.

Tape test naming convention:

I've renamed the tape tests to include an indication of how
many tapes and drives each test needs.  The indication consists
of 4 or 5 characters just before the final -tape.  For example,
there is a tape test named:

  vol-duration-2t1da-tape

this means that it uses 2 tape (2t) one drive (1d) and the
autochanger (a).  Another test might be named

  fixed-block-size-1t1d-tape

which means it uses one tape on one drive and no autochanger.

Adding tests:

If you want to add more tests, do so by putting the shell script 
in the tests subdirectory. Be careful when adding (or better not)
new clients, pools, and such to the test-bacula-dir.conf.in file
as it may invalidate a good number of tests, which respond to
questions by answering with a number (i.e. the order of the selection
list is known). It might be better to add your own testb-bacula...
configuration file.  

To avoid re-doing a make setup if you have made a change to the
conf files, and you do not need a new copy of the source, you can simply do:

   make sed

Debugging failed tests:

Prior versions required editing the tests/xxxx and changing a debug flag.
However, that has been replaced by two environment variables:

   REGRESS_DEBUG
   REGRESS_WAIT

If you define REGRESS_DEBUG, e.g.

   REGRESS_DEBUG=1
   export REGRESS_DEBUG

then run a test, it will display the job and debug output.

If you define REGRESS_WAIT, the script will stop and request:

Start Bacula under debugger and enter anything when ready ...

At this point, you can start any of the daemons under the debugger,
then answer the message by entering any character.  The script will         
then continue. For any daemon or daemons that you have manually started,
you will see an error message when the script attempts to run a second
copy, but those messages can be ignored.  This makes it reasonably easy
to run any component or components under the debugger if necessary.

Explicit example:

In shell window 1.

cd regress
export REGRESS_DEBUG=1
export REGRESS_WAIT=1
tests/name-of-script-test
(wait until it tells you to start the debugger)

In shell window 2

cd regress/bin
gdb bacula-xx    (where xx is the component you want to debug).
(possibly set a break point -- normally not)
run -s -f
(wait for the output to stop)

In shell window 1
(enter any character or simply a return)
(ignore the error message it prints complaining that the daemon
you are debugging is already running, which is in fact the case).


That is all there is to it.  The debugger window will get some
output and will stop waiting for input if anything goes wrong
like a seg fault.  At that point, you can enter commands.

The procedure avoids modifying the test scripts and trying to
find pids and the such.  If you want less debug output when
debugging, don't set REGRESS_DEBUG=1.

===

Also, if you run from time to time on a computer that is not connected
to the network, please be sure that "hostname" is set to "localhost",
otherwise, your tests may fail because the hostname used by Bacula's
./configure cannot be properly resolved.

Anyway, you can debug where it is happening in the source code using the 
following example.  For example, here I get the following backtrace:

======= Backtrace: =========
/lib/libc.so.6[0xb7b9d6e1]
/lib/libc.so.6(cfree+0x89)[0xb7b9ed79]
/home/kern/bacula/regress/bin/bacula-fd[0x8082ae5]
/home/kern/bacula/regress/bin/bacula-fd[0x8082d58]
/home/kern/bacula/regress/bin/bacula-fd[0x80838ac]
/home/kern/bacula/regress/bin/bacula-fd[0x807aa3f]
/home/kern/bacula/regress/bin/bacula-fd[0x807ac29]
/home/kern/bacula/regress/bin/bacula-fd[0x804d188]
/lib/libc.so.6(__libc_start_main+0xdc)[0xb7b4ef9c]
/home/kern/bacula/regress/bin/bacula-fd[0x804cd21]

Now to convert this into something more meaningful, kill off any hung Bacula 
processes.  Note the one that was running -- above you see that it was 
bacula-fd, then bring the same binary up in the debugger.  Then start at the 
first bacula-fd line, and feed the hex number to gdb as follows:

info symbol 0x8082ae5
free_addresses(dlist*) + 53 in section .text

info symbol 0x8082d58
add_address(dlist**, IPADDR::i_type, unsigned short, int, char const*, char 
const*, char**) + 568 in section .text