Reference

For looking up a flag, a key or a path. Each entry is one line; the pages under How it decides and Operating it say why. Flags are shown as --flag; -flag is accepted too, and fpm-tune <command> -h prints the same list.

Commands

plan, advisory serve and top run as the php-fpm user or root, because they read the pool configuration and the status pages. Positional arguments are refused on every command: Go's flag parsing stops at the first one and drops the flags after it. See Requirements.

Flags shared by plan, apply, enable-status and serve

--sizing p95 sizes on the 95th percentile with a 10% margin, floored by the most recent peak; peak sizes on the typical peak itself, which rises in one scrape and decays on a half-life, with the same floor. See Measuring workers.

plan

Without --drop-in-dir, a host running several masters is planned as one, against one of their memory limits. When another fpm-tune holds the state lock, plan reports without recording; when the state directory is not writable, likewise, and says so.

apply

--no-learn is refused unless --dry-run is also given: applying has to record what it wrote, or the next run reloads the pool this one just reloaded. apply refuses to write from a budget it could not confirm; pass --memory. On a host running several masters, --drop-in-dir is required. See How it fails safe.

enable-status

It writes zz-fpm-tune-status.conf, validates, reloads, and rolls back if the master does not come back. With every pool already exposing a page it prints Every pool on this master already exposes a status page and does nothing.

serve

--apply --no-learn is refused, for the same reason as on apply. --recommend inside a directory a master includes is refused. A second daemon whose --metrics address is taken does not start.

install-service

A first run writes the whole config; a re-run keeps it and changes only the keys named. Both rewrite the unit and restart the service. See Running as a daemon.

mode

fpm-tune mode                  # print the current mode
sudo fpm-tune mode apply       # rewrite the mode line and restart the service
sudo fpm-tune mode advisory

No flags. Refused, with the fix, when /etc/fpm-tune/config does not exist.

top

The keys are on Applying once.

apply-now

The config file

/etc/fpm-tune/config is what the installed service reads (serve --config). One key = value per line; blank lines and lines starting with # or ; are ignored. Every serve flag name is a key (interval = 15s, reserve = 20%, cpu = true), and an unknown key is refused, so a typo stops the service rather than being ignored. A flag given on the command line overrides the file.

mode is the one key that is not a flag: advisory (the default) or apply. In advisory mode, when no recommend key is set, the recommendation is written to /var/lib/fpm-tune/recommended.conf. The file install-service writes carries mode and metrics as active lines and the other common keys as commented defaults:

mode = advisory

# Where /metrics is served. Empty disables it.
metrics = 127.0.0.1:9110

# heartbeat = 30m
# sizing = p95
# cpu = true
# cpu-headroom = 2
# drop-in-dir =
# history = 24h
# control = /var/lib/fpm-tune/control.sock
# recommend = /var/lib/fpm-tune/recommended.conf

fpm-tune mode and a re-run of install-service rewrite single lines and leave the rest, including your comments, as they were. After editing by hand: sudo systemctl restart fpm-tune.

Files and paths

<id> is the first eight hex digits of a SHA-256 of the pool directory, so two masters sharing a backup directory keep separate records. The pool directory is the one the master includes, /etc/php/8.4/fpm/pool.d on Debian and Ubuntu.

Pool markers

A pool declares its own class and headroom in its config, as env[...] lines that php-fpm accepts and fpm-tune reads:

[media]
env[FPM_TUNE_WORKLOAD] = subprocess-heavy
env[FPM_TUNE_CPU_HEADROOM] = 3

FPM_TUNE_WORKLOAD names the class, overriding --workload for this pool: web (aliases api, simple; spawns nothing, the default), bursty (a child now and then), subprocess-heavy (aliases subprocess, media, children; a child on most requests). Case does not matter. An unknown name is a warning in the plan, and nothing is reserved for that pool's children. Measurement refines the class once a baseline exists. See Spawned children.

FPM_TUNE_CPU_HEADROOM is the pool's own headroom factor, 1 to 100, overriding --cpu-headroom. A value that is not a number in that range is a warning in the plan and the host's headroom is used, so one pool's typo does not stop the host being planned. See CPU.

Exit status

0 on success, including -h, help and version. 1 on any error, printed to stderr as fpm-tune: ...: an unknown command, no command, a positional argument, a flag that does not parse, a refusal, or a failed run. apply exits 1 when the reload was signalled but the run ended before the master was seen to survive (the change stands; run apply again to confirm it), and when the change was applied but its record could not be saved. apply-now exits 1 when the daemon reports an error.