There is a new version of this tutorial available for Debian 8 (Jessie).

Chrooting Apache2 With mod_chroot On Debian Lenny

Version 1.0
Author: Falko Timme
Follow me on Twitter

This guide explains how to set up mod_chroot with Apache2 on a Debian Lenny system. With mod_chroot, you can run Apache2 in a secure chroot environment and make your server less vulnerable to break-in attempts that try to exploit vulnerabilities in Apache2 or your installed web applications.

I do not issue any guarantee that this will work for you!


1 Preliminary Note

I'm assuming that you have a running Debian Lenny system with a working Apache2, e.g. as shown in this tutorial: The Perfect Server - Debian Lenny (Debian 5.0) [ISPConfig 2]. In addition to that I assume that you have one or more web sites set up within the /var/www directory (e.g. if you use ISPConfig).


2 Installing mod_chroot

To install mod_chroot, we simply run:

aptitude install libapache2-mod-chroot

Then we enable mod_chroot and restart Apache:

a2enmod mod_chroot
/etc/init.d/apache2 restart


3 Configuring Apache

I want to use the /var/www directory as the directory containing the chroot jail. Debian's Apache uses the PID file /var/run/; when Apache is chrooted to /var/www, /var/run/ translates to /var/www/var/run/ Therefore we create that directory now:

mkdir -p /var/www/var/run
chown -R root:root /var/www/var/run

Now we must tell Apache that we want to use /var/www as our chroot directory. We open /etc/apache2/apache2.conf, and right below the PidFile line, we add a ChrootDir line:

vi /etc/apache2/apache2.conf
# PidFile: The file in which the server should record its process
# identification number when it starts.
# This needs to be set in /etc/apache2/envvars
ChrootDir /var/www

Next we must tell our vhosts that the document root has changed (for example, a DocumentRoot /var/www translates now to DocumentRoot /). We can do this either by changing the DocumentRoot directive of each vhost, or more easier, by creating a symlink in the file system.

3.1 First Method: Changing The DocumentRoot

Let's assume we have a vhost with DocumentRoot /var/www. We must now open the vhost configuration of that vhost and change DocumentRoot /var/www to DocumentRoot /. Accordingly, DocumentRoot /var/www/web1/web would now translate to DocumentRoot /web1/web, and so on. If you want to use this method, you must change the DocumentRoot for every single vhost.


This method is easier, because you have to do it only once and don't have to modify any vhost configuration. We create a symlink pointing from /var/www/var/www to /var/www:

mkdir -p /var/www/var
cd /var/www/var
ln -s ../../ www

Finally, we have to stop Apache, create a symlink from /var/run/ to /var/www/var/run/, and start it again:

/etc/init.d/apache2 stop
ln -s /var/www/var/run/ /var/run/
/etc/init.d/apache2 start

That's it. You can now call your web pages as before, and they should be served without problems, as long as they are static HTML files or using mod_php.

If you are using CGI, e.g. Perl, suPHP, Ruby, etc., then you must copy the interpreter (e.g. /usr/bin/perl, /usr/sbin/suphp, etc.) to the chroot jail together with all libraries needed by the interpreter. You can find out about the required libraries with the ldd command, e.g.

ldd /usr/sbin/suphp
server2:/var/www/web1/log# ldd /usr/sbin/suphp =>  (0xffffe000) => /usr/lib/ (0xb7e34000) => /lib/tls/i686/cmov/ (0xb7e0f000) => /lib/ (0xb7e03000) => /lib/tls/i686/cmov/ (0xb7cd2000)
        /lib/ (0xb7f23000)

If you've copied all required files, but the page still isn't working, you should take a look at the Apache error log. Usually it tells you where the problem is. Also read for known problems and solutions.


Share this page:

Suggested articles

2 Comment(s)

Add comment


By: Rob

I'm not running ISPConfig, but I do have a fairly standard setup of apache2 (2.2.9) on Debian Lenny. These instructions break it in a maddening manner.

 My ServerRoot is /etc/apache2; vhost configs are set up in the usual way under /etc/apache2/sites-available (and ./sites-enabled); the site files themselves are under /srv/www/(sitename)/public_html, etc.

 So, my vhost config files need to look like this:

<VirtualHost *:80>
    DocumentRoot /
    ErrorLog /srv/www/
    CustomLog /srv/www/ combined
    <Location />
        AuthUserFile /
        AuthName "Access restricted to developers"
        AuthType Basic
        require valid-user
    SetEnv TMPDIR /
    php_admin_value open_basedir /
    php_admin_value upload_tmp_dir /


 Note the goofy mix of chroot'd and not-chroot'd directories. The chroot'd DocumentRoot will trigger warnings when apache2 is started; if you ignore those, then everything appears to work OK. However, if the ErrorLog directive uses a chroot'd path, then those warnings somehow trigger a fatal error that causes apache2 to not start at all. (This makes debugging this a real adventure.) But, once it's running, the non-chroot'd paths for both ErrorLog and CustomLog seem to work just fine.

 I've verified that the DocumentRoot, ErrorLog, CustomLog, and AuthUserFile directives all work with this setup. I'm not sure about the rest.

It's possible there's something seriously wrong with my setup, but everything's been working great for months (until now), so if there is, I don't know what it is.

By: max


I am new to chrooting, so I apologise in advance if I ask silly questions. I have followed your tutorial, but now I can't run my phpMyAdmin. I installed it in /usr/local/phpMyAdmin and created a symbolic link to /var/www

As a consequence I am getting error 403 when I try to connect to it.

What am I doing wrong?


P.S. I am running Debian GNU/Linux version 5.0.7