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


Last modified: April 3, 2020

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:

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 & 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

Additional Documentation