> ModSecurity Handbook: Getting Started: Chapter 2. Installation


2 Installation

Before you can install ModSecurity, you need to decide if you want to compile it from source or use a binary version—either one included with your operating system or one produced by a third party. Each of the options comes with its advantages and disadvantages, as listed in Table 2.1, “Installation options”.

Table 2.1. Installation options

In some cases, you won’t have a choice. For example, if you’ve installed Apache from source, you will need to install ModSecurity from source too (you will be able to reuse the system packages, of course). The following questions may help you to make the decision:

I generally try to use binary packages when they are available (and they are available on Debian, which is currently my platform of choice). When I build dedicated reverse proxy installations, however, I tend to build everything from source, because that allows me access to the latest Apache and ModSecurity versions, and makes it easier to tweak things (by changing the source code of either Apache or ModSecurity) when I want to.

Installing from source is the preferred approach to installing ModSecurity, mostly because that way you get the latest (and best) version, and because you are able to make any changes you want.

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>" ↩
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”.

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:

        [some stuff you won't care about]
        [all releases, one per directory]

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:


Using ModSecurity with a custom-compiled version of Apache is more work than it should be because of a dependency problem that we have to resolve manually. PCRE, which ModSecurity uses for pattern matching, is a very popular library that is integrated into many operating systems. The problem is that Apache bundles PCRE and uses the bundled version by default when you compile it from source. Unless you take care to avoid conflicts, you’ll probably end up with Apache using the bundled version of PCRE and ModSecurity using the one provided by the operating system. The solution to this problem is to build Apache to use the external PCRE version too, which requires just one change to the way you build Apache.

The configure option you need (remember, this is the configure of Apache, not ModSecurity) is --with-pcre, and it is used like this:

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

We are also enabling the mod_unique_id module, which is required for ModSecurity’s full transaction log. Now you need to again compile and install Apache.

To configure ModSecurity, use the --with-apxs compile-time option to specify the location of your Apache installation. In the following example, I am assuming Apache is installed in /home/ivanr/apache:

$ ./configure \

From here you install ModSecurity as described in the previous section.

After both Apache and ModSecurity are installed, you should confirm that both products link to the same PCRE library, using ldd:

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

You should get the same result when you compile ModSecurity:

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

It is quite possible to have a configuration in which Apache uses its bundled PCRE and ModSecurity another PCRE version available on the system. This is probably the most commonly reported issue on the users’ mailing list because it not only prevents ModSecurity from working but also crashes Apache.

Starting with version 2.6, ModSecurity reports at startup (in the error log) the detected library version numbers and compares them to those used at compile time. One or more warnings will be issued if a mismatch is found. This feature is especially handy for troubleshooting PCRE library collisions.

[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" 

As previously discussed, using a binary version of ModSecurity is often the easiest option, because it just works. Unfortunately, what you gain in ease of installation you lose by sometimes being able to use only an older version. Further, packagers often do not include mlogc, which is essential for remote log centralization. For that reason, I don’t recommend installation from binaries unless there is no other way. If you do decide to check out what is available in binary form, the list of available binary packages is available from http://www.modsecurity.org/download/.

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.

ModSecurity was ported to Windows early on, in 2003, and has run well on this platform ever since. Windows binary packages of ModSecurity are maintained by Steffen Land, who runs Apache Lounge, a community for those who run Apache on Windows. In addition to ModSecurity, Steffen maintains his version of Apache itself, as well as many third-party modules you might want to run on Windows. The ModSecurity binary packages are consistently up to date, so you will have little trouble if you want to run the latest version. The download includes ModSecurity as well as mlogc.

The installation is quite easy. First, download the package and copy the dynamic libraries into the modules/ folder (of the Apache installation). Then, modify your Apache configuration to activate ModSecurity:

LoadModule security2_module modules/mod_security2.so

You will also need to activate mod_unique_id. This module may not be already active, but there should already be a commented-out line in your configuration. You just need to find it and uncomment it. If it isn’t there, just add the following:

LoadModule unique_id_module modules/mod_unique_id.so

It’s never been easier to install ModSecurity, now that it is included with so many operating system and distributions. Although the installation from source code gives you guaranteed access to the most recent version, as well as access to the yet-unreleased code, it can be time-consuming if you are not used to it. It’s not everyone’s cup of tea. There is something to be said for using the provided version and not having to think about upgrading (and saving the time it takes to upgrade).

In the next chapter, I’ll explain each of the configuration options, teaching you how to set every single option, step by step, so that everything is just the way you like it.