mod_chroot

What is it?

mod_chroot makes running Apache in a secure chroot environment easy. You don't need to create a special directory hierarchy containing /dev, /lib, /etc...

mod_chroot is now included in

Many thanks to all package maintainers!

Why chroot?

For security.

chroot(2) changes the root directory of a process to a directory other than "/". It means the process is locked inside a virtual filesystem root. If you configure your chroot jail properly, Apache and its child processes (think CGI scripts) won't be able to access anything except the jail.

A non-root process is not able to leave a chroot jail. Still it's not wise to put device files, suid binaries or hardlinks inside the jail.

chroot - the hard way

There are many documents about running programs inside a chroot jail. Some daemons (tinydns, dnscache, vsftpd) support it out of the box. For others (like Apache) you need to carefully build a "virtual root", containing every file the program may need. This usually includes:

Creating this structure is great fun. Run the program, read the error message, copy the missing file, start over. Now think about upgrading - you have to keep your "virtual root" current - if there is a bug in libssl, you need to put a new version in two places. Scared enough? Read on.

chroot - the mod_chroot way

mod_chroot allows you to run Apache in a chroot jail with no additional files. The chroot() system call is performed at the end of startup procedure - when all libraries are loaded and log files open. There are still some things you have to keep in mind - see below.

Installation and configuration is covered by INSTALL.

Caveats

Running Apache (and CGI/Perl/PHP) inside a chroot jail can be tricky. Read CAVEATS for known problems and solutions.

mod_chroot has been tested under Linux 2.4 and FreeBSD 4-STABLE with Apache 1.3.29. It should work under older versions of Apache 1.3 as well.

Starting from version 0.3, mod_chroot supports Apache 2. It has been tested with Apache 2.0.51 under Linux 2.4 and FreeBSD 4-STABLE. It should work under older versions of Apache 2.0 as well. Be sure to read Apache 2.0 notes before using mod_chroot with Apache 2.0

Download

All published version of mod_chroot are available at http://core.segfault.pl/~hobbit/mod_chroot/dist. Please use the latest one.

Contact

Mail addresses:

mod_chroot mailing list is also available via GMane (as gmane.comp.apache.mod-chroot.general). GMane also has a nice archive.

Prior art

I needed a simple module just to perform chroot at startup. Before I started coding, I found mod_security which does this, among others. I didn't need URL normalization and other mod_security features so I decided to create my own module. My code is similar to mod_security, with some sanity checks added. mod_security is developed by Ivan Ristic.

See here for reasons to choose mod_chroot over mod_security.

Contributed code

contrib contains various pieces written by other people (currently - a patch against mod_chroot 0.5 to make it use RSBAC jail feature instead of standard chroot, by Ang-st)

Valid XHTML 1.0! Valid CSS!