Quick Start

Special httpd requirements

There are no special requirements on Windows.

On Unix, the --enable-exception-hook configure argument is required on the httpd build. Otherwise, mod_whatkilledus can't compile or function.

Checking --enable-exception-hook...

$ grep AP_ENABLE_EXCEPTION_HOOK /path/to/httpd/include/ap_config_auto.h
#define AP_ENABLE_EXCEPTION_HOOK 1

If it isn't configured correctly, you'll see something like /* #undef AP_ENABLE_EXCEPTION_HOOK */ as the grep output instead of what is displayed above, and you'll need to reconfigure httpd with the --enable-exception-hook configure argument and compile and install again.

Download it

Unzip it in a convenient place.

Using the provided Windows binaries

You'll find directories for Apache httpd 2.2.x and Apache httpd 2.4.x under the dist/Windows/i686 (32-bit) and dist/Windows/x86_64 (64-bit) directories.

Copy mod_whatkilledus.so, mod_whatkilledus.pdb, mod_backtrace.so, and mod_backtrace.pdb to Apache httpd's modules directory.

Microsoft Run-time Library Dependency

The binary builds included in version 2.01 of this project require Microsoft Visual C++ 2010 Redistributable Package to be installed on the system.

Building it

Unix

Something like this should work:

make clean all install APXS=/path/to/apxs [LIBUNWIND=yes]

(apxs is a tool in the httpd bin directory.)

Add LIBUNWIND=yes if libunwind is installed in the normal place for your Linux or FreeBSD or OS X system and this isn't a 32-bit build of httpd on OS X.

If you try to build mod_whatkilledus but httpd wasn't configured with --enable-exception-hook, you will encounter one of these failures:

Windows

From a Visual Studio command prompt:

nmake -f makefile.win32 HTTPD=c:\my\apache22 clean all install

Use a Visual Studio 32-bit command prompt if compiling for use with a 32-bit build of Apache httpd, or a Visual Studio 64-bit command prompt otherwise.

If you have trouble building it, I suggest using the provided binaries.

A simple configuration

LoadModule backtrace_module modules/mod_backtrace.so
LoadModule whatkilledus_module modules/mod_whatkilledus.so

WKUObscureInRequest hdr:Authorization hdr:Cookie hdr:Proxy-Authorization user password query unparsed-line

# Omit the following directive on Windows:
EnableExceptionHook On

If EnableExceptionHook On results in a syntax error on a Unix platform, you must rebuild the server with the --enable-exception-hook configure argument. Sorry!

Please refer to the full documentation before you put this in production.

Windows .pdb files

.pdb files are needed for web server and other binaries in order to show the proper symbols in backtraces. If a problem is being actively debugged with mod_backtrace, download the symbol files for your level of Apache httpd and follow the instructions for unpacking them.

These symbol files need to come from the provider of your Apache httpd build. Don't download these from apache.org unless you downloaded an ASF build of Apache httpd.

Testing what happens after a crash

This is just for a quick test in a non-production environment. Don't forget to remove this configuration as well as mod_crash from your web server install.

Install mod_crash.so, either by copying the provided Windows binary to Apache httpd's modules directory, or by using the install-mod-crash target of the makefile.

Add this extra configuration to your server:

LoadModule crash_module modules/mod_crash.so
<Location /backtrace>
SetHandler backtrace-handler
</Location>

<Location /crash>
SetHandler crash-handler
</Location>
After restarting the server, try to load the URIs /backtrace/ and /crash/. The former should result in backtraces of various formats in your browser window. The latter should result in a very long and uncomfortable pause before the browser displays an error message, and a report like the following should appear in the file whatkilledus_log (or .log on Windows) in Apache httpd's logs directory: 
**** Crash at 2012-09-06 14:48:23
Process id:  23368
Fatal signal: 11

/home/trawick/inst/24-64/modules/mod_backtrace.so:0x7fecbd7a23b1
/home/trawick/inst/24-64/modules/mod_whatkilledus.so:0x7fecbd39a9f7
/home/trawick/inst/24-64/modules/mod_whatkilledus.so:0x7fecbd39ac1a
/home/trawick/inst/24-64/bin/httpd:ap_run_fatal_exception+0x5b 0x430562
/home/trawick/inst/24-64/bin/httpd:0x4616a5
/home/trawick/inst/24-64/bin/httpd:0x4616df
/lib/x86_64-linux-gnu/libpthread.so.0:0x7fecc4724060
/home/trawick/inst/24-64/modules/mod_crash.so:0x7fecbd59e986
/home/trawick/inst/24-64/modules/mod_crash.so:0x7fecbd59ead8
/home/trawick/inst/24-64/bin/httpd:ap_run_handler+0x5b 0x45008e
/home/trawick/inst/24-64/bin/httpd:ap_invoke_handler+0x173 0x450966
/home/trawick/inst/24-64/bin/httpd:ap_process_async_request+0x264 0x46c46d
/home/trawick/inst/24-64/bin/httpd:0x468dc4
/home/trawick/inst/24-64/bin/httpd:0x468fb3
/home/trawick/inst/24-64/bin/httpd:ap_run_process_connection+0x5b 0x45d68b
/home/trawick/inst/24-64/modules/mod_mpm_event.so:0x7fecc3b00450
/home/trawick/inst/24-64/modules/mod_mpm_event.so:0x7fecc3b0287c
/home/trawick/inst/apr14-64/lib/libapr-1.so.0:0x7fecc495f4ab
/lib/x86_64-linux-gnu/libpthread.so.0:0x7fecc471befc
/lib/x86_64-linux-gnu/libc.so.6:clone+0x6d 0x7fecc445659d

Request line (parsed):
GET :10080 /crash/
Request headers:
Host:127.0.0.1%3a10080
User-Agent:ApacheBench/2.3
Accept:*/*

Client connection:
127.0.0.1:44883->127.0.0.1:10080  (user agent at 127.0.0.1:44883)

Please remove mod_crash.so and the extra configuration for /backtrace and /crash right this minute so that you don't forget about them. If you built it yourself on Windows, mod_crash.pdb also needs to be removed.

The validity of function names in the backtrace depends on a lot of stuff. Hopefully the mod_backtrace documentation will eventually cover potential issues in gory detail.