wiki:Howto/Apache2FastCgiSuexecPhp

Apache 2 with FastCGI, SuExec and PHP

These notes are specific to Ubuntu 7.10 (Gutsy) but can be easily adjusted for other distributions.

Running PHP v5 on Apache v2.x requires the use of CGI and php-cgi if the recommended apache2-mpm-worker configuration is to be maintained. This prevents the use of libapache2-mod-php5 because that module requires apache2-mpm-prefork - these two mpm's are mutually exclusive.

Check what is installed

First Apache:

$ dpkg-query -l 'apache2*' | egrep '^ii'
ii  apache2                2.2.4-3build1  Next generation, scalable, extendable web server
ii  apache2-mpm-worker     2.2.4-3build1  High speed threaded model for Apache HTTPD
ii  apache2-utils          2.2.4-3build1  utility programs for webservers
ii  apache2.2-common       2.2.4-3build1  Next generation, scalable, extendable web server

and now PHP:

$ dpkg-query -l '*php*' | egrep '^(ii|un)'
un  libapache2-mod-php4 <none>           (no description available)
un  libapache2-mod-php5 <none>           (no description available)
un  php-doc             <none>           (no description available)
un  php-pear            <none>           (no description available)
un  php3                <none>           (no description available)
ii  php5-cgi            5.2.3-1ubuntu6.2 server-side, HTML-embedded scripting languag
ii  php5-common         5.2.3-1ubuntu6.2 Common files for packages built from the php
un  php5-json           <none>           (no description available)
ii  php5-mysql          5.2.3-1ubuntu6.2 MySQL module for php5
un  php5-mysqli         <none>           (no description available)
un  phpapi-20060613     <none>           (no description available)

The FastCGI module:

$ dpkg-query -l '*fcgi*' | egrep '^(ii|un)'
ii  libapache2-mod-fcgid 1:2.1-2        an alternative module compat with mod_fastcgi

The ii at the beginning of each line above denotes installed. Some package have dependencies on others. Use apt-get to install the packages and their dependencies if they aren't already:

$ sudo apt-get install apache2 php5-cgi libapache2-mod-fcgid

SuExec Errors

When using the Virtualmin virtual hosting management tool the home directories of each domain are under /home/. This differs from the Apache convention of /var/www/ and causes issues with suexec refusing to execute CGI programs due to permissions problems.

Two examples of errors from /var/log/apache2/suexec.log:

uid: (1014/intuitivenipple) gid: (1013/1013) cmd: php-fcgi-wrapper
cannot stat program: (php-fcgi-wrapper)

uid: (1014/intuitivenipple) gid: (1013/1013) cmd: php-fcgi-wrapper
target uid/gid (1014/1013) mismatch with directory (0/0) or program (0/0)

The first error is caused because 'php-fcgi-wrapper' is a symbolic link to /usr/bin/php-cgi and suexec doesn't allow sym-links.

The second error is caused because the directory and the executable do not have owner and group that match the ones set in the site's VirtualHost configuration (/etc/apache2/sites-available/domain.net.conf):

<VirtualHost domain.net>
  SuexecUserGroup "#1014" "#1013"

Custom SuExec Build

The suexec program has settings built in when it is compiled to prevent it being reconfigured to avoid the security restrictions it is designed to enforce.

If you are using Virtualmin (or more accurately, not using /var/www/ as the root for your virtual domains) you will need to build a custom version of apache's suexec to adjust those built-in settings. You can view them like this:

$ sudo /usr/lib/apache2/suexec -V
 -D AP_DOC_ROOT="/var/www"
 -D AP_GID_MIN=100
 -D AP_HTTPD_USER="www-data"
 -D AP_LOG_EXEC="/var/log/apache2/suexec.log"
 -D AP_SAFE_PATH="/usr/local/bin:/usr/bin:/bin"
 -D AP_UID_MIN=100
 -D AP_USERDIR_SUFFIX="public_html"

We need to change to AP_DOC_ROOT="/home" for Virtualmin.

Install the tools we need:

$ sudo apt-get install build-essential binutils

Create a directory to keep source-code separate and then fetch the source for apache2.2-common (which contains the suexec code):

$ mkdir SourceCode
$ cd SourceCode
$ sudo  apt-get  build-dep apache2.2-common
$ apt-get source apache2.2-common
Reading package lists... Done
Building dependency tree       
Reading state information... Done
NOTICE: 'apache2' packaging is maintained in the 'Svn' version control system at:
svn://svn.debian.org/pkg-apache
Need to get 6485kB of source archives.
Get: 1 http://archive.ubuntu.com gutsy/main apache2 2.2.4-3build1 (dsc) [1235B]
Get: 2 http://archive.ubuntu.com gutsy/main apache2 2.2.4-3build1 (tar) [6366kB]
Get: 3 http://archive.ubuntu.com gutsy/main apache2 2.2.4-3build1 (diff) [118kB]
Fetched 6485kB in 3s (1849kB/s)
gpg: Signature made Thu 04 Oct 2007 19:28:33 BST using DSA key ID 0A0AC927
gpg: Can't check signature: public key not found
dpkg-source: extracting apache2 in apache2-2.2.4
dpkg-source: unpacking apache2_2.2.4.orig.tar.gz
dpkg-source: applying ./apache2_2.2.4-3build1.diff.gz

Check the  Apache 2.2 documentation for details of all the suexec configure options and also Linode-member Internat's guide to  rebuilding the apache2.2-common Debian/Ubuntu package.

Move into the source-code directory and configure for our custom requirements:

$ cd  apache2-2.2.4
$ ./configure --prefix=/usr --enable-suexec --with-suexec-caller=www-data --with-suexec-userdir=public_html \
 --with-suexec-docroot=/home --with-suexec-uidmin=100 --with-suexec-gidmin=100 --with-suexec-logfile=/var/log/apache2/suexec.log \
 --with-suexec-safepath='/usr/local/bin:/usr/bin:/bin'

The configure script is responsible for checking that the host PC has all the tools and code-library headers installed. If configure reports an error and mentions a missing library, then you need to install the development headers for that library. Usually the package name has the -devel suffix so, for example, if "libsomething" is missing, the first thing to try is

$ sudo apt-get install libsomething-devel

If this doesn't solve it, search for the correct development library name using:

$ apt-cache search libsomething

If you still can't find it, try a search engine or look at the Ubuntu package repositories.

Assuming configure completed successfully you should see:

...
config.status: creating support/apxs
config.status: creating support/apachectl
config.status: creating support/dbmmanage
config.status: creating support/envvars-std
config.status: creating support/log_server_status
config.status: creating support/logresolve.pl
config.status: creating support/phf_abuse_log.cgi
config.status: creating support/split-logfile
config.status: creating build/rules.mk
config.status: creating build/pkg/pkginfo
config.status: creating build/config_vars.sh
config.status: creating include/ap_config_auto.h
config.status: executing default commands

With everything configured we can build the package:

$ make

Assuming make completes without errors, check that suexec was built and has the correct configuration:

$ ls  support/suexec
support/suexec
$ sudo support/suexec -V
 -D AP_DOC_ROOT="/home"
 -D AP_GID_MIN=100
 -D AP_HTTPD_USER="www-data"
 -D AP_LOG_EXEC="/var/log/apache2/suexec.log"
 -D AP_SAFE_PATH="/usr/local/bin:/usr/bin:/bin"
 -D AP_UID_MIN=100
 -D AP_USERDIR_SUFFIX="public_html"

Now we need to back-up the installed suexec and put this new version in its place:

$ sudo mv /usr/lib/apache2/suexec /usr/lib/apache2/suexec-var-www
$ sudo cp support/suexec /usr/lib/apache2/suexec
$ sudo chown root:www-data /usr/lib/apache2/suexec
$ sudo chmod 4750 /usr/lib/apache2/suexec

Configure Virtual Domains

Now that suexec is ready it is time to configure the virtual domains. The directory structure is usually something like this:

/home/domain.net/
/home/domain.net/logs/
/home/domain.net/public_html/
/home/domain.net/cgi-bin/
/home/domain.net/domains/

To those we'll add conf/ (for custom php.ini) and lib/ (for files accessible to php-cgi but outside the web-root).

/home/domain.net/conf/
/home/domain.net/lib/

As an example the  pastebin package configuration and code libraries would be installed in lib/.

You will need to repeat the following steps for each virtual domain that needs FastCGI access to PHP (modifying base path and user/group settings for each). The result is that each virtual domain's CGI scripts run as the correct user. See the section Automate Configuration of New Domains with Skeleton for how to add these values to the Virtualmin domain templates so new domains are created with PHP enabled.

To execute the CGI properly the executable, and the directory it is in, must have the same user and group as those set in the site's SuexecUserGroup statement (referred to earlier). The usual way to assure this is to set SuexecUserGroup to match the user and group of the home directory of the user.

The user's home directory and all directories below it should already meet those requirements so we can install a script in cgi-bin/ that will call the /usr/bin/php-cgi executable.

Change to the user's home directory and create the directories:

$ cd /home/<virtual-domain-user>
$ mkdir conf
$ mkdir lib
$ mkdir -p cgi-bin/php5-default

Create conf/php.ini with this content. Make sure to adjust the paths to match the domain:

include_path = ".:/home/intuitivenipple.net/lib"
open_basedir "/home/intuitivenipple.net:/tmp"

Create the script cgi-bin/php5-default/php-fcgi-wrapper with the following contents:

#!/bin/sh
# Wrapper for PHP-fcgi
# This wrapper can be used to define settings before launching the PHP-fcgi binary.

# Define the path to php.ini. This defaults to /etc/phpX/cgi.
export PHPRC=/home/intuitivenipple.net/conf

# Define the number of PHP child processes that will be launched. 
# This is low to control memory usage on a server that might launch
# these processes for lots of domains.
# Leave undefined to let PHP decide.
export PHP_FCGI_CHILDREN=1

# Maximum requests before a process is stopped and a new one is launched
export PHP_FCGI_MAX_REQUESTS=5000

# Launch the PHP CGI binary
# This can be any other version of PHP which is compiled with FCGI support.
exec /usr/bin/php5-cgi

Change the PHPRC path to match the user.

Make sure the directories and the script have the correct user and group ID. Replace <user> and <group> with your virtual domain's user and group respectively:

$ sudo chown -R <user>:<group> cgi-bin/php5-default
$ sudo chown -R <user>:<group> conf
$ sudo chown -R <user>:<group> lib

You can use these same steps to install other CGI scripts.

Now the virtual domain's Apache configuration needs a block of directives adding that will activate the FastCGI PHP handler.

Many guides and tutorials show this done on a per-server basis by adding a file to /etc/apache2/conf.d/. The file is often called php-fcgid.conf.

That file will work fine with mod_user (allows access to user's public_html via  http://server.domain.net/~user) but won't work with virtual domains where the CGI script has to be owned by the SuexecUserGroup of each Virtual Host.

If you have that already installed in /etc/apache2/conf.d/ you should consider removing it and also deleting the default FastCGI directories at /var/www/fcgi-bin.d/.

Add the following block of directives to the virtual domain's Apache configuration file. The files are usually in the directory /etc/apache2/sites-available/.

For my site, the file is /etc/apache2/sites-available/intuitivenipple.net.conf The file will start something like:

<VirtualHost 67.18.187.60:80>
 SuexecUserGroup "#1014" "#1013"
 ServerName intuitivenipple.net
 ServerAlias www.intuitivenipple.net

Ensure the SuexecUserGroup IDs are correct. Here, they are specified as the UID and GID numbers rather than the names (saves Apache time having to look them up). You can get them like this:

$ grep intuitivenipple /etc/passwd
intuitivenipple:x:1014:1013::/home/intuitivenipple.net:/bin/sh

The first number is the UID, the second is the GID. You can cross-reference the GID to its name like this:

$ grep 1013 /etc/group
intuitivenipple:x:1013:www-data

This shows that the group has www-data as a member. That is the identity that Apache runs as.

Now add the FastCGI conditional statements to the end of the virtual domain configuration file, inserting them in front of the closing </VirtualHost> directive, so it looks like this:

 <IfModule !mod_php4.c>
  <IfModule !mod_php4_filter.c>
   <IfModule !mod_php5.c>
    <IfModule !mod_php5_filter.c>
     <IfModule !mod_php5_hooks.c>
      <IfModule mod_actions.c>
       <IfModule mod_alias.c>
        <IfModule mod_mime.c>
         <IfModule mod_fcgid.c>
          # Define a new handler "php-fcgi" for ".php" files, plus the action that must follow
          AddHandler php-fcgi .php
          Action php-fcgi /fcgi-bin/php-fcgi-wrapper
    
          # Define alias "/fcgi-bin/". The action above is using this value, which means that
          # you could run another "php5-cgi" command by just changing this alias
          Alias /fcgi-bin/ /home/intuitivenipple.net/cgi-bin/php5-default/
    
          # Turn on the fcgid-script handler for all files within the alias "/fcgi-bin/"
          <Location /fcgi-bin/>
           SetHandler fcgid-script
           Options +ExecCGI
          </Location>
          # ensure no access to the script source code
          ReWriteEngine On
          ReWriteRule ^/fcgi-bin/[^/]*$ / [PT] 
         </IfModule>
        </IfModule>
       </IfModule>
      </IfModule>
     </IfModule>
    </IfModule>
   </IfModule>
  </IfModule>
 </IfModule>

</VirtualHost>

Make sure you set the Alias path to the correct directory! E.g.

Alias /fcgi-bin/ /home/domain.net/cgi-bin/php5-default/

Save the file then restart Apache:

$ sudo /etc/init.d/apache2 restart

Test

Add a simple PHP test file to the web-root:

$ echo "<?php phpinfo() ?>" > public_html/info.php
$ chown <user>:<group> public_html/info.php

You can test it from a browser or even from the command line using wget to ensure the server returns a 200 OK response:

$  wget -O - http://domain.net/info.php | head
--21:59:07--  http://domain.net/info.php
           => `-'
Resolving domain.net... 10.1.2.3
Connecting to domain.net|10.1.2.3|:80... connected.
HTTP request sent, awaiting response... 200 OK

If you see the PHP configuration reported in your browser, starting with something like "PHP Version 5.2.3-1ubuntu6.2", then you've successfully installed SuExec protected FastCGI access to PHP 5.

Repeat For All Domains

Remember to repeat the per-virtual-domain steps for each domain that requires PHP support. You can automate that to some degree by adding the directories and files to the /etc/skel/ directory so when a user is created they are copied and permissions set correctly.

If you're working with sub-domains you can copy the parent's cgi-bin directory to the sub-domain (assuming the parent already has the PHP CGI script installed!):

$ pwd
/home/domain.net

$ cp -a cgi-bin domains/subdomain.domain.net/

and then add the FastCGI configuration directives to the sub-domain's apache configuration by editing /etc/apache2/sites-available/subdomain.domain.net.conf to add the Fast CGI directives as described previously.

Make sure to set the Alias path correctly. For sub-domains it is of the form Alias /fcgi-bin/ /home/domain.net/domains/subdomain.domain.net/cgi-bin/php5-default/

And of course, reload the configuration once more:

$ sudo /etc/init.d/apache2 reload

Automate Configuration of New Domains with Skeleton

To automate the configuration for all new domains you can configure the Virtualmin default Apache template and add to the /etc/skel/ directory.

In Virtualmin:

  1. go to System Settings > Server Templates
  2. Select the Default Settings template
  3. choose Edit Template Section Apache website

In the Directives and settings for new websites text-area add the following lines to the end of the existing template text:

 <IfModule !mod_php4.c>
  <IfModule !mod_php4_filter.c>
   <IfModule !mod_php5.c>
    <IfModule !mod_php5_filter.c>
     <IfModule !mod_php5_hooks.c>
      <IfModule mod_actions.c>
       <IfModule mod_alias.c>
        <IfModule mod_mime.c>
         <IfModule mod_fcgid.c>
          # Define a new handler "php-fcgi" for ".php" files, plus the action that must follow
          AddHandler php-fcgi .php
          Action php-fcgi /fcgi-bin/php-fcgi-wrapper
    
          # Define alias "/fcgi-bin/". The action above is using this value, which means that
          # you could run another "php5-cgi" command by just changing this alias
          Alias /fcgi-bin/ ${HOME}/cgi-bin/php5-default/
    
          # Turn on the fcgid-script handler for all files within the alias "/fcgi-bin/"
          <Location /fcgi-bin/>
           SetHandler fcgid-script
           Options +ExecCGI
          </Location>
         </IfModule>
        </IfModule>
       </IfModule>
      </IfModule>
     </IfModule>
    </IfModule>
   </IfModule>
  </IfModule>
 </IfModule>

Notice how the alias uses a variable:

Alias /fcgi-bin/${HOME}/cgi-bin/php5-default/

Save that change and then open a terminal to the server and add the cgi-bin and PHP directories and script to /etc/skel/:

$ sudo mkdir -p  /etc/skel/cgi-bin/php5-default
$ sudo mkdir /etc/skel/conf
$ sudo mkdir /etc/skel/lib

Create the shell script /etc/skel/cgi-bin/php5-default/php-fcgi-wrapper with these contents:

#!/bin/sh
# Wrapper for PHP-fcgi
# This wrapper can be used to define settings before launching the PHP-fcgi binary.

# Define the path to php.ini. This defaults to /etc/phpX/cgi.
export PHPRC=${HOME}/conf

# Define the number of PHP child processes that will be launched. 
# This is low to control memory usage on a server that might launch
# these processes for lots of domains.
# Leave undefined to let PHP decide.
export PHP_FCGI_CHILDREN=1

# Maximum requests before a process is stopped and a new one is launched
export PHP_FCGI_MAX_REQUESTS=5000

# Launch the PHP CGI binary
# This can be any other version of PHP which is compiled with FCGI support.
exec /usr/bin/php5-cgi

Create the /etc/skel/conf/php.ini file:

include_path = ".:${HOME}/lib"
open_basedir "${HOME}:/tmp"

Set the correct permissions on the files:

$ sudo chmod 750 /etc/skel/cgi-bin/php5-default/php-fcgi-wrapper
$ sudo chmod 750 /etc/skel/conf/php.ini

After creating a new user check that the installed /home/<user>/cgi-bin/php5-default/php-fcgi-wrapper and /home/<user>/conf/php.ini have had ${HOME} expanded correctly to the absolute path. If not, correct it.

$ cd /home/username
$ NEWHOME="$(pwd)"
$  sed  -ibak -e "s,\${HOME},${NEWHOME}," cgi-bin/php5-default/php-fcgi-wrapper
$  sed  -ibak -e "s,\${HOME},${NEWHOME}," conf/php.ini

This is because when installing from the skeleton files the system has the option of whether or not to expand shell variables in the files, and by default it doesn't (otherwise .profile and others would be a total mess!).

That should be sufficient to ensure all new domains have PHP FastCGI enabled automatically.