PHP, Node.js & Python Configuration

Mastering PHP-FPM in cPanel: Solving Default Handler Errors and Proper Configuration for All Versions

Published · Updated 8 min read
Knowledge base article
Contents (34 sections)

Mastering PHP-FPM in cPanel: Optimized Performance and Reliability

PHP-FPM (FastCGI Process Manager) is a powerful PHP handler optimized for speed, stability, and scalability. Integrated seamlessly within cPanel, PHP-FPM efficiently manages PHP processes, significantly improving website performance and server resource utilization.

What is PHP-FPM

PHP-FPM (FastCGI Process Manager) is an advanced PHP implementation that:

  • Manages PHP requests efficiently.

  • Reduces latency through optimized resource usage.

  • Enhances website responsiveness and load times.

Benefits of Using PHP-FPM in cPanel

  • Increased Performance: Efficient handling of PHP scripts with reduced CPU usage.

  • Improved Stability: Separate pools for different domains or subdomains ensure isolated environments, preventing cross-site issues.

  • Enhanced Security: Limits exposure by isolating PHP execution environments.

  • Scalability: Smoothly handles traffic spikes without server crashes or slowdown.

Enabling PHP-FPM in cPanel

Follow these simple steps to activate PHP-FPM:

  1. Log in to your cPanel dashboard.

  2. Navigate to MultiPHP Manager under the Software section.

  3. Select your domain from the domain list.

  4. Choose your desired PHP version from the dropdown menu.

  5. Toggle on PHP-FPM and click Apply.

Tip: Enable PHP-FPM individually per domain or globally based on your needs.

Optimizing PHP-FPM Settings

Fine-tuning your PHP-FPM settings can lead to significant performance gains:

Key PHP-FPM Settings:

  • Max Requests (pm.max_requests): Set limits to prevent memory leaks (recommended: 500-1000).

  • Process Manager (pm): Choose between dynamic (recommended for most setups), static (for high-performance), or ondemand (resource-efficient).

  • Max Children (pm.max_children): Adjust based on available RAM and CPU cores.

  • Idle Timeout (pm.process_idle_timeout): Reduce resource usage by terminating idle processes.

ini
pm = dynamic
pm.max_children = 20
pm.start_servers = 5
pm.min_spare_servers = 5
pm.max_spare_servers = 10
pm.max_requests = 500
code

How to Monitor PHP-FPM Usage on a Linux Server

code

PHP-FPM (FastCGI Process Manager) is the backbone of dynamic PHP website performance. Monitoring its behavior is essential for ensuring fast page loads, avoiding bottlenecks, and tuning configuration parameters effectively.

code

This guide covers various methods to monitor PHP-FPM usage in real time and identify potential issues on a Linux-based server (such as CloudLinux or CentOS with cPanel).

code
code

1. Monitor All PHP-FPM Processes (Live Count)

code

To see how many PHP-FPM child processes are running server-wide:

code
bash
watch -n 2 "ps -ef | grep php-fpm | grep pool | wc -l"
code

This gives you the total number of active PHP-FPM worker processes across all domains.

code
code

2. See Usage per Domain Pool

code

To view how many workers are running per website (pool):

code
bash
watch -n 2 "ps -ef | grep php-fpm | grep pool | awk '{print \$NF}' | sort | uniq -c"
code

Sample output:

code
code
 6 pool siteone_com
 4 pool sitetwo_com
 2 pool demoexample_com
code

This helps identify which domains are consuming the most PHP-FPM resources.

code
code

3. Real-Time CPU/Memory Usage per Worker

code

To watch which PHP-FPM workers are consuming the most memory and CPU:

code
bash
watch -n 2 "ps -eo pid,user,cmd,%mem,%cpu --sort=-%mem | grep php-fpm | grep pool"
code

This is helpful for detecting overloaded pools or runaway scripts.

code
code

4. Enable and Use PHP-FPM Status Page (Optional)

code

Each pool can define a status page. In the pool config (/opt/cpanel/ea-php81/root/etc/php-fpm.d/example.com.conf):

code
ini
pm.status_path = /status
code

Then configure Apache to pass /status requests to PHP-FPM and restrict access by IP.

code
apache
<LocationMatch "^/status$">
 SetHandler "proxy:unix:/opt/cpanel/ea-php81/root/usr/var/run/php-fpm/yourpool.sock|fcgi://localhost"
 Require ip YOUR.IP.HERE
</LocationMatch>
code

Access https://yourdomain.com/status to view:

code

  • Accepted connections

  • Active processes

  • Idle processes

  • Max children reached

  • Slow requests

code
code

5. Aggregate Monitoring Tools

code

You can also use these tools to monitor PHP-FPM performance across time:

code
Tool Purpose
htop Live memory/CPU usage
netdata Full server + PHP-FPM metrics (visual)
top -c List live command-based CPU usage
iostat Disk I/O performance
mysqladmin processlist Live MySQL query load
code
code

Final Tips

code

  • If pm.max_children is frequently reached, increase it gradually.

  • Monitor logs at:
    /usr/local/apache/logs/error_log
    /opt/cpanel/ea-php81/root/usr/var/log/php-fpm/error.log

  • Keep pm.max_requests set to 500 or more to recycle processes periodically.

code
code

Use these tools to ensure your server runs fast, stable, and scalable during high-traffic loads.

code

PHP-FPM Security Best Practices

Enhance the security of PHP-FPM environments:

  • Regularly update PHP to the latest stable version.

  • Enable open_basedir to restrict PHP scripts to specific directories.

  • Set strict file permissions (directories: 755, files: 644).

  • Regularly audit logs located at /var/log/php-fpm/.

Troubleshooting Common PHP-FPM Issues

Encountering issues Here's how to address common problems:

  • 503 Errors (Service Unavailable):

    • Check PHP-FPM error logs: /var/log/php-fpm/error.log

    • Increase resources (pm.max_children, memory limits).

  • Slow PHP Execution:

    • Optimize PHP scripts.

    • Adjust PHP-FPM pool settings for better resource allocation.

  • High CPU or Memory Usage:

    • Limit requests per child (pm.max_requests).

    • Fine-tune PHP-FPM settings to align with your server resources.

Background

You wanted to configure PHP-FPM for the ea-php81 package (or any other PHP version) as the system-wide (default) handler on a cPanel server. Historically, administrators have used commands like:

bash
/usr/local/cpanel/bin/rebuild_phpconf --default=ea-php81 --ea-php81=fpm

or

bash
whmapi1 php_set_handler version=ea-php81 handler=fpm

to set FPM globally. However, on newer cPanel versions (e.g., v11.126.x on CloudLinux 8.10), these approaches fail or do not work as expected.

The Core Issue

1. Deprecated Scripts and Handler System

  • The rebuild_phpconf script and php.conf.yaml approach are deprecated in recent cPanel versions.

  • PHP-FPM is not treated as an Apache handler, so php_set_handler fails with:

code
API failure: The "get_config_string" method is missing in the Cpanel::WebServer::Supported::apache::Handler::fpm class.

This error is expected behavior because cPanel does not define FPM as a handler in the traditional sense.

2. Domain-Level PHP-FPM Works

Even though the system-wide FPM setting fails, you can still confirm PHP-FPM is working for individual domains. For example:

bash
/usr/local/cpanel/scripts/php_fpm_config --rebuild

Domains such as example.com or example.net successfully use PHP-FPM pools, and httpd -M | grep proxy_fcgi confirms the module is loaded.

3. Redundant DSO Warning

Despite using PHP-FPM for all domains, WHM still shows a warning:

Recommendations for "ea-php81-php": PHP DSO * PHP DSO runs as the user nobody by default... install mod_ruid2 or mod_mpm_itk...

This warning appears solely because the ea-php81-php package is installed, not because it's actively used. It's safe to ignore if you're using PHP-FPM on all domains.

The Correct Solution

1. Convert All Existing Domains to PHP-FPM

Run the following WHM API call:

bash
whmapi1 convert_all_domains_to_fpm

This enables FPM for every existing domain using supported PHP versions.

2. Set FPM for Future Accounts

Ensure that any new domains created use PHP-FPM by default:

bash
whmapi1 php_set_default_accounts_to_fpm

3. Enable or Disable PHP-FPM per Domain

To enable PHP-FPM for a specific domain:

bash
whmapi1 php_set_vhost_versions version=ea-php81 domain=example.com fpm=1

To disable:

bash
whmapi1 php_set_vhost_versions version=ea-php81 domain=example.com fpm=0

Auto-Restart PHP-FPM for Maximum Uptime and Resilience

Boost your server reliability by configuring PHP-FPM to auto-restart on crash or failure. This proactive setup is especially useful for preventing downtime due to memory limits, PHP bugs, or DoS attacks.

Why You Need It

  • Improves website uptime by recovering from PHP-FPM hangs

  • Avoids 504 errors and "Primary script unknown" logs

  • Perfect for WordPress, or high-traffic PHP sites

Step-by-Step Setup

Step 1: Create an Override File for PHP 8.1

bash
sudo mkdir -p /etc/systemd/system/ea-php81-php-fpm.service.d

Step 2: Add the Auto-Restart Configuration

bash
echo -e "[Service]\nRestart=always\nRestartSec=5s" | sudo tee /etc/systemd/system/ea-php81-php-fpm.service.d/override.conf

This tells systemd to always restart the service 5 seconds after any failure.

Step 3: Reload systemd and Restart PHP-FPM

bash
sudo systemctl daemon-reexec
sudo systemctl restart ea-php81-php-fpm

Step 4: Confirm It's Working

Run this command to verify:

bash
systemctl show ea-php81-php-fpm | grep Restart

Expected output:

code
Restart=always
RestartUSec=5s

Pro Tips

  • Enable this for other versions like ea-php80, ea-php82 as needed

  • Combine with monitoring tools like CSF or Monit for alerts

  • Add this to your onboarding SOPs or automation scripts

Business Benefits

Upgrade Impact
Auto-restart on failure Keeps mission-critical sites always running
Works with systemd No extra software required
Lightweight implementation Takes less than 2 minutes to configure

Best Practices

  • Use php_fpm_config --rebuild or WHM MultiPHP Manager to check current domain-level FPM usage.

  • Ignore the DSO warnings if no domains are actually using the DSO handler.

  • Avoid deprecated scripts like rebuild_phpconf for FPM configuration.

Final Summary

  • Problem: Errors when trying to set FPM as a system-wide handler via php_set_handler or rebuild_phpconf.

  • Reason: PHP-FPM is not a traditional Apache handler in cPanel's new architecture.

  • Solution: Use convert_all_domains_to_fpm, php_set_default_accounts_to_fpm, and php_set_vhost_versions APIs.

  • Clarification: Warnings for "PHP DSO" are harmless if FPM is in use.

By following these supported methods, you'll successfully configure PHP-FPM for ea-php81, ea-php82, or a

Monitoring PHP-FPM Performance

Use built-in tools and third-party applications for ongoing monitoring:

  • cPanel Metrics: Review CPU, memory, and resource usage directly in cPanel.

  • Server Monitoring Tools: Leverage Nagios, Munin, Zabbix, or Grafana for detailed insights.

Note: CentOS has reached end-of-life. If you are setting up a new server, we recommend using AlmaLinux or Rocky Linux as a drop-in replacement. The commands and procedures in this article apply equally to AlmaLinux and Rocky Linux.

Was this article helpful?

Your answer helps us decide what to improve next.

Still need help? Open a support ticket and our team will reply.

Related articles

Prefer an app? Add this site to your home screen.Get the app
Need Help?
Live chatNew TicketTrack TicketKnowledge BaseContact UsWhatsApp
Mastering PHP-FPM in cPanel: Solving Default Handler Errors and Proper Configuration for All Versions - Knowledge Base