PHP-FPM User Pools

  1. Home
  2. Knowledge Base
  3. WHM & cPanel
  4. PHP-FPM User Pools


This document explains how the system creates a user pool with PHP-FPM.

How does the system create pools?

The system creates a pool when the /var/cpanel/userdata/[user]/[domain].php_fpm.yaml configuration file exists in the domain. This file must use the following lines at a minimum:

_is_present: 1

You may place any pool values that you wish within this file. The _is_present value is optional, but is required if you do not set any other values in the file.


This file only contains the differences of directives from the built-in default directives.


Create a pool

To create a pool, run the Cpanel::PHPFPM::rebuild_files() function.


You may also run the /scripts/php_fpm_config --rebuild script to create a pool.

The system will perform the following steps for you:

    • The system scans for the /var/cpanel/ApachePHPFPM/system.yaml and /var/cpanel/ApachePHPFPM/system_pool_defaults.yaml files and then generates a system configuration for each of the PHP versions.
    • The system searches for the domain’s yaml files.
    • The system generates a line in the /opt/cpanel/[ea_php_version]/root/etc/php-fpm.d/[domain].conf file for every domain.yaml file.
    • To direct the requests to the php_fpm daemon with Apache, the system modifies the httpd.conf file with the rebuild_files() script to resemble the following example:
      # 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/"
      # php -- END cPanel-generated handler, do not edit


      The system removes any existing conf files that do not contain a corresponding domain.yaml file.

The system creates the FPM socket in the /opt/cpanel/$phpversion/root/usr/var/run/php-fpm/${obscure_domain}.sock directory, where $phpversion represents the version of PHP, and $obscure_domain represents a hashed version of the domain. Your hashed version will resemble the following example:


When the pool and system configurations exist in their designated locations, the system restarts the pools. The method that the system uses to restart depends on whether it runs as a systemd or an init.d system. The system then shuts off any PHP version pools that do not hold domains with that version.

Jail shell

When you create a PHP-FPM user pool, the system automatically binds them to the virtfs mount when the following conditions exist:

  • The /var/cpanel/feature_toggles/apachefpmjail file exists.
  • The WHM account uses either the jailshell or the noshell settings.
  • You enabled the Experimental: Jail Apache Virtual Hosts using mod_ruid2 and cPanel® jailshell setting in the  Security section of WHM’s Tweak Settings interface (Home >> Server Configuration >> Tweak Settings).
Facebook Comments

Was this article helpful?

Related Articles