PHP-FPM Domain Pools | cPanel & WHM Documentation

Overview

This document explains the process by which the system establishes a domain pool using PHP-FPM.

How System Creates Pools

A PHP-FPM domain pool is created when the configuration file located at /var/cpanel/userdata/[user]/[domain].php_fpm.yaml is present within the domain. This file is required to contain the following structure:

You can specify any desired pool values within this file.

• The --- line must be included directly above the pool values.
• The _is_present value is optional; however, it must be included if no other values are defined in the file.

Create a Pool

To initiate the creation of a PHP-FPM pool, execute the Cpanel::PHPFPM::rebuild_files() function.

The system proceeds through the following steps:

• The system scans for /var/cpanel/ApachePHPFPM/system.yaml and /var/cpanel/ApachePHPFPM/system_pool_defaults.yaml files, subsequently generating a system configuration for each installed PHP version.
• The system then searches for the domain's corresponding .yaml configuration files.
• For each domain.yaml file, the system generates a corresponding line in the /opt/cpanel/[ea_php_version]/root/etc/php-fpm.d/[domain].conf file.
• To effectively route requests to the php_fpm daemon via Apache, the rebuild_files() script modifies the httpd.conf file to appear as demonstrated in the following example:

1
2
3
4
5

# 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

The FPM socket is established by the system in the /opt/cpanel/phpversion/root/usr/var/run/php-fpm/obscure_domain.sock directory. Here, phpversion denotes the specific PHP version, and obscure_domain is a hashed representation of the domain. An example of a hashed version is provided below:

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

Once the pool and system configurations are correctly established in their designated locations, the system proceeds to restart the pools. The restart method employed by the system varies depending on whether it operates as a systemd or an init.d system. Following this, the system prunes any PHP version pools that do not contain associated domains.

Jail Shell

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

• The /var/cpanel/feature_toggles/apachefpmjail file is present.
• The WHM account is configured with either jailshell or noshell settings.
• The Experimental: Jail Apache Virtual Hosts using mod_ruid2 and cPanel® jailshell setting has been enabled within the Security section of WHM’s Tweak Settings interface (accessible via WHM » Home » Server Configuration » Tweak Settings).

Additional Resources

• MultiPHP INI Editor for WHM
• MultiPHP Manager for cPanel
• MultiPHP Manager for WHM
• MultiPHP Manager for WHM — System Settings
• The php_fpm_config Script
• The cPanel Glossary