cPanel Knowledge Base
Page tree
Skip to end of metadata
Go to start of metadata

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 and ea-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 PHP-FPM for a shared server, select the tab that corresponds to your PHP version:

To set up user pools for an EasyApache 4 server that runs PHP version 5.6, perform the following steps:

  1. 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

  2. Run the following command to create PHP-FPM's run directory in your home directory:

    mkdir -p /home/<user>/run/
chown <user>. /home/<user>/run/

  3. 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

  4. Edit your <user>.conf file to include the following changes:

    1. 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]

    2. On line 12, change the listening socket path to the directory that you created in step 2.

      listen = /home/<user>/run/php56-fpm.sock

    3. 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 the nobody value.

        listen.owner = <user>
listen.group = nobody

    4. On line 35, change the user and group 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>

    5. On line 219, change the error log directory.

      php_admin_value[error_log] = /home/<user>/logs/ea-php56-php-fpm.log

    6. On line 225, change the PHP session directory.

      php_value[session.save_path] = /home/<user>/session

  5. 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

  6. 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

  7. Create and edit the user's Apache include directory and file.

    1. 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>

    2. 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>

  8. Run the following command to copy the fpm.conf file from the std directory tree to the ssl 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

  9. Run the /scripts/rebuildhttpdconf script.

  10. 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:

  1. 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

  2. Run the following command to create PHP-FPM's run directory in your home directory:

    mkdir -p /home/<user>/run/
chown <user>. /home/<user>/run/

  3. 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

  4. Edit your <user>.conf file to include the following changes:

    1. 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]

    2. On lines 24 and 26, change the  user  and  group  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>

    3. On line 38, change the listening socket path to the directory that you created in step 2.

      listen = /home/<user>/run/php70-fpm.sock

    4. 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 the nobody value.

        listen.owner = <user>
listen.group = nobody

    5. On line 52, change the user and group targets to the name of the user whom you wish to own the process.

    6. On line 413, change the error log directory:

      php_admin_value[error_log] = /home/<user>/logs/ea-php70-php-fpm.log

    7. On line 419, change the PHP session directory:

      php_value[session.save_path] = /home/<user>/session

  5. 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

  6. 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

  7. Create and edit the user's Apache include directory and file.

    1. 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>

    2. 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>

  8. Run the following command to copy the fpm.conf file from the std directory tree to the ssl 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

  9. Run the /scripts/rebuildhttpdconf script.

  10. Run the /scripts/restartsrv_httpd script.

How to disable user pools

To disable user pools, perform the following steps:

  1. 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.

  2. 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

  3. Remove the FPM user configuration file with the following command:

    rm /opt/cpanel/ea-phpxx/root/etc/php-fpm.d/$user.conf

  4. Rebuild the httpd configuration with the following command:

    /scripts/rebuildhttpdconf

  5. 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 7
    systemctl stop ea-php56-php-fpm.service
systemctl start ea-php56-php-fpm.service

  6. Restart Apache with the following command:

    /scripts/restartsrv httpd

Additional documentation