title: PHP-FPM Domain Pools
created at: Mon Oct 28 2024 05:55:20 GMT+0000 (Coordinated Universal Time)
updated at: Sat Feb 08 2025 14:22:50 GMT+0000 (Coordinated Universal Time)
---
# PHP-FPM Domain Pools
# Overview
This document explains how the system creates a domain 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** include the following lines:
```bash
---
_is_present: 1
```
You may place any desired pool values in this file.
* You **must** include the `---` line above the pool values in this file.
* The `_is_present` value is optional, but you **must** include it if you do not set any other values in the file.
!! Warning
!! Exercise **extreme** caution when you manually edit `.yaml` files. Incorrect syntax in these files will cause services to fail. We **strongly** recommend that you create a backup of your system before you manually edit `.yaml` files.
!! Note
!! 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.
!! Note
!! You may also run the `/scripts/php_fpm_config --rebuild` script to create a pool.
The system will perform the following steps:
* 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:
```bash
# php -- BEGIN cPanel-generated handler, do not edit
<FilesMatch ".(phtml|php[0-9]*)
quot;>
SetHandler "proxy:unix:/home/cptest3/cptest3_tld.php_fpm.sock|fcgi://cptest3.tld/"
</FilesMatch>
# php -- END cPanel-generated handler, do not edit
```
!! Note
!! 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:
```javascript
/opt/cpanel/ea-php56/root/usr/var/run/php-fpm/4cfb2f15c04ae8a6a980ad6b78a834e7c8661958.sock
```
When the pool and system configurations exist in their designated locations, the system restarts the pools. The method that the system uses to restart them depends on whether it runs as a `systemd` or an `init.d` system. The system then removes any PHP version pools that do **not** hold domains with that version.
# Jail shell
When you create a PHP-FPM domain pool, if the following conditions exist, the system automatically binds them to the `virtfs` mount:
* The `/var/cpanel/feature_toggles/apachefpmjail` file exists.
* The WHM account uses either the `jailshell` or `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* ](https://docs.cpanel.net/whm/server-configuration/tweak-settings/) interface (*WHM » Home » Server Configuration » Tweak Settings*).