Configure or Disable PHP-FPM with User Pools for EasyApache 4

Overview

Warning:
  • This document is only valid for cPanel & WHM version 58 and earlier. We deprecated this configuration process in cPanel & WHM version 60.
  • Because this document outlines deprecated functionality, cPanel Technical Support can’t help you with this process.
  • To configure PHP-FPM for cPanel & WHM version 60 or later, read our MultiPHP Manager 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:

  • PHP Handlers
  • Yellowdog Updater, Modified (yum) Basics

Set up pools per user

Important:
  • You can only configure one PHP-FPM pool per user.
  • These instructions assume that your server runs EasyApache 4.

  • In the examples below, the following statements are true:

    • ea-php56 and ea-php70 represent the versions of PHP to use.
    • username represents a user on the system.
    • example.com represents the domain’s base directory.
    • group represents the user’s group.
    • account represents the user’s account.
    • virtual-host represents the name of the virtual host.

To set up PHP-FPM for a shared server, follow the steps for your PHP version:

PHP 5.6

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

    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: 

    1
2

    mkdir -p /home/username/run/
chown username. /home/username/run/

  3. Run the following commands to copy and rename your PHP version’s www.conf.example file: 

    1
2

    cd /opt/cpanel/ea-php56/root/etc/php-fpm.d/
cp www.conf.example username.conf

  4. Edit your username.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: 

      1
2

      ; 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/username/run/php56-fpm.sock

    • Uncomment line 31 and line 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 username value. 

        listen.owner = username

      • The listen.group parameter to the nobody value. 

        listen.group = nobody

    • On line 35, change the user and group targets to the name and group of the user who will 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 = username
  ; 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/username/logs/ea-php56-php-fpm.log

    • On line 225, change the PHP session directory: 

      php_value[session.save_path] = /home/username/session

  5. Create the /home/username/session directory, if it doesn’t already exist, and update the username permissions. To do this, run the following commands: 

    1
2

    mkdir /home/username/session
chown username. /home/username/session

  6. Restart the PHP-FPM service by running the following commands:

    • CentOS 6: 
      1
2

      /etc/init.d/ea-php56-php-fpm stop
/etc/init.d/ea-php56-php-fpm start
    • CentOS 7: 
      1
2

      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:

    • Run the following commands to create the Apache include directories: 

      1
2

      mkdir -p /etc/apache2/conf.d/userdata/std/2_4/account/virtual-host
mkdir -p /etc/apache2/conf.d/userdata/ssl/2_4/account/virtual-host

    • Edit the /etc/apache2/conf.d/userdata/std/2_4/account/virtual-host/fpm.conf file to include the following lines: 

      1
2
3
4

      <IfModule proxy_fcgi_module>
    ProxyPassMatch "^/(.*.php(/.*)?)$" "unix:/home/username/run/php56-fpm.sock|fcgi://localhost/home/username/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/account/virtual-host/fpm.conf /etc/apache2/conf.d/userdata/ssl/2_4/account/virtual-host/fpm.conf

  9. Run the /scripts/rebuildhttpdconf script.

  10. Run the /scripts/restartsrv_httpd script.

PHP 7.0

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: 

    1
2

    mkdir -p /home/username/run/
chown username. /home/username/run/

  3. Run the following commands to copy and rename your PHP version’s www.conf.example file: 

    1
2

    cd /opt/cpanel/ea-php70/root/etc/php-fpm.d/
cp www.conf.example username.conf

  4. Edit your username.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 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 = username
; RPM: Keep a group allowed to write in log dir.
group = username

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

      listen = /home/username/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:

      • Change the listen.owner parameter to the username value.
      • Change the listen.group parameter to the nobody value. 
        listen.owner = username
listen.group = nobody
      • On line 52, change the user and group targets to the name of the user who you wish to own the process.
      • On line 413, change the error log directory: 
        php_admin_value[error_log] = /home/username/logs/ea-php70-php-fpm.log
      • On line 419, change the PHP session directory: 
        php_value[session.save_path] = /home/username/session

  5. Create the /home/username/session directory, if it doesn’t already exist, and update the username value’s permissions. To do this, run the following commands: 

    1
2

    mkdir /home/username/session
chown username. /home/username/session

  6. Run the following commands to stop and restart the PHP FPM service:

    • Centos 6: 
      1
2

      /etc/init.d/ea-php70-php-fpm stop
/etc/init.d/ea-php70-php-fpm start
    • CentOS 7: 
      1
2

      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.

    • Run the following commands to create the Apache include directories: 

      1
2

      mkdir -p /etc/apache2/conf.d/userdata/std/2_4/account/virtual-host
mkdir -p /etc/apache2/conf.d/userdata/ssl/2_4/account/virtual-host

    • Edit the /etc/apache2/conf.d/userdata/std/2_4/account/virtual-host/fpm.conf file to include the following lines: 

      1
2
3
4

      <IfModule proxy_fcgi_module>
  ProxyPassMatch "^/(.*.php(/.*)?)$" "unix:/home/username/run/php70-fpm.sock|fcgi://localhost/home/username/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/account/virtual-host/fpm.conf /etc/apache2/conf.d/userdata/ssl/2_4/account/virtual-host/fpm.conf

  9. Run the /scripts/rebuildhttpdconf script.

  10. Run the /scripts/restartsrv_httpd script.

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 the /scripts/rebuildhttpdconf script 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 and 6 
      1
2

      /etc/init.d/ea-php56-php-fpm stop
/etc/init.d/ea-php56-php-fpm start
    • CentOS 7 
      1
2

      systemctl stop ea-php56-php-fpm.service
systemctl start ea-php56-php-fpm.service

  6. Restart Apache with the following command: 

    /scripts/restartsrv httpd