]> git.sur5r.net Git - bacula/bacula/blob - regress/README
Update win32 readme
[bacula/bacula] / regress / README
1              Bacula Regression
2                Kern Sibbald
3
4 This is Bacula's regression script directory.
5
6 !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
7 Warning!!!! Make sure not to run it on the same system 
8 with your production Catalog because the tables will all
9 be cleared. You can run it on the your production system
10 if you use a different database. E.g. if your production
11 system uses MySQL, you can use SQLite here.
12 !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
13
14
15 To set it up, create your personal configuration file, by
16 copying prototype.conf to config or simply editing prototype.conf
17 directly then copying it to the file config.
18
19 You must end up with a file named config in the main regress 
20 directory that has all the specifications that correspond to
21 your system.
22
23 If you are using SQLite, make sure that depkgs is pre-built if it
24 isn't already: (cd your-depkgs; make sqlite).
25
26 Note, if you use any database other than SQLite, be sure it is not              
27 your production database because Bacula will delete all the tables
28 and recreate them.  With SQLite, a new different database is created,
29 so it will not affect your production system.
30
31 Using the .conf file, you can now select between any Catalog type:
32 SQLite, SQLite3, MySQL, or PostgreSQL.  Be aware, however, if you
33 use an installed database on a production server, running these
34 tests will delete all the tables !!!!!!!!!!!!!!!!!!  I run my
35 tests on a non-production machine, and in addition, I normally use
36 SQLite as the database, while my production uses MySQL.
37
38 Then do:
39
40    make setup
41
42 You run the above one time.  This will build a Makefile from
43 Makefile.in and your xxx.conf file, copy the Bacula source,
44 configure, build it, and configure all the Bacula scripts
45 and conf files.  If you change your source, you will need to
46 redo this command.
47
48 Then you can run any of the tests in the tests subdirectory.
49 Each test whose name ends in -root requires you to be root for
50 a resonable run.  Each test is totally independent of any other
51 test. Aside from the required "make setup", each test is totally
52 self-initalizing and should clean up after itself.
53
54 All the tests expect you to execute them from the main regress 
55 directory!               
56
57 Running the disk based tests:
58
59 You can run all the disk based tests by doing:
60
61   ./do_file
62
63 The disk based tests are totally separate from any production
64 system, provided you have configured the database appropriately     
65 as noted above.
66
67 Running all the "standard" tests:
68
69 You can run all the disk and most of the tape tests by doing:
70
71   ./do_all
72
73 ======== Important !!! ============
74 When running the tape tests, Bacula will write on any tape that
75 is in the tape drive that you have configured.  If it is a production
76 Bacula tape, it will be destroyed.  If you have configured an Autochanger,
77 Bacula will write on the tapes in slots 1 and 2 thus destroying any
78 information on those tapes, even if they are Bacula production tapes.
79 =================================== 
80
81 Each of the above calls one or more scripts. By looking at the
82 scripts available in this directory, you can see that there are a number
83 of options for running tests.
84
85 You can run them individually as:
86
87    tests/two-jobs-test
88
89 or all non-root tests (my normal testing under my account)
90
91   ./all-non-root-tests
92
93 or all tests (I only run these before a production release):
94
95    su
96    ./all-tests
97
98
99 after running the root tests, while still root, it is a good idea
100 to do:
101
102    make reset
103
104 this cleans up any files that may be created with root permissions.
105
106 Tape test naming convention:
107
108 I've renamed the tape tests to include an indication of how
109 many tapes and drives each test needs.  The indication consists
110 of 4 or 5 characters just before the final -tape.  For example,
111 there is a tape test named:
112
113   vol-duration-2t1da-tape
114
115 this means that it uses 2 tape (2t) one drive (1d) and the
116 autochanger (a).  Another test might be named
117
118   fixed-block-size-1t1d-tape
119
120 which means it uses one tape on one drive and no autochanger.
121
122 Adding tests:
123
124 If you want to add more tests, do so by putting the shell script 
125 in the tests subdirectory. Be careful when adding (or better not)
126 new clients, pools, and such to the test-bacula-dir.conf.in file
127 as it may invalidate a good number of tests, which respond to
128 questions by answering with a number (i.e. the order of the selection
129 list is known). It might be better to add your own testb-bacula...
130 configuration file.  
131
132 To avoid re-doing a make setup if you have made a change to the
133 conf files, and you do not need a new copy of the source, you can simply do:
134
135    make sed
136
137 Debugging failed tests:
138
139 Prior versions required editing the tests/xxxx and changing a debug flag.
140 However, that has been replaced by two environment variables:
141
142    REGRESS_DEBUG
143    REGRESS_WAIT
144
145 If you define REGRESS_DEBUG, e.g.
146
147    REGRESS_DEBUG=1
148    export REGRESS_DEBUG
149
150 then run a test, it will display the job and debug output.
151
152 If you define REGRESS_WAIT, the script will stop and request:
153
154 Start Bacula under debugger and enter anything when ready ...
155
156 At this point, you can start any of the daemons under the debugger,
157 then answer the message by entering any character.  The script will         
158 then continue. For any daemon or daemons that you have manually started,
159 you will see an error message when the script attempts to run a second
160 copy, but those messages can be ignored.  This makes it reasonably easy
161 to run any component or components under the debugger if necessary.
162
163 Explicit example:
164
165 In shell window 1.
166
167 cd regress
168 export REGRESS_DEBUG=1
169 export REGRESS_WAIT=1
170 tests/name-of-script-test
171 (wait until it tells you to start the debugger)
172
173 In shell window 2
174
175 cd regress/bin
176 gdb bacula-xx    (where xx is the component you want to debug).
177 (possibly set a break point -- normally not)
178 run -s -f
179 (wait for the output to stop)
180
181 In shell window 1
182 (enter any character or simply a return)
183 (ignore the error message it prints complaining that the daemon
184 you are debugging is already running, which is in fact the case).
185
186
187 That is all there is to it.  The debugger window will get some
188 output and will stop waiting for input if anything goes wrong
189 like a seg fault.  At that point, you can enter commands.
190
191 The procedure avoids modifying the test scripts and trying to
192 find pids and the such.  If you want less debug output when
193 debugging, don't set REGRESS_DEBUG=1.
194
195 ===
196
197 Also, if you run from time to time on a computer that is not connected
198 to the network, please be sure that "hostname" is set to "localhost",
199 otherwise, your tests may fail because the hostname used by Bacula's
200 ./configure cannot be properly resolved.
201
202 Anyway, you can debug where it is happening in the source code using the 
203 following example.  For example, here I get the following backtrace:
204
205 ======= Backtrace: =========
206 /lib/libc.so.6[0xb7b9d6e1]
207 /lib/libc.so.6(cfree+0x89)[0xb7b9ed79]
208 /home/kern/bacula/regress/bin/bacula-fd[0x8082ae5]
209 /home/kern/bacula/regress/bin/bacula-fd[0x8082d58]
210 /home/kern/bacula/regress/bin/bacula-fd[0x80838ac]
211 /home/kern/bacula/regress/bin/bacula-fd[0x807aa3f]
212 /home/kern/bacula/regress/bin/bacula-fd[0x807ac29]
213 /home/kern/bacula/regress/bin/bacula-fd[0x804d188]
214 /lib/libc.so.6(__libc_start_main+0xdc)[0xb7b4ef9c]
215 /home/kern/bacula/regress/bin/bacula-fd[0x804cd21]
216
217 Now to convert this into something more meaningful, kill off any hung Bacula 
218 processes.  Note the one that was running -- above you see that it was 
219 bacula-fd, then bring the same binary up in the debugger.  Then start at the 
220 first bacula-fd line, and feed the hex number to gdb as follows:
221
222 info symbol 0x8082ae5
223 free_addresses(dlist*) + 53 in section .text
224
225 info symbol 0x8082d58
226 add_address(dlist**, IPADDR::i_type, unsigned short, int, char const*, char 
227 const*, char**) + 568 in section .text