Child pages
  • PHP-FPM Code and FileSystem Layout for EasyApache 4
Skip to end of metadata
Go to start of metadata

This documentation is for cPanel & WHM version 66.  The "RELEASE" version of our documentation can be found in the Version 64 Documentation space.

Overview

This document explains the PHP-FPM code, its filesystem layout, how the system implements PHP-FPM, and how to restore your PHP to your system.

What does PHP-FPM do?

PHP FastCGI Process Manager (PHP-FPM) is an alternative FastCGI daemon for PHP that allows a website to handle strenuous loads. It also allows for a host to set specific amounts of resources to process a domain's requests. PHP-FPM maintains "pools" (workers available to respond to PHP requests) to accomplish this. These "pools" of workers allow the website to handle more requests than it normally could.

PHP-FPM is faster than traditional CGI-based methods, such as SUPHP, for multi-user PHP environments. It does not overload a system's memory with PHP from Apache processes like ruid2+php-dso does. This method is useful when a user receives extra traffic that requires resources to process it. For example, your website may receive a spike in traffic after a TV show features it or is linked from a popular website.

You can examine your server, locate the source of the extra traffic, and then enable PHP-FPM on that site via the pool manager. PHP-FPM does this through a service to serve PHP requests that Apache routes traffic to. PHP-FPM only executes PHP requests, which enables it to service content quicker than other methods.

How does cPanel implement PHP-FPM?

The Cpanel::PHPFPM (Cpanel/PHPFPM.pm) module is the basis of EasyApache support with PHP-FPM. The module's built-in defaults generate configuration files that provide fully functional PHP-FPM pools for a domain.

The system uses the following configuration files:

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

The system does not require the presence of these files to run since the built-in defaults enable the PHP-FPM to run sufficiently. Within these files you include different directives from the built-in values. 

Note:

Only include the differences in directives within these files.

The following shows an example of the system.yaml file:

---
daemonize: yes

This only uses a different value than the built-in default for the daemonize setting. The system-pool-defaults.yaml file is similar but applies to each pool that you create. We create one pool for each domain in the system. Some fields use unacceptable characters such as ".[]()" for internal reasons but will require you to amend or scrub them. If you find any of these characters, substitute them with an underscore.

For example:

Old NameNew Name
syslog.facilitysyslog_facility
php_admin_value[disable_functions]php_admin_value_disable_functions

The filesystem configuration files

The system stores the configuration files that control PHP-FPM in the following files:

FileDescription
/opt/cpanel/ea-php54/root/etc/php-fpm.conf This file contains the system configurations of PHP-FPM.
/opt/cpanel/ea-php54/root/etc/php-fpm.d/[domain].conf This file changes your domain to the domain setting of the website that you use. For example, the cptest1.tld.conf domain.

The .yaml files within the /var/cpanel directories generate these two files.

Notes:

  • Do not edit these configuration files manually.
  • The system repeats these configuration files for each version that you select.
  • The /opt/cpanel/ea-php54/root/etc/php-fpm.d/[domain].conf file shows ea-php54 or php54 as its version.
  • You must change ea-php54 to the version your system currently runs on. For example, if your system runs on PHP version 5.5 or 5.6, change ea-php54 to ea-php55 or ea-php56.

Required files

Use the following required files only if you wish to run PHP-FPM:

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

This file controls a specific domain's pool.

First, it uses the built-in default values, then the system_pool_defaults values, and lastly, generates the [domain].conf file.

Optional files

Use the following optional files only if you wish to to change the default parameters:

FileDescription
/var/cpanel/ApachePHPFPM/system.yaml

This file contains system level settings.

The system also uses this file to generate the /opt/cpanel/ea-php5?/root/etc/php-fpm.conf file, where the ? indicates that the system uses this file to generate all of the PHP versions of the php-fpm.conf file.

/var/cpanel/ApachePHPFPM/system_pool_defaults.yaml

The systems uses this file to generate each domain's pool.

For example, the /opt/cpanel/ea-php5?/root/etc/php-fpm.d/[domain].conf domain.

Note:

All domain pools use these defaults unless a .yaml file overrides them.

Restore PHP to your system

cPanel & WHM cannot clean up configurations or other related files when you manually remove RPMs. If you manually remove RPMs, you could remove dependencies in which your hosted websites require. 

Warning:

We do not recommend that you perform yum remove operations with any ea-php RPMs. If you remove PHP from your system while any of your hosted websites still us it, those websites will display errors. In addition, Apache could fail to display the website entirely. Before you perform a yum remove operation, confirm that none of your hosted websites use the PHP version that you wish to remove with WHM's MultiPHP Manager interface (Home >> Software >> MultiPHP Manager).

If you use yum or the EasyApache 4 interface (Home >> Software >> EasyApache 4) to remove FPM packages, the system will revert you back to the current system default.

To restore PHP versions to your system, run the following two commands:

ea_install_profile --install /etc/cpanel/ea4/profiles/cpanel/default.json
/scripts/restartsrv apache_php_fpm

Note:

We recommend that you use the above commands to restore Apache and PHP to a functional state. If the above commands fail, you must consult with your server's administrator for further assistance.

Additional documentation