2 Installation

To download ModSecurity, go to its web site or the SourceForge project page. You will need both the main distribution and the cryptographic signature:

$ wget http://www.modsecurity.org/download/modsecurity-apache_2.5.10-dev2.tar.gz
$ wget http://www.modsecurity.org/download/modsecurity-apache_2.5.10-dev2.tar.gz.asc

Verify the signature before doing anything else. That will ensure that the package you’ve just downloaded does not contain a trojan horse planted by a third party and that it hasn’t been corrupted during transport.

$ gpg --verify modsecurity-apache_2.5.10-dev2.tar.gz.asc
gpg: Signature made Wed 12 Aug 2009 23:27:06 BST using DSA key ID E77B534D
gpg: Can't check signature: public key not found

Your first attempt may not provide the expected results, but that can be solved easily by importing the referenced key from a key server:

$ gpg --recv-keys E77B534D
gpg: requesting key E77B534D from hkp server keys.gnupg.net
gpg: /home/guest/.gnupg/trustdb.gpg: trustdb created
gpg: key E77B534D: public key "Brian Rectanus (work) <brian.rectanus@breach.com>" ↩
imported
gpg: no ultimately trusted keys found
gpg: Total number processed: 1
gpg:               imported: 1

Now you can try again:

$ gpg --verify modsecurity-apache_2.5.10-dev2.tar.gz.asc
gpg: Signature made Wed 12 Aug 2009 23:27:06 BST using DSA key ID E77B534D
gpg: Good signature from "Brian Rectanus (work) <brian.rectanus@breach.com>"
gpg:                 aka "Brian Rectanus <brian@rectanus.net>"
gpg:                 aka "Brian Rectanus (personal) <brectanu@gmail.com>"
gpg: WARNING: This key is not certified with a trusted signature!
gpg:          There is no indication that the signature belongs to the owner.

While this warning might look serious, it generally isn’t a problem, and has to do with the way gpg expects you to verify the identity of an individual. The warning basically tells you that you’ve downloaded Brian’s key from somewhere, but that you don’t really know that it belongs to him. The only way to be sure, as far as gpg is concerned, is to meet Brian in real life, or to meet someone else who knows him personally. If you want to learn more, look up web of trust on Wikipedia.

If you want to be on the cutting edge, downloading the latest development version directly from the Subversion (the source code control system used by the ModSecurity project) repository is the way to go. When you do this, you’ll get new features days and even months before they make it into an official stable release. Having said that, however, there is a reason why we call some versions “stable.” When you use a repository version of ModSecurity, you need to accept that there is no guarantee whatsoever that it will work correctly. For what it’s worth, I am currently running a development version in production, and I am confident that it will not bring my server down.

Before you can install a development version of ModSecurity, you need to know where to find it. The repository, which is hosted with SourceForge, can be viewed with a browser. The view of the root of the repository is similar to that in Figure 2-1, “ModSecurity repository root”.

Figure 2-1. ModSecurity repository root

What you probably want is located in the m2/ directory, which houses ModSecurity 2.x. Within that directory, you will find a directory structure that you will find familiar if you’ve worked with Subversion before:

m2/
    branches/
        2.1.x/
        2.5.x/
        2.6.x/
    experimental/
        [some stuff you won't care about]
    tags/
        [all releases, one per directory]
    trunk/

The trunk directory always contains the most recent development version. The active branches may sometimes contain a feature or a fix that has not been released yet. The branches will always be generally stable anyway, and the risk of something breaking is minimal.

Once you have determined the location of the version of ModSecurity that you wish to use, you can get it using the export command of Subversion, like this:

$ svn export https://mod-security.svn.sourceforge.net/svnroot/mod-security/↩
m2/trunk modsecurity-trunk

What you will get in the folder modsecurity-trunk is almost the same as what you get when you download a release. The documentation might not be in sync, however. Starting with ModSecurity 2.6, the master documentation is kept in a wiki, with copies of the wiki included with releases.

Before you can start to compile ModSecurity, you must ensure that you have a complete development toolchain installed. Refer to the documentation of the operating system you are using for instructions. If you’ll be adding ModSecurity to an operating system–provided Apache, you are likely to need to install a specific Apache development package, too. For example, on Debian and Ubuntu, you need to use apache2-prefork-dev or apache2-threaded-dev, depending on which deployment model (process-based or thread-based) you chose.

In the next step, ensure that you have resolved all the dependencies before compilation. The dependencies are listed in Table 2.2, “ModSecurity dependencies”.

If you already have Apache installed, you will only ever need to deal with libcurl, libxml2, and Lua. With Apache compiled from source, you will also need the PCRE library. Although Apache comes bundled with one, it is used in a way that does not allow other modules to access it. To work around this issue, install PCRE separately and then tell Apache to use the external copy. I explain how to do that later in this section.

If you’re installing from source, go to the packages’ web sites, and download and install the tarballs. If you’re using managed packages, you just need to determine what the missing packages are called. On Debian Lenny, the following command installs the missing packages:

# apt-get install libcurl3-dev liblua5.1-dev libxml2-dev

Refer to the documentation of the package management system used by your platform to determine how to search the package database.

The process should be straightforward from here on. Execute the following commands in succession:

$ ./configure
$ make

This set of commands assumes that you don’t need any compile-time options. If you do, see the following section. Before ModSecurity 2.6, the making of mlogc was optional and you had to execute another make mlogc to do it.

After ModSecurity is built, one more step is required to install it:

$ sudo make install

This command adds the module to your Apache installation, but does not activate it—you must do that manually. (While you are there, confirm that mod_unique_id is enabled; ModSecurity requires it.) The command will also create a folder (/usr/local/modsecurity by default) and store the various run-time files in it. Here’s what you get:

bin/
    mlogc
    mlogc-batch-load.pl
    rules-updater.pl
lib/
    mod_security2.so

$ ./configure \
    --with-pcre=/usr/bin/pcre-config \
    --enable-unique-id

$ ./configure \
    --with-apxs=/home/ivanr/apache/bin/apxs

$ ldd ~/apache/bin/httpd  | grep pcre
        libpcre.so.3 => /usr/lib/libpcre.so.3 (0xb7d3f000)

$ ldd ~/apache/modules/mod_security2.so | grep pcre
        libpcre.so.3 => /usr/lib/libpcre.so.3 (0xb7f4c000)

[notice] ModSecurity for Apache/2.6.0-rc1 (http://www.modsecurity.org/) configured.
[notice] ModSecurity: APR compiled version="1.3.8"; loaded version="1.3.8"
[notice] ModSecurity: PCRE compiled version="8.12"; loaded version="8.12 2011-01-15"
[notice] ModSecurity: LIBXML compiled version="2.7.3" 

If you are a Fedora Core user and you are running version 10 or later, you can install ModSecurity directly from the official distribution, using yum:

# yum install mod_security

On CentOS and Red Hat Enterprise Linux, you have two options. One is to use the packages from EPEL (Extra Packages for Enterprise Linux), which is a volunteer effort and part of the Fedora community. The other option is to use the custom packages built by Jason Litka. Either way, the available packages support CentOS/RHEL 4.x and 5.x, on the i386 and x86_64 architectures. The installation process is the same as for Fedora Core.

Debian was the first distribution to include ModSecurity, but also the first distribution to kick it out due to a licensing issue. The ModSecurity license was clarified in version 2.5.6 with the addition of an open source exception, and that opened the door for it to get back into Debian. Alberto Gonzalez Iniesta has been a long-time supporter of ModSecurity on Debian, supporting ModSecurity in his own (unofficial) repository, and is now the official packager.

If you are running a version of Debian or Ubuntu that includes ModSecurity, the installation is as easy as:

# apt-get install libapache-mod-security

This single command will download the package and install it, then activate the module in the Apache configuration.