Chapter 23. Getting Help and Online Resources

Contents:

In this chapter, we propose a way to solve your mod_perl-related
problems and provide starting points for information resources
related to mod_perl.

If you have any problem with mod_perl itself, be it a build problem
or a runtime problem, you should follow the steps below. But before
you follow them, think carefully about whether the problem you are
experiencing is mod_perl-related. It's quite
possible that the problem is in the Perl code, SQL code, Apache
itself, or something else entirely. In such cases, you should refer
to other resources presented later in this chapter. Remember that
although mod_perl resources might help you with many related things,
they will never be as detailed as resources devoted to the topic at
hand.

If you still think that the problem has something to do with
mod_perl, these are the steps to follow:

Try to tackle the problem
by yourself for a while. Check that you
have the right permissions, that there is enough disk space, etc. Do
sanity checks: try to remove the mod_perl source tree, unpack it
again, and build from fresh.

When trying to figure out what the problem is, always run under
single-server mode (httpd -X) and always check
the error_log file.

If you still have problems, proceed to step 2.

Reread the
documentation (or if you
didn't read it yet, do it now). Try to follow the
build and usage steps as explained there. This book,
Writing Apache Modules with Perl and C
(O'Reilly), and the documentation distributed with
the mod_perl sources provide in-depth details on this topic. Also,
make sure to read Chapter 22 thoroughly. If you are
still in trouble, proceed to step 3.

Go to the
mod_perl list archives (at
http://perl.apache.org/maillist/)
and see whether someone has already reported the same problem. If
someone did, chances are that a cure to the problem has been posted
to the list, be it a source patch or a workaround. If after doing an
exhaustive search you haven't come up with any
solution, proceed to step 4.

Notice that sometimes doing this step before step 2 can be a good
idea as well—you may happen to have encountered a well-known
bug, and if that's the case doing a quick lookup in
the mailing-list archives will save you time and frustration.

This step is the last resort. Contact the mod_perl mailing
list. You should never abuse this step, and use it only when you have
already been through the previous three steps. If you ask FAQ
questions unnecessarily, chances are that people will not reply to
you. And if you ask more FAQ questions, you might get onto
people's blacklists and they will not answer your
future questions even if they are relevant. Remember that all the
answers that you get are coming from volunteers who, instead of
having fun outdoors, try to have fun answering challenging questions.
FAQ questions aren't challenging, and few people
have fun answering them. See more details about mod_perl list
etiquette in the next section.

It's not enough to just contact the list and ask for
help. You have to provide as many details as possible. The next
section covers the details you have to provide.

However, don't be afraid. The mod_perl mailing list
is filled with only nice people who can provide much help and
guidance, so if you can't figure something out after
having followed the above steps, your question is welcome.

You cannot post to the list without first subscribing to it. To
subscribe, send an email to
[email protected]. After you receive a
confirmation email, you can start posting to the list. Send your
emails to
[email protected].

There are other related mailing lists you might want to be on too.
See the list of these and subscription instructions in Section 23.3.

23.1. How to Report Problems

When reporting a problem to the
mod_perl mailing list, always send these details:

Anything in the error_log file that looks
suspicious and possibly related to the problem

Output of perl -V

Version of mod_perl

Version of Apache

Options given to mod_perl's
Makefile.PL file

Server configuration details

If make test fails, the output of make
test TEST_VERBOSE=1

Also check whether:

make test passes 100%

The script works under mod_cgi, if applicable

You should try to isolate the problem and send the smallest possible
code snippet that reproduces the problem.

23.1.1. Getting the Backtrace from Core Dumps

If you get a core dump (segmentation fault),
send a backtrace if possible. Before you try to
produce it, rebuild mod_perl with:

panic% perl Makefile.PL PERL_DEBUG=1

which will:

Add -g to EXTRA_CFLAGS

Turn on PERL_TRACE

Set PERL_DESTRUCT_LEVEL=2 (additional checks
during Perl cleanup)

Link against libperld, if it exists

You can read a full explanation in Chapter 21, but
here is a summary of how to get a backtrace:

In English: cd to the mod_perl source directory
and start gdb with a path to the
httpd binary, which is located in the Apache
source tree. (Of course, replace x with real
version numbers.) Next, start the httpd process
from within gdb and issue a request that causes
a core dump. When the code has died with the
SIGSEGVsignal, run bt to get
the backtrace.

Alternatively, you can also attach to an already running process like
so:

panic% gdb httpd <process id number>

If the dump is happening in libperl, you have to
rebuild Perl with -DDEBUGGING enabled during the
./Configure stage. A quick way to this is to go
to your Perl source tree and run these commands:

After loading the special macros file
(.gdbinit), you can use the
curinfogdb macro to figure
out the file and line number in which the code stuck. Chapter 21 talks in more detail about tracing techniques.