Overview
Warnings:
- This document is only valid for cPanel & WHM version 58 and earlier. We deprecated this configuration process in cPanel & WHM version 60.
- cPanel Technical Support does not provide assistance with the instructions in this article.
- To configure PHP-FPM for cPanel & WHM version 60 or later, read our MultiPHP Manager for WHM documentation.
The FastCGI Process Manager (PHP-FPM) implementation of FastCGI provides process management, emergency restarts, and IP address restriction. You must perform extra steps to use this handler with user pools on a shared server.
For more information about how to install FastCGI and PHP-FPM, read the following documentation:
Set up pools per user
Important:
You can only configure one PHP-FPM pool per user.
Notes:
- These instructions assume that your server runs EasyApache 4.
- In the examples below, the following are true:
ea-php56
andea-php70
represent the versions of PHP to use.<user>
represents a user on the system.example.com
represents the domain's base directory.<useraccount>
represents the user's account.<vhost>
represents the name of the virtual host.
To set up user pools for an EasyApache 4 server that runs PHP version 5.6, perform the following steps:
Run the following command as the
root
user to install FCGI and PHP-FPM:yum install ea-apache24-mod_proxy_fcgi ea-php56-php-fpm
Note:
To change the PHP handler for each version to use CGI, run the following script:
/usr/local/cpanel/bin/rebuild_phpconf --default=ea-php56 --ea-php55=cgi --ea-php56=cgi --ea-php70=cgi
Run the following command to create PHP-FPM's
run
directory in yourhome
directory:mkdir -p /home/<user>/run/ chown <user>. /home/<user>/run/
Run the following commands to copy and rename your PHP version's
www.conf.example
file:cd /opt/cpanel/ea-php56/root/etc/php-fpm.d/ cp www.conf.example <user>.conf
Edit your
<user>.conf
file to include the following changes:On line 2, change the name of the pool. We recommend that you use the username of the account.
; Start a new pool named 'www'. [user]
On line 12, change the listening socket path to the directory that you created in step 2.
listen = /home/<user>/run/php56-fpm.sock
Uncomment lines 31 and 32 and change the following parameters' values to allow the
init
script to set the permissions for the Unix socket:- The
listen.owner
parameter to the<user>
value.
The
listen.group
parameter to thenobody
value.listen.owner = <user> listen.group = nobody
- The
On line 35, change the
user
andgroup
targets to the name of the user whom you wish to own the process.; Unix user/group of processes ; Note: The user is mandatory. If the group is not set, the default user's group ; will be used. ; RPM: apache Choosed to be able to access some dir as httpd user = <user> ; RPM: Keep a group allowed to write in log dir. group = <group>
On line 219, change the error log directory.
php_admin_value[error_log] = /home/<user>/logs/ea-php56-php-fpm.log
On line 225, change the PHP session directory.
php_value[session.save_path] = /home/<user>/session
Create the
/home/<user>/session
directory, if it does not already exist, and update the<user>
value's permissions. To do this, run the following commands:mkdir /home/<user>/session chown <user>. /home/<user>/session
Run the following commands to restart the PHP FPM service:
CentOS 6:/etc/init.d/ea-php56-php-fpm stop /etc/init.d/ea-php56-php-fpm start
CentOS 7:
systemctl stop ea-php56-php-fpm.service systemctl start ea-php56-php-fpm.service
Create and edit the user's Apache include directory and file.
Run the following commands to create the Apache include directories:
mkdir -p /etc/apache2/conf.d/userdata/std/2_4/<useraccount>/<vhost> mkdir -p /etc/apache2/conf.d/userdata/ssl/2_4/<useraccount>/<vhost>
Edit the
/etc/apache2/conf.d/userdata/std/2_4/<useraccount>/<vhost>/fpm.conf
file to include the following lines:<IfModule proxy_fcgi_module> ProxyPassMatch "^/(.*\.php(/.*)?)$" "unix:/home/<user>/run/php56-fpm.sock|fcgi://localhost/home/<user>/public_html/" DirectoryIndex index.php </IfModule>
Run the following command to copy the
fpm.conf
file from thestd
directory tree to thessl
directory tree:cp /etc/apache2/conf.d/userdata/std/2_4/<useraccount>/<vhost>/fpm.conf /etc/apache2/conf.d/userdata/ssl/2_4/<useraccount>/<vhost>/fpm.conf
Run the
/scripts/rebuildhttpdconf
script.Run the
/scripts/restartsrv_httpd
script.
To set up user pools for an EasyApache 4 server that runs PHP version 7.0, perform the following steps:
Run the following command as the
root
user to install FCGI and PHP-FPM:yum install ea-apache24-mod_proxy_fcgi ea-php70-php-fpm
Note:
To change the PHP handler for each version to use CGI, run the following script:
/usr/local/cpanel/bin/rebuild_phpconf --default=ea-php56 --ea-php54=cgi --ea-php55=cgi --ea-php56=cgi --ea-php70=cgi
Run the following command to create PHP-FPM's
run
directory in yourhome
directory:mkdir -p /home/<user>/run/ chown <user>. /home/<user>/run/
Run the following commands to copy and rename your PHP version's
www.conf.example
file:cd /opt/cpanel/ea-php70/root/etc/php-fpm.d/ cp www.conf.example <user>.conf
Edit your
<user>.conf
file to include the following changes:On line 4, change the name of the pool. We recommend that you use the username of the account.
; Start a new pool named 'www'. [user]
On lines 24 and 26, change the
user
andgroup
targets to the name of the user that you want to own the process.; Unix user/group of processes ; Note: The user is mandatory. If the group is not set, the default user's group ; will be used. ; RPM: apache Choosed to be able to access some dir as httpd user = <user> ; RPM: Keep a group allowed to write in log dir. group = <user>
On line 38, change the listening socket path to the directory that you created in step 2.
listen = /home/<user>/run/php70-fpm.sock
Uncomment lines 48 and 49 and change the following parameters' values to allow the
init
script to set the permissions for the Unix socket:- The
listen.owner
parameter to the<user>
value.
The
listen.group
parameter to thenobody
value.listen.owner = <user> listen.group = nobody
- The
On line 52, change the
user
andgroup
targets to the name of the user whom you wish to own the process.On line 413, change the error log directory:
php_admin_value[error_log] = /home/<user>/logs/ea-php70-php-fpm.log
On line 419, change the PHP session directory:
php_value[session.save_path] = /home/<user>/session
Create the
/home/<user>/session
directory, if it does not already exist, and update the<user>
value's permissions. To do this, run the following commands:mkdir /home/<user>/session chown <user>. /home/<user>/session
Run the following commands to stop and restart the PHP FPM service:
Centos 6:/etc/init.d/ea-php70-php-fpm stop /etc/init.d/ea-php70-php-fpm start
CentOS 7:
systemctl stop ea-php70-php-fpm.service systemctl start ea-php70-php-fpm.service
Create and edit the user's Apache include directory and file.
Run the following commands to create the Apache include directories:
mkdir -p /etc/apache2/conf.d/userdata/std/2_4/<useraccount>/<vhost> mkdir -p /etc/apache2/conf.d/userdata/ssl/2_4/<useraccount>/<vhost>
Edit the
/etc/apache2/conf.d/userdata/std/2_4/<useraccount>/<vhost>/fpm.conf
file to include the following lines:<IfModule proxy_fcgi_module> ProxyPassMatch "^/(.*\.php(/.*)?)$" "unix:/home/<user>/run/php70-fpm.sock|fcgi://localhost/home/<user>/public_html/ DirectoryIndex index.php </IfModule>
Run the following command to copy the
fpm.conf
file from thestd
directory tree to thessl
directory tree:cp /etc/apache2/conf.d/userdata/std/2_4/<useraccount>/<vhost>/fpm.conf /etc/apache2/conf.d/userdata/ssl/2_4/<useraccount>/<vhost>/fpm.conf
Run the
/scripts/rebuildhttpdconf
script.Run the
/scripts/restartsrv_httpd
script.
How to disable user pools
To disable user pools, perform the following steps:
Remove the
fpm.conf
file from the user's include directory with the following command:rm /etc/apache2/conf.d/userdata/std/2_4/$user/$domain/fpm.conf
Note:
You must remove the directory before
rebuild httpd
will disable the include line.If the user's system does not contain any other includes, remove the user's include directory with the following command:
rmdir /etc/apache2/conf.d/userdata/std/2_4/$user
Remove the FPM user configuration file with the following command:
rm /opt/cpanel/ea-phpxx/root/etc/php-fpm.d/$user.conf
Rebuild the
httpd
configuration with the following command:/scripts/rebuildhttpdconf
Stop and start the FPM with the commands appropriate for your version of OS:
CentOS 5 & 6/etc/init.d/ea-php56-php-fpm stop /etc/init.d/ea-php56-php-fpm start
CentOS 7systemctl stop ea-php56-php-fpm.service systemctl start ea-php56-php-fpm.service
Restart Apache with the following command:
/scripts/restartsrv httpd
Additional documentation