How to configure PHP-FPM pool settings for performance

Configure the PHP FastCGI Process Manager to handle increased traffic loads efficiently. These steps target Ubuntu 24.04 with PHP 8.3.x and Nginx 1.24.x. You will adjust process management strategies and resource limits to prevent exhaustion.

Prerequisites

• Ubuntu 24.04 LTS server
• Nginx 1.24.x installed and running
• PHP 8.3.x installed via the official repository or Ondřej Sur's repo
• sudo privileges to modify system files
• Access to the PHP-FPM pool configuration directory, typically /etc/php/8.3/fpm/pool.d/

Step 1: Create a dedicated pool configuration file

Copy the default pool configuration to create a new optimized pool. This isolates your settings from the default pool used by other applications.

sudo cp /etc/php/8.3/fpm/pool.d/www.conf /etc/php/8.3/fpm/pool.d/www-optimized.conf

Step 2: Set the process manager type

Choose between dynamic or static process management. Dynamic mode is recommended for variable traffic. Set the manager type to dynamic to scale workers based on load.

sudo nano /etc/php/8.3/fpm/pool.d/www-optimized.conf

Find the line starting with pm = and change it to dynamic.

pm = dynamic

Step 3: Configure the maximum number of children

Define the maximum number of worker processes. A value of 100 to 200 is standard for small to medium sites. Increase this number if your server has ample RAM. Set pm.max_children to 150.

pm.max_children = 150

Calculate the optimal value based on available RAM. Divide total RAM by the memory needed per process (PHP + OS overhead). For a 4GB server, 150 processes at 20MB each is safe.

Step 4: Set the start and minimum children

Define how many processes start immediately and the minimum number kept alive. This prevents the server from spawning too many processes instantly. Set pm.start to 5 and pm.min_spare_servers to 5.

pm.start = 5
pm.min_spare_servers = 5

Step 5: Configure spare process limits

Set the maximum number of spare processes and the rate at which they are spawned. This controls the queue size for incoming requests. Set pm.max_spare_servers to 20 and pm.max_requests to 500.

pm.max_spare_servers = 20
pm.max_requests = 500

Restart the process manager to apply these changes. A lower pm.max_requests value forces workers to restart more often, which clears memory leaks.

Step 6: Adjust the request timeout

Set the timeout for a single request. If a script takes longer than this, PHP-FPM kills the process. Set pm.max_requests to 500 to rotate workers periodically. Set request_terminate_timeout to 60 seconds.

request_terminate_timeout = 60s

Prevent PHP from hanging indefinitely. If a request exceeds this time, the process is terminated and a 504 Gateway Timeout error is returned to the client.

Step 7: Configure the child process start rate

Control how quickly new processes are started when the pool is under load. This prevents a sudden spike in memory usage. Set pm.max_requests_start_rate to 10 and pm.max_requests_start_rate_time to 1s.

pm.max_requests_start_rate = 10
pm.max_requests_start_rate_time = 1s

Note: These specific parameters are available in newer PHP versions. If they are not recognized, they are ignored. Focus on pm.max_children and pm.max_spare_servers for core tuning.

Step 8: Set the error log path

Redirect error logs to a file for easier debugging. Set php_admin_value[error_log] to a specific file path. This ensures errors are captured even if the default logging is misconfigured.

php_admin_value[error_log] = /var/log/php-fpm-www-optimized-error.log

Ensure the directory exists and has correct permissions before referencing it in the config file.

Step 9: Reload the PHP-FPM service

Apply the new configuration without restarting the entire service. A reload ensures existing connections are handled gracefully while new ones use the updated settings.

sudo systemctl reload php8.3-fpm

Verify that the service status remains active. If the service fails to reload, check the logs for syntax errors in the configuration file.

Verify the installation

Check the active processes to ensure the new limits are applied. The output should show the number of running processes matching your pm.max_children setting under normal load.

sudo systemctl status php8.3-fpm

Look for Active: active (running). Run the following command to see the current pool status and process count.

sudo php-fpm8.3 -t

This command tests the configuration file syntax. If it returns no errors, the configuration is valid. Access the site to confirm that requests are processed without errors.

Troubleshooting

Monitor the process manager log for errors. If the process count drops to zero, the workers may be crashing. Check the php-fpm log file located at /var/log/php-fpm.log or the specific error log defined in the pool config.

sudo tail -f /var/log/php-fpm.log

Common issues include hitting the memory limit or the process count limit. If you see "Too many open files" errors, increase the file descriptor limit in limits.conf. If you see "segfault" or "core dump" errors, check for PHP extensions causing crashes.

Adjust pm.max_children if the system runs out of memory. Reducing this value prevents the system from swapping heavily. Ensure the pm.max_requests value is high enough to handle traffic but low enough to catch memory leaks.

Restart the service if you change the process manager type from static to dynamic. This ensures the new dynamic settings take effect immediately.