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


This howto requires:


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

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" \

Create a new configuration file from template:

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

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|' \

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"

Reload Apache 2 configuration:

  ${cmdProxy} systemctl reload 'apache2'


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 :


.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/' \

Reload the PHP-FPM configuration:

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


Categories: PHP


Leave a Reply

Avatar placeholder

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.