Skip to main content

PHP-FPM Configuration Guide

Brandon Langley
Updated

PHP-FPM Configuration Guide

Infrastructure: PHP 8.x FastCGI Process Manager (PHP-FPM)
Platform: RHEL/Rocky 8-10 | Ubuntu/Debian 22/24

Overview

PHP-FPM (FastCGI Process Manager) is the runtime that powers the Diskover Web UI. It sits between Nginx and the PHP application — Nginx hands off incoming requests to PHP-FPM via a Unix socket, and PHP-FPM executes the Diskover Web PHP code and returns the response.

Getting PHP-FPM configured correctly matters because misconfigured pool settings can lead to slow page loads, failed requests under load, or permission errors that prevent the Web UI from functioning entirely. This guide documents the PHP-FPM configuration required by Diskover, so you can install, verify, and troubleshoot PHP-FPM on your web host.

When to use this guide:

  • Installing and configuring PHP-FPM for the Diskover Web UI

  • Verifying that PHP-FPM is configured correctly after a deployment

  • Troubleshooting Web UI performance issues related to PHP-FPM

  • Understanding the required PHP-FPM settings and why they matter

Understanding PHP-FPM

PHP-FPM manages a pool of PHP worker processes that handle incoming web requests. Instead of spawning a new PHP process for every request (like traditional CGI), PHP-FPM keeps a pool of long-lived processes ready to go, which is significantly faster.

Key Concepts

Process Manager Modes:

Mode

Behavior

Use Case

static

Fixed number of worker processes at all times

Predictable, high-traffic environments

dynamic

Scales workers up and down based on demand

Diskover default — good balance of performance and resource usage

ondemand

Spawns workers only when requests arrive

Low-traffic environments where memory conservation matters

Diskover uses dynamic process management, which means PHP-FPM starts with a baseline number of workers and creates more as traffic increases, up to a configured maximum.

Unix Sockets vs TCP:

Diskover configures PHP-FPM to communicate with Nginx over a Unix socket rather than a TCP port. Unix sockets are faster for same-host communication because they skip the network stack entirely. The socket file acts as the communication channel between Nginx and PHP-FPM.

User/Group Ownership:

PHP-FPM worker processes and the Unix socket must run as and be owned by the same user that Nginx runs as. This ensures Nginx can read from and write to the socket.

The user differs by platform: nginx on RHEL/Rocky, www-data on Ubuntu/Debian.

Architecture Considerations

PHP-FPM always runs on the web host alongside Nginx, PHP, and the Diskover Web UI. It is not deployed to worker or Elasticsearch hosts.

Sizing Guidelines:

Deployment Size

pm.max_children

Notes

Small (< 10 concurrent users)

50 (default)

Default settings are sufficient

Medium (10–50 concurrent users)

50–100

Monitor memory; each child uses ~30–50 MB

Large (50+ concurrent users)

100–200

Ensure the host has enough RAM to support the pool

A rough formula: pm.max_children = Available RAM for PHP / Average memory per PHP process. For Diskover Web, each PHP-FPM child process typically consumes 30–50 MB of memory.

Prerequisites

Requirement

Detail

OS

RHEL/Rocky 8-10, Ubuntu/Debian 22 or 24

Nginx

Must be installed and running on the same host

Diskover Web

Installed at /var/www/diskover-web/

Installation

Required PHP Packages

Diskover Web requires PHP 8.4 with the following extensions:

Package

RHEL/Rocky

Ubuntu/Debian

PHP core

php84

php8.4

Common

php84-php-common

php8.4-common

FPM

php84-php-fpm

php8.4-fpm

OPcache

php84-php-opcache

php8.4-opcache

CLI

php84-php-cli

php8.4-cli

GD (images)

php84-php-gd

php8.4-gd

MySQL

php84-php-mysqlnd

php8.4-mysqlnd

LDAP

php84-php-ldap

php8.4-ldap

ZIP

php84-php-pecl-zip

php8.4-zip

XML

php84-php-xml

php8.4-xml

Multibyte strings

php84-php-mbstring

php8.4-mbstring

JSON

php84-php-json

(built-in on 8.4)

SQLite

php84-php-sqlite3

php8.4-sqlite3

cURL

—

php8.4-curl

RHEL/Rocky 8/9

# Install the REMI repository
dnf install -y https://rpms.remirepo.net/enterprise/remi-release-$(rpm -E %rhel).rpm
# Install PHP 8.4 and extensions
dnf install -y php84 php84-php-common php84-php-fpm php84-php-opcache \
  php84-php-cli php84-php-gd php84-php-mysqlnd php84-php-ldap \
  php84-php-pecl-zip php84-php-xml php84-php-mbstring php84-php-json \
  php84-php-sqlite3

Ubuntu/Debian 22/24

# Add the Ondrej PHP PPA
add-apt-repository -y ppa:ondrej/php
apt update
# Install PHP 8.4 and extensions
apt install -y php8.4 php8.4-common php8.4-fpm php8.4-opcache php8.4-cli \
  php8.4-gd php8.4-mysqlnd php8.4-ldap php8.4-zip php8.4-xml \
  php8.4-mbstring php8.4-sqlite3 php8.4-curl

Configuration

Configuration File Locations

File

RHEL/Rocky

Ubuntu/Debian

PHP-FPM pool config (www.conf)

/etc/opt/remi/php84/php-fpm.d/www.conf

/etc/php/8.4/fpm/pool.d/www.conf

PHP configuration (php.ini)

Discovered via php84 -i | grep php.ini

/etc/php/8.4/fpm/php.ini

PHP-FPM main config

/etc/opt/remi/php84/php-fpm.conf

/etc/php/8.4/fpm/php-fpm.conf

Systemd service

/etc/systemd/system/php-fpm.service

/etc/systemd/system/php-fpm.service

PHP-FPM Pool Configuration (www.conf)

This is the most important configuration file. It controls how PHP-FPM manages worker processes and communicates with Nginx.

Process Manager Settings

These settings are identical on both platforms:

pm = dynamic
pm.max_children = 50
pm.start_servers = 5
pm.min_spare_servers = 5
pm.max_spare_servers = 35

Parameter

Value

Description

pm

dynamic

Process manager mode — scales workers based on demand

pm.max_children

50

Maximum number of simultaneous PHP-FPM worker processes

pm.start_servers

5

Number of worker processes created on startup

pm.min_spare_servers

5

Minimum number of idle workers to keep available

pm.max_spare_servers

35

Maximum number of idle workers before excess are terminated

Socket and Communication

RHEL/Rocky:

listen = /var/opt/remi/php84/run/php-fpm/www.sock
listen.owner = nginx
listen.group = nginx
listen.allowed_clients = 127.0.0.1

Ubuntu/Debian:

listen = /var/run/php/php-fpm.sock
listen.owner = www-data
listen.group = www-data
listen.allowed_clients = 127.0.0.1

The listen.owner and listen.group settings are critical — they must match the user that Nginx runs as. If these are wrong, Nginx will get "permission denied" errors when trying to connect to the PHP-FPM socket.

Note: On RHEL/Rocky, the default www.conf shipped by the REMI package sets listen.acl_users = apache. This line must be commented out for the listen.owner and listen.group settings to take effect.

Worker User/Group

RHEL/Rocky:

user = nginx
group = nginx

Ubuntu/Debian:

user = www-data
group = www-data

Logging

RHEL/Rocky:

slowlog = /var/opt/remi/php84/log/php-fpm/www-slow.log
php_admin_value[error_log] = /var/opt/remi/php84/log/php-fpm/www-error.log
php_admin_flag[log_errors] = on

Ubuntu/Debian:

php_admin_value[error_log] = /var/log/php8.4-fpm.log
php_admin_flag[log_errors] = on

Session and Cache Paths (RHEL/Rocky)

php_value[session.save_handler] = files
php_value[session.save_path]    = /var/opt/remi/php84/lib/php/session
php_value[soap.wsdl_cache_dir]  = /var/opt/remi/php84/lib/php/wsdlcache

PHP Configuration (php.ini)

Diskover requires a customized php.ini based on the PHP 8.4 production defaults. The key Diskover-specific settings are:

Parameter

Value

Default

Why

max_execution_time

86400

30

Diskover Web operations (large searches, exports) can run for extended periods. Set to 24 hours to prevent timeouts.

max_input_time

86400

60

Matches max_execution_time — allows long-running input processing.

memory_limit

128M

128M

Standard production default; sufficient for Diskover Web.

display_errors

Off

Off

Production setting — errors logged to file, not displayed to users.

log_errors

On

On

Ensures PHP errors are captured in log files for troubleshooting.

post_max_size

8M

8M

Standard production default.

upload_max_filesize

2M

2M

Standard production default.

Systemd Service File

Diskover uses a custom systemd unit file for PHP-FPM at /etc/systemd/system/php-fpm.service. This overrides any package-provided service file to ensure consistent behavior.

RHEL/Rocky:

[Unit]
Description=PHP FastCGI process manager
After=local-fs.target network.target nginx.service
[Service]
PIDFile=/opt/php/php-fpm.pid
ExecStartPre=-/usr/bin/rm -f /var/opt/remi/php84/run/php-fpm/www.sock
ExecStart=/opt/remi/php84/root/usr/sbin/php-fpm --fpm-config /etc/opt/remi/php84/php-fpm.conf --nodaemonize
Type=simple
[Install]
WantedBy=multi-user.target

Ubuntu/Debian:

[Unit]
Description=PHP FastCGI process manager
After=local-fs.target network.target nginx.service
[Service]
PIDFile=/run/php/php8.4-fpm.pid
ExecStartPre=-/usr/bin/rm -f /var/run/php/php8.4-fpm.sock
ExecStart=/usr/sbin/php-fpm8.4 --fpm-config /etc/php/8.4/fpm/php-fpm.conf --nodaemonize
Type=simple
[Install]
WantedBy=multi-user.target

Notable details:

  • The ExecStartPre line removes any stale socket file before starting, preventing "address already in use" errors after an unclean shutdown.

  • The After=nginx.service directive ensures PHP-FPM starts after Nginx, though Nginx can handle PHP-FPM being temporarily unavailable.

  • The --nodaemonize flag keeps PHP-FPM in the foreground so systemd can manage the process lifecycle.

Directory Ownership

Key directories must be owned by the web server user for PHP-FPM to function correctly:

RHEL/Rocky:

chown -R nginx:nginx /var/opt/remi/php84/lib/php
mkdir -p /var/run/php-fpm && chown nginx:nginx /var/run/php-fpm && chmod 755 /var/run/php-fpm

Ubuntu/Debian:

chown -R www-data:www-data /var/lib/php
mkdir -p /var/run/php-fpm && chown www-data:www-data /var/run/php-fpm && chmod 755 /var/run/php-fpm

Service Management

Action

Command

Start

systemctl start php-fpm

Stop

systemctl stop php-fpm

Restart

systemctl restart php-fpm

Reload (graceful)

systemctl reload php-fpm

Status

systemctl status php-fpm

Logs

journalctl -fu php-fpm

Enable on boot

systemctl enable php-fpm

Use reload instead of restart when changing pool configuration (www.conf) — it gracefully finishes in-flight requests before applying the new settings.

Monitoring & Maintenance

Health Check Commands

Check

Command

Expected Result

Service status

systemctl status php-fpm

active (running)

Socket exists

ls -la /var/opt/remi/php84/run/php-fpm/www.sock (RHEL) or ls -la /var/run/php/php-fpm.sock (Debian)

Socket file exists, owned by nginx/www-data

PHP version

php -v (Debian) or /opt/remi/php84/root/usr/bin/php -v (RHEL)

PHP 8.4.x

PHP modules

php -m (Debian) or /opt/remi/php84/root/usr/bin/php -m (RHEL)

Lists all required extensions

FPM process count

ps aux | grep php-fpm | grep -v grep | wc -l

At least 6 (1 master + 5 start_servers)

Log Locations

Log

RHEL/Rocky

Ubuntu/Debian

FPM error log

/var/opt/remi/php84/log/php-fpm/www-error.log

/var/log/php8.4-fpm.log

FPM slow log

/var/opt/remi/php84/log/php-fpm/www-slow.log

—

Systemd journal

journalctl -fu php-fpm

journalctl -fu php-fpm

Backup Procedures

Before upgrading PHP or modifying FPM configuration, back up:

# RHEL/Rocky
cp /etc/opt/remi/php84/php-fpm.d/www.conf /root/www.conf.bak.$(date +%Y%m%d)
cp /etc/systemd/system/php-fpm.service /root/php-fpm.service.bak.$(date +%Y%m%d)
# Ubuntu/Debian
cp /etc/php/8.4/fpm/pool.d/www.conf /root/www.conf.bak.$(date +%Y%m%d)
cp /etc/systemd/system/php-fpm.service /root/php-fpm.service.bak.$(date +%Y%m%d)

Troubleshooting

Issue

Cause

Solution

Nginx returns 502 Bad Gateway

PHP-FPM is not running or socket does not exist

Verify systemctl status php-fpm shows active. Check that the socket file exists at the expected path.

Nginx returns 502 Bad Gateway (socket exists)

Socket ownership mismatch — Nginx cannot read the socket

Verify listen.owner and listen.group match the Nginx user (nginx on RHEL, www-data on Debian). On RHEL, ensure listen.acl_users = apache is commented out.

PHP-FPM fails to start with "address already in use"

Stale socket file from a previous unclean shutdown

Remove the socket file manually: rm -f /var/opt/remi/php84/run/php-fpm/www.sock (RHEL) or rm -f /var/run/php/php-fpm.sock (Debian), then start the service. The custom systemd service file should handle this automatically via ExecStartPre.

Diskover Web pages load slowly under load

Not enough PHP-FPM worker processes

Increase pm.max_children in www.conf. Monitor with ps aux | grep php-fpm to see if all children are busy.

"server reached max_children" in FPM log

All worker processes are occupied

Increase pm.max_children in www.conf and restart PHP-FPM. Ensure the host has enough RAM (each child ≈ 30–50 MB).

PHP errors not appearing in logs

log_errors is off or error log path is wrong

Verify php_admin_flag[log_errors] = on in www.conf and check that the error log directory exists and is writable.

Diskover Web request timeouts

max_execution_time too low

Verify php.ini has max_execution_time = 86400. The default PHP value of 30 seconds is too low for Diskover.

Support

Related articles

Comments

0 comments

Please sign in to leave a comment.

Powered by Zendesk