Skip to content

apache2 with php fpm

Michael Kaufmann edited this page Mar 29, 2017 · 1 revision

1. Introducion

With PHP 5.3.3 a new PHP SAPI handler was added to PHP. Its called PHP-FPM (FastCGI Process Manager). PHP-FPM is an alternative PHP FastCGI implementation with some additional features useful for sites of any size, especially busier sites.

More Infos can be found here:


  • Fast + Secure. PHP is thread safe that way so you can use Apache mpm-worker for better performance and less memory overhead as with apache prefork and mod-php.
  • No permission problems between the FTP- and Webserver-users


  • More difficult to setup.

I assume that you have Froxlor already running (using mod_php) and the database set up.

2. Setting up the environment

First of all you should install all needed packages.

Debian Wheezy:

apt-get install libnss-mysql-bg nscd libapache2-mod-fastcgi apache2-suexec php5-fpm

Now that php5-fpm is installed, enable fastcgi by typing this in a root shell:

a2enmod fastcgi actions

Now restart Apache with

/etc/init.d/apache2 restart

3. Setting up username <-> user ID mappings

You should ensure that the Froxlor cronjob isn't executed while you set up fastcgi. This could produce unwanted results!

/etc/init.d/cron stop

In order to have php-fpm work as intended you need real usernames since php-fpm cannot work with the virtual user IDs Froxlor uses by default. We must get 'libnss-mysql' to read usernames from MySQL. The FTP table in the Froxlor database provides us with every information we need. To avoid any bottlenecks that might happen with big directories we install the name service caching daemon 'nscd'.

Now copy and paste the actual configuration files from the Froxlor panel and apply them to your file system. You'll need the to create or update the following files:

  • /etc/libnss-mysql-root.cfg
  • /etc/libnss-mysql.cfg
  • /etc/nsswitch.conf

Make sure that only root can read those configuration files since they include your Froxlor database password!

chmod 600 /etc/libnss-mysql-root.cfg /etc/libnss-mysql.cfg
/etc/init.d/nscd restart

Now it should already work. To find out if it really works just go to a directory that was created by Froxlor and check if the user ID got replaced by the username.

ls -al /var/customers/webs/

This should produce a result like:

drwxr-xr-x  3 web1      web1       4096 2008-06-13 17:18 web1
drwxr-xr-x  8 web2      web2       4096 2009-01-02 17:40 web2
drwxr-xr-x 10 web3      web3       4096 2009-01-25 13:33 web3

If you don't see a result like this or just the virtual user IDs, re-check your configuration and whether these users really exist using the getent passwd command. If nscd isn't working properly you cannot continue with the next steps.

4. Setting up fastcgi

Now edit /etc/apache2/mods-available/fastcgi.conf - it needs to look like this:

 <IfModule mod_fastcgi.c>
     FastCgiIpcDir /var/lib/apache2/fastcgi 
     <Location "/fastcgiphp">
         Order Deny,Allow
         Deny from All
         # Prevent accessing this path directly
         Allow from env=REDIRECT_STATUS

5. Enable fastcgi and PHP-FPM in Froxlor

You must now instruct Froxlor to create the FPM configuration and to add related directives to Apache's VirtualHost configurations.

In order to use FPM you need to create a user froxlorlocal and a group of the same name:

addgroup --gid 9999 froxlorlocal
adduser --no-create-home --uid 9999 --ingroup froxlorlocal --shell /bin/false --disabled-password --gecos '' froxlorlocal

Now activate, in the Settings section on the Froxlor admin web panel, the PHP-FPM option.

When you load the settings overview page (compact overview) again, you'll see a new link to configure PHP-FPM. Click it, then set the configuration directory of php-fpm - this is where Froxlor stores the PHP-FPM configuration. The default value of @/etc/php5-fpm@ will not work on Debian (unless you make further customizations), so use this instead:


Adjust the command to start on of php5-fpm: (by default there is only "/etc/init.d/php-fpm restart" - without 5)

/etc/init.d/php5-fpm restart

Check whether the temporary directory is correct and check "Use PHP-FPM in Froxlor Vhost".

Finaly, in /etc/init.d/php5-fpm, edit the line starting @# Required-Start@ to look like this:

# Required-Start:    $remote_fs $network mysql nscd

This insert the start of php5-fpm into the boot process and ensures it is started later than mysql and nscd. This is essential to receive the correct UID/GUI to start php5-fpm! If there are any problems with this during boot (check /var/log/boot), you can edit the /etc/init.d/apache2 init script, making it start php5-fpm before Apache.

6. Final Steps

Log in to Froxlor and click on ''Rebuild Configuration Files''.

Run Froxlor's global cron job once to immediately produce fastcgi configurations for all VirtualHosts:

/usr/bin/php5 /var/www/froxlor/scripts/froxlor_master_cronjob.php --force --debug

Now install apache2-mpm-worker since it's faster than the non-threaded apache-mpm-prefork variant (which is required for mod_php). Also disable or remove mod_php.

apt-get install apache2-mpm-worker

You also want to restart the Cron daemon now:

/etc/init.d/cron start

If you have set up all correctly it should be now possible to open the customer domains in your browser. If there are PHP child processes under the Apache process all is working fine. You can also check that by running phpinfo(); from a file within a customer domain.

7. Possible Problems you might run into

There are like 1 billion problems you might have to face ;)

  • First get nss-mysql and nscd running
  • Dont forget to restart nss-mysql and nscd
  • Check if path to init.d script and fpm config are correctly set
  • 500 Internal Server Error - Check the logs! Often you can find the solution by the given errors. This may help you further
  • Enable debug logging for apache and restart it. (LogLevel debug in /etc/apache2/apache2.conf) Be sure to uncomment this line and do a restart of apache after debugging!
  • Look at the logs!!!
  • Run @ps faux@ and check whether there is a PHP process running under the apache process.
  • When editing configuration files, please do not use WinSCP or Windows Notepad. Wditing files using these utilities will convert them to Windows format - and Linux will be unable to read those.
  • If there are problems with restarting PHP5-FPM, try editing the start-script and reduce the timeout from 30 seconds to 5 seconds. Especially with many customers it may take a long time to start PHP-FPM up during boots.

Still problems?

If you run into problems with this how-to please let us know. Please prefer the Forum over the Bugtracker or IRC. Thanks!

You can’t perform that action at this time.