Install PHP-FPM on Debian

PHP-FPM is an greatly enhanced FastCGI mechanism for PHP. It greatly raise the performances of PHP sites. This howto help you to setup this software on Debian.

This howto is tested on:

• Debian 10.0 Buster

Requirements

This howto requires:

• the Debian “contrib” repository, as described by Setup the contrib and non-free Debian repositories.
• Apache 2, as described by Install Apache 2 on Debian.

Installation

Detect if sudo is available (“command” is used if not):

cmdProxy='command'
command type -f 'sudo' &>'/dev/null' && cmdProxy='sudo'

FPM server setup

Install the software:

${cmdProxy} apt-get install 'php' 'php-fpm' 'php-cli'

Detect the version of the installed PHP environment:

phpVersion="$(readlink -f /usr/bin/php | cut -c 13-)"

Detect the path to PHP configuration files:

[ -d '/etc/php5' ] && phpConfPath='/etc/php5'
[ -d "/etc/php/${phpVersion}" ] && phpConfPath="/etc/php/${phpVersion}"

Backup (divert) the provided default configuration:

[ -e "${phpConfPath}/fpm/pool.d/www.conf" ] \
  && ${cmdProxy} dpkg-divert --rename \
    --divert "${phpConfPath}/fpm/pool.d/www.conf.dist" \
    "${phpConfPath}/fpm/pool.d/www.conf"

Create a new configuration file from template:

[ -e "${phpConfPath}/fpm/pool.d/www.conf" ] \
    || ${cmdProxy} cp "${phpConfPath}/fpm/pool.d/www.conf.dist" \
                      "${phpConfPath}/fpm/pool.d/www.conf"

Enable the FPM server status monitoring features:

[ -e "${phpConfPath}/fpm/pool.d/www.conf" ] \
    && ${cmdProxy} sed -i \
      -e 's|^;*pm.status_path.*|pm.status_path = /php-fpm-status|' \
      -e 's|^;*ping.path.*|ping.path = /php-fpm-ping|' \
    "${phpConfPath}/fpm/pool.d/www.conf";

Reload PHP and the FPM server configuration:

${cmdProxy} systemctl 'restart' "php${phpVersion}-fpm"

A FPM server requires to be restarted by the command above to reload PHP global settings after change. php-tools provide a reload option that restart the FPM server present on your system.

HTTP server configuration

Apache 2

Enable Apache 2 FPM configuration:

if [[ -e "/etc/apache2/conf-available/php${phpVersion}-fpm.conf" ]]; then
  ${cmdProxy} a2enmod 'proxy_fcgi' 'setenvif'
  ${cmdProxy} a2enconf "php${phpVersion}-fpm"
fi

Reload Apache 2 configuration:

  ${cmdProxy} systemctl reload 'apache2'

NGINX

NGINX need the PHP configuration to be added to each “server” configuration. The needed configuration is:

  # pass PHP scripts to FastCGI server
  #
  location ~ \.php$ {
    include "snippets/fastcgi-php.conf";

    # With php-fpm (or other unix sockets):
    fastcgi_pass "unix:/run/php/php7.3-fpm.sock";
  }

Make sure to adjust the fastcgi_pass setting to fit your system. It must correspond to the ‘listen’ setting in the FPM pool configuration file.

nginx-tools, script easing NGINX server administration, automatically create the server configuration with the needed configuration lines.

Next steps

This howto recommends :

• Install php-tools, command-line tool easing PHP configuration.
• Improve PHP initial configuration on Debian.
• Log PHP messages with Syslog.
• Install PHP extension OPCache on Debian.
• Install PHP extension APCu on Debian.

Troubleshooting

.htaccess: Invalid command ‘php_flag’

If the following error appear in Apache 2 error log:

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

One of the hosted site use “php_flag” rule in a .htaccess file. This rule is provided by PHP Apache 2 module (aka. mod_php), and is not supported by PHP-FPM.

Fix the error by commenting the “php_flag” lines in the .htaccess file, and adding the ini rule to PHP global configuration with php-tools.

FastCGI: comm with server aborted : idle timeout

If the following error appear in Apache 2 error log:

FastCGI: comm with server “/run/php/php7.3-fpm.sock” aborted: idle timeout (610 sec)

This error appear when a PHP page run for more than 610 seconds. It can be due ,for example, to a web application upgrade process.

Fix the error by raising the -idle-timeout option in “/etc/apache2/mods-available/php*-fpm.conf”:

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

And disable the request_terminate_timeout option in “/etc/php*/fpm/pool.d/www.conf”.

The two values must be greater than the PHP max_execution_time option value.

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

If the following error appear in PHP-FPM log (“/var/log/php*-fpm.log”):

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

This error appears when the FPM “request_slowlog_timeout” option is enabled. It signals a failure to create the error trace. This can trigger a server failure 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.

Fix the problem by disabling the “request_slowlog_timeout” option in the FPM server configuration:

[ -e "${phpConfPath}/fpm/pool.d/www.conf" ] \
    && ${cmdProxy} sed -i \
      -e 's/^request_slowlog_timeout/;request_slowlog_timeout/' \
    "${phpConfPath}/fpm/pool.d/www.conf";

Reload the PHP-FPM configuration:

${cmdProxy} systemctl 'restart' "php${phpVersion}-fpm"

Thanks

• Thanks to PHP-FPM (en) developers.
• Thanks to Evolix (fr) for Howto Nginx + PHP-FPM (fr).
• Thanks to HowtoForge (en) for Using PHP5-FPM With Apache2 On Ubuntu 11.10 (en).
• Thanks to Damien Pobel for man dpkg-divert (Administration système) – remplacer la version d’un fichier contenu dans un paquet (fr).
• Thanks to DerfK for its answer to I/O Error with PHP5-FPM, ptrace(PEEKDATA) failed (en).