Gentoo Wiki


This article is outdated. Please update this article with new information to match with the current portage tree and gentoo releases, and remove information about really old versions of software, then remove {{Update}} from this article's source.

Warning: This page is outdated. You are welcome to update it to be used with PHP5. Please refer to LightTPD#Installation instead of repeating the whole installation routine. Merge further LightTPD- and PHP-specific information with LightTPD and PHP, respectively.



This howto focuses on explaining how to safely set up a standalone PHP instance within a chroot jail. While I will be using the lighttpd HTTP server as my platform, it should be fairly straightforward to configure Apache (or any other FastCGI-enabled web server) to use the same setup.

While knowledge of how chroot jails work is not required, you are encouraged to also read the HOWTO Jail. This howto will only tell you which commands to type in and does not explain what they do or how they work in detail.


I decided to configure my PHP setup to run inside a chroot jail due to my strong dislike for the security of PHP and its typical applications. The security advantages provided by this setup include:


If you don't already have these USE flags set, or don't want to set them globally, tweak your /etc/portage/package.use accordingly:

echo "dev-lang/php cgi memlimit hardenedphp" >> /etc/portage/package.use
echo "www-servers/lighttpd fastcgi" >> /etc/portage/package.use

Then, to install these packages, run:

emerge -atv jail \<dev-lang/php-5 lighttpd

TODO: Is the net-www/spawn-fcgi package a feasible alternative for other webservers? [it doesn't support the -P (pidfile) option]

Setting up the jail

First and foremost, you need to decide where you want to locate your jail. Since I'm running more than one jail on my setup, I decided to create a common /jail parent directory, and have all my jails there:

mkdir -p /jail/php

Next you need to create the user account that is going to inhabit the new jail:

groupadd php
useradd -d /jail/php -s /usr/bin/jail -g php -G php php

Now initialize the jail environment and create the user within the jail.

mkjailenv /jail/php
mkdir /jail/php/{bin,lib,php}
cp -d /lib/ld-*.so* /jail/php/lib/
addjailuser /jail/php /php /bin/sh php

TODO: Also explain how to set up a shell-less jail environment.Insert non-formatted text here

TODO: AMD64 machines need /lib64, not /lib

Set up the jail shell. If you want to use an alternative shell within the jail environment, such as dash, just substitute all occurences of bash.

addjailsw /jail/php -P /bin/bash "-c exit"
ln -s bash /jail/php/bin/sh

Optional: If you want to restrict access to the PHP jail for everyone else, enter these commands:

chown root:php /jail/php
chmod 0750 /jail/php

Installing and setting up software

This step is fairly trivial. You have to run addjailsw with every executable in your host environment that you want to have available in the jail. Note that the last command line argument is passed on to the program itself, and has to force it to exit - otherwise addjailsw will just hang. Note that we already installed a shell into the jail environment in the last step.

Some programs necessary for the correct operation of this howto:

addjailsw /jail/php -P /usr/bin/chmod "--version"
addjailsw /jail/php -P /usr/bin/php-cgi "--version"
addjailsw /jail/php -P /usr/bin/spawn-fcgi "-v"

TODO: Optional: imagemagick


This howto was mainly written by intgr. See my user page for contact details.

Retrieved from ""

Last modified: Fri, 15 Aug 2008 12:35:00 +0000 Hits: 5,342