Starting from version 0.3 mod_chroot supports both Apache 1.3 and 2.0. While most problems with Apache 1.3 are solved in 2.0 (no more module ordering hassle, no need to apply EAPI patches), architecture changes that appeared in 2.0 created one new problem: multi-processing modules (MPMs). MPMs are core Apache modules responsible for handling requests and dispatching them to child processes/threads.

Unfortunately, MPMs are initialized after all "normal" Apache modules. This basically means that with mod_chroot, MPM initialization is done after a chroot(2) call; when control is handed to MPM, Apache is already inside a jail. And MPMs need to create some files during startup (at least one, a pidfile) - these have to be placed inside the jail. I suggest creating a special directory for these files inside your jail, /var/www/var/run:

# mkdir -p /var/www/var/run
# chown -R root.root /var/www/var/run

Then, put the following in httpd.conf:

PidFile /var/run/
ChrootDir /var/www
DocumentRoot /
... other MPM directives (LockFile? ScoreBoardFile?)

Remember that you'll also need to link /var/run/ to /var/www/var/run/ to keep apachectl happy:

ln -s /var/www/var/run/ /var/run/

Note that this only applies to MPMs. All "normal" Apache modules will be initialized before chroot(2) call is done; all files required by these modules can safely be stored outside of the jail.

Below I put a short list of MPM directives affected by mod_chroot. "Description" and "MPM" lines in this list are taken directly from Apache 2.0 documentation. Note that in most cases I tested only one special file inside a jail is required: a pidfile. Your mileage may vary.


DescriptionFile where the server records the process ID of the daemon
MPMsbeos, leader, mpm_winnt, mpmt_os2, perchild, prefork, threadpool, worker
Notes This one is probably unavoidable. Apache's pidfile needs to be stored inside the jail. Use:
PidFile /var/run/


Description Method that Apache uses to serialize multiple children accepting requests on network sockets
MPMsleader, perchild, prefork, threadpool, worker
Notes If this directive is not set (or set to Default), the compile-time selected default is used. Under all systems I tested this default uses shared memory (posixsem, sysvsem or pthread). Two other methods (flock and fcntl) require access to a file (set with LockFile). If your Apache complains about LockFile being unaccessible, try setting AcceptMutex to sysvsem, posixsem or pthread. If your Apache doesn't support them, try flock or fcntl and see LockFile.


Description Location of the accept serialization lock file
MPMsleader, perchild, prefork, threadpool, worker
Notes If your system doesn't allow you to set AcceptMutex to anything different than flock or fcntl, you'll need to store the lockfile inside the jail. Use:
LockFile /var/run/httpd.lock


Description Directory where Apache attempts to switch before dumping core
MPMsbeos, leader, mpm_winnt, perchild, prefork, threadpool, worker
Notes You don't need this one unless you're debugging Apache. Default value for this directive is the directory set with ServerRoot, which is usually owned by root; Apache is unable to create the coredump there anyway and discards it. If you really want to analyze the dumps, use:
CoreDumpDirectory /var/run


Description Location of the file used to store coordination data for the child processes
MPMsbeos, leader, mpm_winnt, perchild, prefork, threadpool, worker
Notes If this directive is not specified, Apache will try to use shared memory. If your architecture doesn't support that, a file will be used. If this is your case, use:
ScoreBoardFile /var/run/httpd.scoreboard

« back to INSTALL

« back to INDEX

Valid XHTML 1.0! Valid CSS!