Install PHP-FPM on Debian

This howto is tested on:

• Debian 6.0 Squeeze
• Debian 7.0 Wheezy
• Ubuntu 13.10 Saucy Salamander

Prerequisites

This howto needs

• the Debian "contrib" repository, as described by Setup the contrib and non-free Debian repositories.
• One of this HTTP servers:

• Apache 2, as described by Install and setup Apache 2 on Debian.
• Lighttpd, as described by Install and setup Lighttpd on Debian.

On Debian 6.0 Squeeze, this howto needs:

• the Dotdeb repository, as described by Setup the Dotdeb apt repository on Debian. Once the setup is done, follow the Install PHP 5.3 packages provided by Dotdeb section.

Installation

FPM setup

Install the software package:

command apt-get install php5-fpm php5

Install the suhosin extension if available:

if [ -n "$(command apt-cache pkgnames php5-suhosin)" ]; then
  command apt-get -y install php5-suhosin
fi

Backup the php-fpm configuration template:

command dpkg-divert --divert '/etc/php5/fpm/pool.d/www.conf-dist' \
    --rename '/etc/php5/fpm/pool.d/www.conf'

Create php-fpm configuration file:

command test -e '/etc/php5/fpm/pool.d/www.conf' \
    || command cp '/etc/php5/fpm/pool.d/www.conf-dist' '/etc/php5/fpm/pool.d/www.conf'

Setup php-fpm to listen for connections on a Unix socket and to allow PHP execution duration up to 600 seconds :

if [ -e '/etc/php5/fpm/pool.d/www.conf' ]; then
  command sed -i \
      -e 's|^listen =.*$|listen = /var/run/php5-fpm.sock|' \
      -e 's|^;*request_terminate_timeout.*|request_terminate_timeout = 605|' \
      -e 's|^;*pm.status_path.*|pm.status_path = /php-fpm-status|' \
      -e 's|^;*ping.path.*|ping.path = /php-fpm-ping|' \
      '/etc/php5/fpm/pool.d/www.conf'
fi

Important: from now, load newly installed PHP extensions with:

if [ -n "$(command find '/etc/php5/fpm/pool.d/' -name '*.conf')" ]; then
  command service php5-fpm restart
fi

Setup the log rotation:

if [ ! -e '/etc/logrotate.d/php5-fpm' ]; then
  command echo -e "/var/log/php5-fpm.log {
\trotate 12
\tweekly
\tmissingok
\tnotifempty
\tcompress
\tdelaycompress
\tpostrotate
\t\tinvoke-rc.d php5-fpm force-reload > /dev/null
\tendscript
}" \
    > '/etc/logrotate.d/php5-fpm'
fi

Finalization

This howto recommends :

• Enhancing of PHP5 default configuration, as described by Enhance PHP 5 initial setup on Debian.
• Logging PHP errors with Syslog, as described by Log PHP errors with Syslog.
• Installing APC op-code cache, as described by Install the PHP APC extension on Debian.

HTTP server configuration

Apache 2 configuration

Install Apache 2 FastCGI module :

if [ -d '/etc/apache2' ]; then
  command apt-get install libapache2-mod-fastcgi
fi

Download Apache 2 configuration to connect PHP-FPM and FastCGI module :

if [ -d '/etc/apache2' ]; then
  command wget 'https://raw.github.com/biapy/howto.biapy.com/master/apache2/php-fpm/php5-fpm.load' \
      --quiet --no-check-certificate --output-document='/etc/apache2/mods-available/php5-fpm.load'
  command wget 'https://raw.github.com/biapy/howto.biapy.com/master/apache2/php-fpm/php5-fpm.conf' \
      --quiet --no-check-certificate --output-document='/etc/apache2/mods-available/php5-fpm.conf'
fi

Enable the php-fpm dummy module for Apache 2 :

if [ -d '/etc/apache2' ]; then
  command a2dismod php5
  command a2enmod php5-fpm fastcgi actions
fi

Reload Apache 2 configuration :

[[ -x '/etc/init.d/apache2' ]] && command service 'apache2' 'force-reload'

If the configuration work, install apache2-mpm-worker :

if [ -d '/etc/apache2' ]; then
  command apt-get install apache2-mpm-worker
fi

Lighttpd configuration

Setup Lighttpd to use PHP-FPM :

if [ -d '/etc/lighttpd' ]; then
echo '# /usr/share/doc/lighttpd-doc/fastcgi.txt.gz
# http://redmine.lighttpd.net/projects/lighttpd/wiki/Docs:ConfigurationOptions#mod_fastcgi-fastcgi

## Start an FastCGI server for php (needs the php5-cgi package)
fastcgi.server += ( ".php" => 
  ((
    "socket" => "/var/run/php5-fpm.sock"
  ))
)' \
    > '/etc/lighttpd/conf-available/15-fastcgi-php-fpm.conf'
fi

Enable the new configuration :

if [ -x '/usr/sbin/lighty-enable-mod' ]; then
  command lighty-disable-mod fastcgi-php
  command lighty-enable-mod fastcgi-php-fpm
fi

Reload Lighttpd configuration :

[[ -x '/etc/init.d/lighttpd' ]] && command service 'lighttpd' 'force-reload'

Solving issues

.htaccess: Invalid command 'php_flag'

If Apache 2 error log shows this error :

.htaccess: Invalid command 'php_flag', perhaps misspelled or defined by a module not included in the server configuration

One of the howted site use "php_flag" rule in a .htaccess file. This rule is provided by php5 Apache 2 module (aka. mod_php5), and is not working with FastCGI or PHP-FPM.

To fix the error, comment the faulty lines in the .htaccess file, and create the equivalent ini file in /etc/php5/conf.d/.

FastCGI: comm with server aborted : idle timeout

If Apache 2 error log shows this error :

FastCGI: comm with server "/var/lib/apache2/fastcgi/php5.fastcgi" aborted: idle timeout (610 sec)

The execution time of a PHP page is over 610s. It can happen, for example, during the upgrade of a Web application.

To fix the error, raise the -idle-timeout option in /etc/apache2/mods-available/php5-fpm.conf:

FastCGIExternalServer /var/lib/apache2/fastcgi/php5.fastcgi -socket /var/run/php5-fpm.sock -idle-timeout 910

Raise the request_terminate_timeout option in /etc/php5/fpm/pool.d/www.conf (its value need to be slightly less than the idle-timout value (see above) :

request_terminate_timeout = 905

This two values must be greater than the PHP max_execution_time value.

ERROR: failed to ptrace(PEEKDATA) pid XXXXX : Input/output error (5)

If PHP-FPM log (/var/log/php5-fpm.log) shows:

ERROR: failed to ptrace(PEEKDATA) pid 25478: Input/output error (5)

This error appears when the "request_slowlog_timeout" option is enabled. It is due to a failure to create the error trace. This can trigger a server indisponibility because:

1. After php-fpm stops the process to trace it, the process fails to resume because of the error tracing it
2. The process is resuming but continues to run forever.

To solve this problem, disable the "request_slowlog_timeout" option:

command sed -i \
    -e 's/^request_slowlog_timeout/;request_slowlog_timeout/' \
  '/etc/php5/fpm/pool.d/'*'.conf'

Reload the PHP-FPM configuration:

command service 'php5-fpm' 'force-reload'

Thanks

• Thanks to PHP-FPM (en) developers.
• Thanks to Evolix (fr) for Howto Nginx + PHP-FPM (fr).
• Thanks to MyProd (fr) for Apache2, PHP-FPM, FastCGI et APC cache d’Opcode (fr).
• Thanks to HowtoForge (en) for Using PHP5-FPM With Apache2 On Ubuntu 11.10 (en).
• Thanks to Failover (en) for Quick Setup: Apache Worker, FastCGI, PHP-FPM and APC (en).
• Thanks to cd ~tigrou/pwet.fr (fr) for man dpkg-divert (Administration système) - remplacer la version d'un fichier contenu dans un paquet (fr).
• Thanks to Foaa (en) for PHP, apache and fastcgi – a comprehensive overview (en).
• Thanks to DerfK for its answer to I/O Error with PHP5-FPM, ptrace(PEEKDATA) failed (en).