PHP-FPM and Its Implementation in EasyApache 4

PHP FastCGI Process Manager (PHP-FPM)

Last modified: November 11, 2022

Overview

PHP-FPM is an advanced FastCGI daemon for PHP that allows websites to handle high traffic loads efficiently. It uses worker pools to process PHP requests and performs significantly faster than traditional CGI-based handlers such as SUPHP. PHP-FPM also prevents Apache from consuming excessive memory by separating PHP execution from Apache processes.

Warning: Only enable Apache PHP-FPM if your server has at least 2 GB of RAM or at least 30 MB of RAM per domain. Enabling PHP-FPM on a low-memory server may cause severe performance issues.

LiteSpeed Compatibility

LiteSpeed Web Server uses the lsphp binary and does not use the system PHP-FPM implementation managed through WHM’s MultiPHP Manager.

Monitoring PHP-FPM

To monitor PHP-FPM activity, enable the Monitor checkbox for the PHP-FPM service in:

WHM » Home » Service Configuration » Service Manager

---

PHP-FPM with EasyApache 4

PrivateTmp Behavior

On supported operating systems, EasyApache 4 uses the PrivateTmp option with PHP-FPM to improve security. This creates isolated temporary directories under /tmp for each PHP-FPM version.

Warning: Removing these PrivateTmp directories manually or automatically will cause errors in PHP-FPM applications. If you must remove them, restart PHP-FPM afterward:

/usr/local/cpanel/scripts/restartsrv_apache_php_fpm --hard

---

PHP-FPM Code and Filesystem Layout for EasyApache 4

Last modified: July 13, 2022

Overview

This section explains how PHP-FPM is implemented in EasyApache 4, including the filesystem layout, configuration structure, and how PHP-FPM pools are generated for each domain.

PHP-FPM allows hosts to allocate specific resources to each domain using worker pools. It is significantly faster than CGI-based handlers and avoids memory overload caused by Apache PHP handlers such as ruid2+php-dso.

PHP-FPM Implementation

The Cpanel::PHPFPM module provides EasyApache support for PHP-FPM. It generates configuration files that create fully functional PHP-FPM pools for each domain.

The system uses two main configuration files:

/var/cpanel/ApachePHPFPM/system.yaml
/var/cpanel/ApachePHPFPM/system_pool_defaults.yaml

Creating Required Files

You must manually create these files:

mkdir -p /var/cpanel/ApachePHPFPM/
touch /var/cpanel/ApachePHPFPM/system.yaml
touch /var/cpanel/ApachePHPFPM/system_pool_defaults.yaml

File Contents

These files should only contain values that differ from the built‑in defaults. The system does not require these files to run PHP-FPM, but they allow customization.

Example system.yaml:

---
daemonize: yes

Important Naming Rules

Replace invalid characters such as .[]() with underscores _. Examples:

Old Name	New Name
syslog.facility	syslog_facility
php_admin_value[disable_functions]	php_admin_value_disable_functions

Note: If you prepend PHP settings with disable_functions or disable_classes, PHP-FPM will append these values to existing php.ini settings in the user’s .htaccess file.

---

Filesystem Configuration Files

PHP-FPM configuration files generated by the YAML templates are stored here:

/opt/cpanel/ea-php80/root/etc/php-fpm.conf
/opt/cpanel/ea-php80/root/etc/php-fpm.d/[domain].conf

Do not edit these files manually. They are regenerated automatically for each PHP version.

If your server uses PHP 7.3 or 7.4, replace ea-php80 with ea-php73 or ea-php74.

---

Required and Optional YAML Files

Required per-domain file:

/var/cpanel/userdata/[user]/[domain].php-fpm.yaml

Optional system-level files:

• /var/cpanel/ApachePHPFPM/system.yaml
• /var/cpanel/ApachePHPFPM/system_pool_defaults.yaml

Note: If you edit a domain’s pool in MultiPHP Manager, system defaults will no longer apply to that domain.

---

Restoring PHP on Your System

Warning: Never remove ea-php packages manually. Doing so may break websites or cause Apache to fail.

To restore PHP versions safely:

ea_install_profile --install /etc/cpanel/ea4/profiles/cpanel/default.json
/usr/local/cpanel/scripts/restartsrv_apache_php_fpm

If these commands fail, contact your system administrator.

Conclusion

PHP-FPM is a powerful and efficient PHP handler that significantly improves performance for multi-user hosting environments. Understanding its configuration structure, filesystem layout, and implementation in EasyApache 4 ensures stable and optimized PHP performance across your server.

PHP-FPM Domain Pools

Last modified: January 18, 2021

Overview

This document explains how cPanel & WHM creates a PHP-FPM domain pool and how the system generates the necessary configuration files.

How the System Creates Pools

The system creates a PHP-FPM pool when the following file exists:

/var/cpanel/userdata/[user]/[domain].php_fpm.yaml

This file must contain at least:

---
_is_present: 1

You may add any additional pool configuration values to this file.

Important:

• The --- line is required.
• The _is_present value is optional unless no other values are defined.
• This file should only contain differences from the built‑in defaults.

Warning: Editing YAML files manually requires extreme caution. Incorrect syntax will cause services to fail. Always back up your system before editing YAML files.

---

Create a Pool

To create a PHP-FPM pool, run the following function:

Cpanel::PHPFPM::rebuild_files()

You may also use the script:

/scripts/php_fpm_config --rebuild

What the System Does

1. The system scans for system.yaml and system_pool_defaults.yaml and generates system-level PHP-FPM configurations for each PHP version.
2. The system searches for domain-level YAML files.
3. For each domain YAML file, the system generates a corresponding configuration file:

/opt/cpanel/[ea_php_version]/root/etc/php-fpm.d/[domain].conf

Apache is then updated to route PHP requests to PHP-FPM using a handler similar to:

# php -- BEGIN cPanel-generated handler, do not edit
<FilesMatch ".(phtml|php[0-9]*)$">
    SetHandler "proxy:unix:/home/cptest3/cptest3_tld.php_fpm.sock|fcgi://cptest3.tld/"
</FilesMatch>
# php -- END cPanel-generated handler, do not edit

Note: Any existing .conf files without a matching domain YAML file are removed.

Socket Creation

The system creates a PHP-FPM socket in:

/opt/cpanel/phpversion/root/usr/var/run/php-fpm/obscure_domain.sock

Example:

/opt/cpanel/ea-php56/root/usr/var/run/php-fpm/4cfb2f15c04ae8a6a980ad6b78a834e7c8661958.sock

Once all configurations are in place, the system restarts the pools using either systemd or init.d, depending on the OS. Pools for PHP versions without domains are removed.

---

Jail Shell Integration

When a PHP-FPM domain pool is created, the system automatically binds it to the virtfs mount if all of the following conditions are met:

• The file /var/cpanel/feature_toggles/apachefpmjail exists.
• The WHM account uses jailshell or noshell.
• The following setting is enabled in WHM Tweak Settings:

WHM » Home » Server Configuration » Tweak Settings » Experimental: Jail Apache Virtual Hosts using mod_ruid2 and cPanel jailshell

Conclusion

PHP-FPM domain pools allow each domain to run PHP efficiently with its own dedicated configuration. Understanding how pools are created, how YAML files work, and how Apache integrates with PHP-FPM ensures stable and optimized PHP performance across your server.