Writing Apache Modules with Perl and C By:   Lincoln Stein and Doug MacEachern Published:   O'Reilly & Associates, Inc.  - March 1999 Copyright © 1999 by O'Reilly & Associates, Inc.

Chapter 2 - A First Module
Troubleshooting Modules

In this section...

Introduction C-Level Debugging Perl-Level Debugging

Introduction

Not every module will work the way you think it will the first time you try it. Because the modules written with the Apache API are by definition embedded in the server, debugging them is not as straightforward as debugging a standalone CGI script. In this section, we cover some general module debugging techniques. You'll find more tips later when we discuss specific issues.

C-Level Debugging

If you are using the C API, you can use standard debuggers to step through your module, examine and change data structures, set watch points, and so forth. Be sure to use a version of httpd that has been compiled with debugging symbols and to turn compiler optimizations off. On Unix systems, you can do this by setting the CFLAGS environment variable before running the configure script:

% CFLAGS=-g ./configure ...

Launch your favorite debugger, such as gdb, and run httpd within it. Be sure to launch httpd with the -X flag. Ordinarily, Unix versions of httpd will prefork many independent processes. This forking will confuse the debugger and will probably confuse you too. -X prevents Apache from preforking and keeps the server in the foreground as well. You will also probably want to specify an alternate configuration file with the -f switch so that you can use a high numbered port instead of the default port 80. Be sure to specify different ErrorLog, TransferLog, PidFile, and ScoreBoardFile directives in the alternate configuration file to avoid conflicts with the live server.

% gdb httpd
(gdb) run -X -f ~www/conf/httpd.conf

Fetch a few pages from the server to make sure that it is running correctly under the debugger. If there is a problem that triggers a core dump, the (gdb) prompt will return and tell you which function caused the crash. Now that you have an idea of where the problem is coming from, a breakpoint can be set to step through and see exactly what is wrong. If we were debugging mod_hello within the gdb debugger, the command to use would be this:

% gdb httpd
(gdb) b hello_handler
Breakpoint 1 at 0x809cefb: file mod_hello.c, line 82.
(gdb) run -X -f ~www/conf/httpd.conf

Now use a browser to fetch a page that will trigger the execution of the breakpointed handler. Control will return to the debugger, allowing you to step through code looking for the problem.

It is also possible to debug httpd without running it in -X mode. Simply start the server as you normally would, then use the ps command to see the process IDs of the servers. Select a PID and start gdb with the process ID as an additional argument. The debugger will attach to the process and list all the files it is reading symbols from. It will eventually stop, providing you with a prompt and a chance to set your breakpoints. Be sure to type in the c continue command so the child will be able to serve requests again. This approach makes it easy to set breakpoints in dynamically loaded modules, which are not pulled in until the parent server has started. There is a catch though: you might have to request the page you wish to debug a number of times before Apache hands off a request to the process you are attached to. To cut down on the number of servers you must cycle through, simply tune the server's configuration to start only a small number of servers.⁹

% gdb httpd process id number
...
Reading symbols from /usr/local/apache/lib/mod_hello.so...done.
0x400d7a81 in flock ()
(gdb) b hello_handler
Breakpoint 1 at 0x40176c77: file mod_hello.c, line 82.
(gdb) c
Continuing.