Debugging Midgard

1. 1. Preparations
2. 2. Shut down normal Apache processes
3. 3. Start the debugger
4. 4. Start the Apache process
5. 5. Recreate the problem
6. 6. Get a stack trace
7. 7. Stop the debugger
8. 8. Start the normal Apache

New features in Midgard might still contain some bugs and misfeatures. If and when you stumble on a bug in Midgard you can help us fix it by trying to find the source of the problem. Here's some instructions on how to do that.

Some people have run into some bugs in Midgard that we are unable recreate and thus cannot debug and fix very easily. The bugs show themselves mostly as segfault messages in the Apache error log and "Document contains no data" messages or partial pages in a browser. The reason for such errors is often a bug in the midgard-php module and can probably be fixed quite easily. However the most difficult part is to track down the bug in the sources. If you want you can help us find the bugs.

To get information about what is going on inside a running program one needs to use a debugger. To locate bugs in the Midgard system we run the Apache executable with the GNU debugger gdb. These are simple instructions for the process:

1. Preparations

Make sure that you have a clean installation of Apache, MySQL and Midgard. Check that there are no old header files or other trails of old installations on your system. If there are, then remove them and install Midgard again. The problem you experienced might have been caused by bad interactions between the old and new installations.

Check also that you have the GNU debugger installed. It is easily available for all Linux distributions and other UNIXes. If you want you may also use some other debugger you are more familiar with, but then you'll have to adapt these instructions a bit.

2. Shut down normal Apache processes

You need to shut down the normal Apache server in order to release the network ports for the debugging process. You can do this by running:

# apachectl stop

3. Start the debugger

Start the debugger with the httpd executable:

# gdb /path/to/httpd

You may use either installed executable (normally in PREFIX/bin/httpd) or the one left in the Apache source directory (apache_1.3.6/src/httpd). At least on some systems the Apache installation process strips debugging symbols from the installed executable so the one in the source directory is generally a better choise for debugging. The two executables should have no differences in functionality.

After gdb has initialized itself and read the debugging symbols from the httpd executable, it prints out the prompt "(gdb)". You may at any point stop the debugger with the command quit. For more information use the command help.

4. Start the Apache process

Start the httpd executable as a single thread server from within the debugger. You can do this with the command:

(gdb) run -X

If the program exits after just a few seconds then it probably cannot access the network ports it needs and fails. In this case you probably still have a normal Apache running.

5. Recreate the problem

Use your browser to access the Midgard page that causes the problem. The browser should stop waiting for more information from the server and the debugger should break with a message like this:

Program received signal SIGSEGV, Segmentation fault.
php3_mgd_is_in_topic_tree (ht=0x80cb780, return_value=0x40194ad0, list=0x40195ef8, plist=0x40195ecc) at functions/midgard.c:1073
1073 for (i = 0; idsi; i++)

(This was a well known bug that was fixed by Midgard 1.1.2. It should not affect proper Midgard installations.)

6. Get a stack trace

By default the debugger lists the function and line that caused the segfault. To get a more complete view into the program internals use the backtrace command to get a stack backtrace of the program.

(gdb) backtrace

You can then mail the returned information to the developer mailing list for closer inspection.

7. Stop the debugger

After you've got the information needed you may stop the debugger with the command quit.

8. Start the normal Apache

Finally you'll be able to restart your normal Apache server by running:

# apachectl start

Happy debugging!