ModSecurity

Installation

Before you begin with installation you will need to choose your preferred installation method. First you need to choose whether to install the latest version of ModSecurity directly from CVS (best features, but possibly unstable) or use the latest stable release (recommended). If you choose a stable release, it might be possible to install ModSecurity from binary. It is always possible to compile it from source code.

The following few pages will give you more information on benefits of choosing one method over another.

CVS Access

If you want to access the latest version of the module you need to get it from the CVS repository. The list of changes made since the last stable release is normally available on the web site (and in the file CHANGES). The CVS repository for ModSecurity is hosted by SourceForge (http://www.sf.net). You can access it directly or view if through web using this address: http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/mod-security/ 

To download the source code to your computer you need to execute the following two commands:

$ cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/mod-security login
$ cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/mod-security \
> co mod_security

The first line will log you in as an anonymous user, and the second will download all files available in the repository.

Nightly Snapshot Download

If you don't like CVS but you still want the latest version you can download the latest nightly tarball from the following address:

http://www.modsecurity.org/download/snapshot/mod_security-snapshot.tar.gz

New features are added to mod_security one by one, with regression tests being run after each change. This should ensure that the version available from CVS is always usable.

Stable Release Download

To download the stable release go to http://www.modsecurity.org/download/. Binary distributions are sometimes available. If they are, they are listed on the download page. If not download the source code distribution.

Installing from source

When installing from source you have two choices: to install the module into the web server itself, or to compile mod_security.c into a dynamic shared object (DSO).

DSO

Installing as DSO is easier, and the procedure is the same for both Apache branches. First unpack the distribution somewhere (anywhere will do), and compile the module with:

# <apache-home>/bin/apxs -cia mod_security.c

After this you only need to stop and then start Apache (if you try to restart it you may get a segfault):

# <apache-home>/bin/apachectl stop
# <apache-home>/bin/apachectl start

Note

I've had reports from people using platforms that do not have the apxs utility installed. In some Unix distribution this tool is distributed in a separate package. The problem arises when that package is not installed b default. To resolve this problem read the documentation from your vendor to discover how you can add your own custom Apache modules. (On some RedHat platforms you need to install the package http-devel to get access to the apxs utility).

Static installation with Apache 1.x

When a module is compiled statically, it gets embedded into the body of the web server. This method results in a slightly faster executable but the compilation method (and subsequent maintenance) is a bit more complicated.

$ cd <apache1-source>
$ cp <modsecurity-source>/apache1/mod_security.c ./src/modules/extra
$ ./configure \
> --activate-module=src/modules/extra/mod_security \
> -–enable-module=security

Compile, install, and start the web server as you normally do.

Static installation with Apache 2.x

To compile statically with Apache 2.x you only need to copy the module source code into the Apache source code tree and reconfigure Apache:

$ cd <apache2-source>
$ cp <modsecurity-source>/apache2/mod_security.c ./modules/proxy
$ ./configure \
> -enable-security \
> --with-module=proxy:mod_security.c

Integrating into the Apache 2.x build

You can also choose to integrate mod_security into the Apache 2.x build.

$ cd <modsecurity-source>/apache2
$ mkdir -r <apache2-source>/modules/security
$ cp mod_security.c Makefile.in config.m4 <apache2-source>/modules/security
$ cd <apache2-source>
$ ./buildconf

From this point on mod_security will appear to Apache as any other built-in module. It will not be compiled-in by default. To enable it do the following:

$ ./configure --enable-security

Compiling the Apache 1.x version against PCRE

By default ModSecurity relies on the regular expression library built into Apache for pattern matching. This works well with Apache 2.x but not so much with Apache 1.x. The Apache 1.x regular expression engine is several times slower. Since 1.9.2 it is possible to compile ModSecurity for Apache 1.x against an external regular expression library (PCRE, http://www.pcre.org, the same library used in Apache 2.x) and achieve significant performance increase. This is achieved with the USE_PCRE compile-time flag.

If you have PCRE already installed on your system it may be sufficient to compile ModSecurity like this:

# <apache1-home>/bin/apxs -DUSE_PCRE -cia mod_security.c

If you don't already have PCRE then you will have to download, configure, and compile it first. It is not necessary to install it.

$ cd <pcre-source>
$ ./configure && make
# cp ./.libs/libpcre.so <apache1-home>/libexec

Then compile and install ModSecurity:

# <apache1-home>/bin/apxs -I <pcre-source> -DUSE_PCRE -cia mod_security.c

Finally, tell Apache to load the PCRE library before ModSecurity. Add the following line before the line that loads ModSecurity (LoadModule ...):

LoadFile libexec/libpcre.so

Now you can stop then start Apache and observe the performance improvements.

Installing from binary

In some circumstances, you will want to install the module as a binary. At the moment I only make Windows binaries available for download. When installing from binary you are likely to have two DSO libraries in the distribution, one for each major Apache branch. Choose the file appropriate for the version you are using. Then proceed as described below:

Apache 1.x

Copy mod_security.so (on Unix) or mod_security.dll (on Windows) to libexec/ (this folder is relative to the Apache installation, not the source tree). Then add the following line to httpd.conf:

LoadModule security_module    libexec/mod_security.so

Depending on your existing configuration (you may have chosen to configure module loading order explicitly) it may be necessary to activate the module using the AddModule directive:

AddModule mod_security.c

In most cases it is not important where you add the line. It is recommended (and, in fact, mandatory if you intend to use the internal chroot feature) to make mod_security execute last in the module chain. Read the section “Required module ordering for chroot support (Apache 1.x)” for more information.

Apache 2.x

Copy mod_security.so (on Unix) or mod_security.dll (on Windows) to modules/ (this folder is relative to the Apache installation, not the source tree). Then add the following line to httpd.conf:

LoadModule security_module    modules/mod_security.so