Skip to main content
emisar

PHP-FPM

v0.1.16

PHP runtime + FPM pool introspection — version, modules, ini, pool status (via fpm_status endpoint), error + slow logs, OPcache state, Composer manifest. Read-only. Set PHP_FPM_STATUS_URL env to point to the FPM status endpoint.

10 allowed by default
Pack ID
php-fpm
Vendor
emisar
OS
linux
Actions
10
Required binaries. Install these on the host before relying on the pack — an action that calls a missing one fails at run time.
php

Install

emisar pack install fetches this pack, re-validates it, and verifies its content hash against the --hash below — the exact bytes this page was rendered against, so a tampered copy is rejected — before copying it into the runner's packs dir. The command reloads a running daemon itself; no manual restart.

on the runner host 
sudo emisar pack install php-fpm --hash sha256:3c03fd5b815f2a6bdda0f8fe6af91fe57a0a21fc1b610faad55bc3c91c1b1568

Setup

Inspects the local PHP runtime and FPM pool on the runner host (php -v / --ini, logs, OPcache, Composer) — no credentials needed.

Environment

Set these on the runner host, then add each name to execution.inherit_env so the value reaches the action.

  • PHP_FPM_STATUS_URL default http://127.0.0.1/fpm-status

    URL of the FPM pool status page, used by the fpm_status/fpm_status_full/fpm_ping actions. Optional; defaults to http://127.0.0.1/fpm-status. Add it to the runner's inherit_env if you override it.

  • PHP_FPM_ERROR_LOG default /var/log/php-fpm/error.log

    Path to the PHP-FPM error log. Add it to the runner's inherit_env if you override it.

  • PHP_FPM_SLOW_LOG default /var/log/php-fpm/slow.log

    Path to the PHP-FPM slow-request log. Add it to the runner's inherit_env if you override it.

  • COMPOSER_DIR default /var/www/html

    Composer project directory inspected by composer_show. Add it to the runner's inherit_env if you override it.

Host access

Run these commands yourself on the runner host. Emisar shows and copies setup recipes; it never runs them.

Read PHP-FPM's root-owned logs and the deployment-owned Composer project.

phpfpm.error_log_tailphpfpm.slow_log_tailphpfpm.composer_show

Run the Emisar service as root

Grant access 
sudo install -d -m 0755 /etc/systemd/system/emisar.service.d
printf '%s\n' '[Service]' 'User=root' 'Group=root' | sudo tee /etc/systemd/system/emisar.service.d/10-php-fpm-host-access.conf >/dev/null
sudo systemctl daemon-reload
sudo systemctl restart emisar
Verify access 
test "$(systemctl show emisar --property=User --value)" = root
sudo test -r /var/log/php-fpm/error.log
sudo test -r /var/log/php-fpm/slow.log
sudo test -r /var/www/html/composer.lock

Impact: Every Emisar action on this runner executes as root. PHP-FPM logs can contain request details and stack traces, while the application tree can contain source and secrets.

Notes

  • The status page must be enabled in the pool config (pm.status_path) and reachable from the runner host for the fpm_status actions to return data.
  • Debian/Ubuntu log paths vary by installed PHP version. Set and allowlist PHP_FPM_ERROR_LOG and PHP_FPM_SLOW_LOG , then grant persistent read access through that deployment's log group or rotation policy.

Verify it works

Runs phpfpm.version, a low-risk read that confirms the pack can reach its target. Run it on the host once the pack is installed; pack install runs it for you.

on the runner host 
sudo emisar pack verify php-fpm

Install and configure a pack walks through the whole sequence on a host.

Actions 10 total

View on GitHub
  • phpfpm.composer_show exec low Low — read-only or trivially reversible

    composer show (in $COMPOSER_DIR)

    List installed Composer packages with versions.

    View source on GitHub
  • phpfpm.error_log_tail exec medium Medium — changes state, easily reversible

    tail FPM error_log

    Tail the FPM error log (last N lines).

    View source on GitHub
  • phpfpm.fpm_ping exec low Low — read-only or trivially reversible

    GET /ping (FPM)

    Check FPM ping endpoint (returns 'pong' if responsive).

    View source on GitHub
  • phpfpm.fpm_status exec low Low — read-only or trivially reversible

    GET /status (FPM)

    Show FPM pool summary — active processes, idle, max children, listen queue.

    View source on GitHub
  • phpfpm.fpm_status_full exec medium Medium — changes state, easily reversible

    GET /status?full (FPM per-process)

    Show per-process detail: pid, state, last request URI, current memory peak. The request URI is live client-supplied request data — query strings included — so it is rated with the pack's log tails rather than with the summary counters in `phpfpm.fpm_status`.

    View source on GitHub
  • phpfpm.ini exec low Low — read-only or trivially reversible

    php --ini

    List all loaded php.ini paths + their contents path.

    View source on GitHub
  • phpfpm.modules exec low Low — read-only or trivially reversible

    php -m

    List all loaded extensions.

    View source on GitHub
  • phpfpm.opcache_status exec low Low — read-only or trivially reversible

    GET /opcache-status

    Show OPcache stats (requires the standard opcache_status.php script reachable at PHP_OPCACHE_URL).

    View source on GitHub
  • phpfpm.slow_log_tail exec medium Medium — changes state, easily reversible

    tail FPM slow_log

    Tail the FPM slow log (last N lines of PHP backtraces for slow requests).

    View source on GitHub
  • phpfpm.version exec low Low — read-only or trivially reversible

    php -v

    Show PHP version + SAPI + Zend Engine version.

    View source on GitHub
← Back to registry
Pack reference  Publish your own