GoAdmio

fpm

Restart or reload every installed PHP-FPM version, with an optional cleanup of leftover pools, or only when memory use is high

On this page: Overview · Quick start · Syntax · Options · Output · Examples · Troubleshooting · Details · See also


Overview

/go/fpm manages PHP-FPM, the service that runs your websites' PHP code. GoAdmio can have several PHP versions installed side by side, each with its own PHP-FPM service. This command acts on all of them at once, so you don't have to look up each service name.

It can:

The command runs sudo internally, so run it as root or as a user with sudo rights.

[!WARNING] A restart cuts PHP requests for a moment, so visitors can see errors. Use reload when you can.

[!WARNING] Run with no arguments, the command also deletes the PHP-FPM pool of any domain whose web server virtual host file is missing or whose home folder no longer exists. If a virtual host file is missing by mistake, that site's PHP stops working until its configuration is rebuilt (see conf).


Quick start

# Clean up, then restart every PHP-FPM service
/go/fpm

Syntax

/go/fpm [percent] [reload|enable]
Form Behavior
/go/fpm Runs the cleanup, then restarts all PHP-FPM services.
/go/fpm reload Reloads all PHP-FPM services. No cleanup.
/go/fpm enable Sets up the socket folder for each PHP version, enables each service at boot, and restarts them. No cleanup.
/go/fpm <percent> Restarts all PHP-FPM services only if memory use is at or above that percentage. Otherwise it does nothing and exits with status 1. No cleanup.
/go/fpm <percent> reload The same, but reloads instead of restarting.

Every run is recorded in /var/log/go/fpm.log, with the time and the arguments you passed.


Options

Argument Required Notes
percent No A number such as 80 (a % sign is ignored). It must be the first argument. Only the digits are used.
reload No Reload instead of restart. Any argument that contains the word reload counts.
enable No Set up the services for reboots, then restart. Any argument that contains the word enable counts, and it takes priority over reload.

Output

The command prints nothing when it works. You may see:

Outcome Result
Memory use is below the percent you gave Nothing happens. Exit status 1.
All other runs The exit status is that of the last systemctl command.

Log

Each run appends one line to /var/log/go/fpm.log:

[Nov 21 12:00:00]# fpm 85 reload

Examples

# Clean up, then restart all PHP-FPM services
/go/fpm
# Reload without interrupting visitors
/go/fpm reload
# Restart only if at least 85% of memory is in use
/go/fpm 85
# After a reboot problem: set up sockets and boot start, then restart
/go/fpm enable
# Check one service (RHEL family: php83-php-fpm, Debian and Ubuntu: php8.3-fpm)
systemctl status php8.3-fpm

Troubleshooting

Symptom Likely cause Fix
Nothing happened, exit status 1 You gave a percent, and memory use is below it. Expected. Check with free, or lower the percentage.
A site shows an error after running with no arguments Its PHP-FPM pool was deleted because its virtual host file or home folder was missing. Rebuild its configuration with conf.
An HTTPS site stopped working (Apache) Its -le-ssl.conf virtual host was removed because its certificate files are missing. Install a certificate (see ssl), then rebuild with conf.
Unit php-fpm.service not found (RHEL family) The system's own php-fpm package isn't installed. The first step always tries to restart it. You can ignore it. The versioned services are still handled.
PHP sites fail after a reboot with a missing socket under /run/sock /run is emptied at boot, so the socket folders are gone. Run /go/fpm enable once, so each service creates its folder itself.
A service doesn't start after enable A configuration error in that PHP version. Check its status with systemctl status, and see checkphpini.
A change isn't picked up after reload Some changes need a full restart. Run /go/fpm or /go/fpm enable.
A reload happened when you wanted a restart (or the other way round) An argument contained the word reload or enable. Check the arguments.

Details

What the no-argument run cleans up

Only a run with no arguments at all does this. It happens before the restart.

Step Action
1 Runs checknginx and checkapache, which test the web server configuration and rebuild it.
2 Looks at the PHP-FPM pool file of every domain in every installed PHP version. It deletes the pool (with GoAdmio's php-fpm command) when the domain's Apache virtual host file is missing, or when /home/<domain> no longer exists.
3 On Apache only: removes any <domain>-le-ssl.conf virtual host whose certificate is found neither in /etc/letsencrypt/live/<domain>/ nor in /etc/ssl/<domain>/.
4 Runs checkphpini to repair php.ini startup errors.
5 Creates /run/sock/<version> for each PHP version (for example /run/sock/83) and sets /run/sock to mode 755.

Which services are restarted

RHEL family Debian and Ubuntu
PHP versions are found in /etc/opt/remi/ /etc/php/
Service name for each version <version>-php-fpm (for example php83-php-fpm) php<version>-fpm (for example php8.3-fpm)
Also handled The system php-fpm service —

A version is included only if it has a php.ini for PHP-FPM.

What enable sets up

For each PHP version the command writes a small systemd override, override.conf, in /etc/systemd/system/<service>.service.d/:

[Service]
RuntimeDirectory=sock/<version number>
RuntimeDirectoryMode=0755

With it, systemd creates the socket folder /run/sock/<version number> each time the service starts. The command then reloads systemd, enables the service at boot, and restarts it.

Memory check

When the first argument is a number, the command works out the share of memory in use from free (used divided by total, as a whole percentage). It continues only if that is at or above your number. This lets a scheduled job restart PHP-FPM only when memory is running high.

flowchart TD
    A["fpm [percent] [reload|enable]"] --> B{"percent given?"}
    B -- "Yes" --> C{"Memory use at or above percent?"}
    C -- "No" --> X["Exit 1, nothing done"]
    C -- "Yes" --> D{"Any arguments?"}
    B -- "No" --> D
    D -- "No arguments" --> E["Cleanup: config checks, orphaned pools, SSL vhosts, php.ini, socket folders"]
    D -- "Arguments" --> F{"enable, reload, or restart?"}
    E --> F
    F -- "enable" --> G["Write overrides, enable at boot, restart each service"]
    F -- "reload" --> H["Reload each service"]
    F -- "restart" --> I["Restart each service"]

See also

Command Description
restart Restart all PHP-FPM pools and the active web server
reload Reload PHP-FPM and the active web server
web Restart (default) or reload the active web server, Nginx or Apache
checkapache Test the Apache configuration and remove SSL virtual hosts whose Let's Encrypt certificate is missing, then rebuild it
checknginx Test the Nginx configuration and remove the virtual host of any domain whose Let's Encrypt certificate is missing, then rebuild it
checkphpini Scan every php.ini on the server for startup errors and delete the line that causes each one
conf Rebuild Apache/Nginx virtual hosts, PHP-FPM pools, and SSL for all accounts, or the web configuration of one domain
mem Check the top ten memory-consuming commands or services