Aegis documentation

#PHP

The PHP cube owns the interpreter's configuration and the FPM master: php.ini, the global FPM file aegis-php-fpm.conf, the default pool aegis-pool.conf and one pools.d/<name>.conf per additional pool, all below php.config_dir and php.fpm_config_dir (/aegis/config/php). The Unix socket, pid file, error log and per-pool logs live under php.run_dir and php.log_dir. There is no database.

php.ini has a second owner: once the panel has written it, it leaves a .panel-managed marker in the configuration directory and configure stops rendering that one file, so panel changes survive. FPM configuration and pools are always rendered. The daemon runs as the keeper service aegis-php with php-fpm -F -y <fpm_config_dir>/aegis-php-fpm.conf.

#Common commands

Cube operations share one wrapper. A success prints ✔ php: <detail> on stdout and exits 0; a failure prints ✖ <message> on stderr and exits 1. The global --json switch prints {"ok": true, "cube": "php", "result": "<detail>"} instead.

expose is the only verb that prints a block instead of that line.

VerbEffect
configurecreate the worker group and user, render php.ini, the FPM file and the default pool, validate
validaterun php-fpm -t -y <fpm conf>
reloadsend SIGUSR2 to the master: pools reload, workers are re-executed
statusread run/php/php-fpm.pid: running (pid N) or stopped
startstart the master through the keeper
stopSIGTERM, then SIGKILL after 15 seconds
restartstop, then start
extensionsrun php -m and report the compiled extensions
exposeprint paths, version and pool count, then publish the PHP binaries
helpprint the command list with examples

#configure

bash
aegis cubes php configureaegis --json cubes php configure

Creates the group and user from php.group / php.user, then writes the three templates. When .panel-managed exists in php.config_dir, php.ini is left alone and the result says so.

text
✔ php: configuration written, configuration is valid{"ok": true, "cube": "php", "result": "configuration written, configuration is valid"}
text
✔ php: php.ini left to the panel, configuration written, configuration is valid

#validate

bash
aegis cubes php validateaegis --json cubes php validate

Runs php-fpm -t against the generated FPM file; the last twelve lines of the test output are included when it fails.

text
✔ php: configuration is valid{"ok": true, "cube": "php", "result": "configuration is valid"}

#reload

bash
aegis cubes php reloadaegis --json cubes php reload

Sends SIGUSR2 to the pid in the pid file. Unlike a restart it keeps the master and only re-executes the workers, so in-flight requests finish. Without a running master it fails with php-fpm is not running.

text
✔ php: pools reloaded{"ok": true, "cube": "php", "result": "pools reloaded"}

#status

bash
aegis cubes php statusaegis --json cubes php status

Reads the pid file only.

text
✔ php: running (pid 741002){"ok": true, "cube": "php", "result": "running (pid 741002)"}

#start

bash
aegis cubes php startaegis --json cubes php start

Starts php-fpm in the foreground under the keeper. Already running reports the existing pid.

text
✔ php: started (pid 741002){"ok": true, "cube": "php", "result": "started (pid 741002)"}

#stop

bash
aegis cubes php stopaegis --json cubes php stop

SIGTERM, then SIGKILL after the grace period.

text
✔ php: stopped (pid 741002){"ok": true, "cube": "php", "result": "stopped (pid 741002)"}

#restart

bash
aegis cubes php restartaegis --json cubes php restart

Stop followed by start. Use reload when only pools changed.

text
✔ php: stopped (pid 741002), started (pid 741058){"ok": true, "cube": "php", "result": "stopped (pid 741002), started (pid 741058)"}

#extensions

bash
aegis cubes php extensionsaegis --json cubes php extensions

Runs php -m, drops the [PHP Modules] style headers, and prints the count with the first twelve names. It takes no options.

text
✔ php: 34 extensions: Core, ctype, curl, date, dom, fileinfo, filter, gd, hash, iconv, igbinary, imagick…{"ok": true, "cube": "php", "result": "34 extensions: Core, ctype, curl, date, dom, fileinfo, filter, gd, hash, iconv, igbinary, imagick…"}

#expose

bash
aegis cubes php exposeaegis --json cubes php expose

Prints the prefix, the configuration directory, the live state, then the version, paths, socket and pool count. It publishes php, php-fpm, php-cgi, php-config, phpize and pecl when they exist in the prefix.

text
cube           phpinstalled      /aegis/apps/web/php/8.5configuration  /aegis/config/phpstate          running (pid 741002)pid            741002log            /aegis/logs/php/php-fpm.logversion        8.5php.ini        /aegis/config/php/php.inifpm config     /aegis/config/php/fpm/aegis-php-fpm.confsocket         /aegis/run/php/php-fpm.sockpools          2published      /aegis/bin/php, /aegis/bin/php-fpm, /aegis/bin/php-cgi, /aegis/bin/php-config, /aegis/bin/phpize, /aegis/bin/pecl
text
{"ok": true, "cube": "php", "installed": "/aegis/apps/web/php/8.5", "configuration": "/aegis/config/php", "state": "running (pid 741002)", "pid": "741002", "log": "/aegis/logs/php/php-fpm.log", "version": "8.5", "php.ini": "/aegis/config/php/php.ini", "fpm config": "/aegis/config/php/fpm/aegis-php-fpm.conf", "socket": "/aegis/run/php/php-fpm.sock", "pools": "2", "published": "/aegis/bin/php, /aegis/bin/php-fpm, /aegis/bin/php-cgi, /aegis/bin/php-config, /aegis/bin/phpize, /aegis/bin/pecl"}

#help

bash
aegis cubes php helpaegis cubes help php
text
ℹ PHP — PHP-FPM pools and the php.ini in useCommands  validate    Check the configuration  reload      Reload the running daemon  configure   Write php.ini and FPM configuration

The list continues with start, stop, status, restart, extensions, expose, pools and help, then the examples.

#FPM pools

The default pool is named www and is part of the main configuration; it is created by configure and cannot be created or deleted here. Every other pool is a file in pools.d/, included by glob, with its own user, group, socket and worker limit — which is how one site gets its own PHP process tree.

text
aegis cubes php pools  Manage FPM poolsCommands  list    List pools  show    Print one pool  create  Create a pool  delete  Delete a poolRun 'aegis cubes php pools <command> --help' for the options of one command.

#pools list

bash
aegis cubes php pools listaegis --json cubes php pools list

www always comes first, followed by the files in pools.d/. It takes no options.

text
✔ php: www, shop{"ok": true, "cube": "php", "result": "www, shop"}

#pools show

bash
aegis cubes php pools show shopaegis --json cubes php pools show shop
ArgumentMeaning
namepool name; www reads the default pool
text
✔ php: ; Aegis — PHP-FPM pool; Deployed to: /aegis/config/php/fpm/aegis-pool.conf[shop]user = aegis-wwwgroup = aegis-wwwlisten = /aegis/run/php/shop.socklisten.owner = aegis-wwwlisten.group = aegis-wwwlisten.mode = 0660pm = dynamicpm.max_children = 20

#pools create

bash
aegis cubes php pools create --name shop --max-children 20aegis cubes php pools create --name api --user aegis-api --group aegis-api --socket /aegis/run/php/api.sock --max-children 8

Renders one pool, validates the FPM configuration and reloads the master when it runs. The pool socket defaults to <socket directory>/<name>.sock, so two pools never share a socket.

OptionValueEffect
--namepool namerequired; www is refused
--useraccountuser = in the pool; default php.user
--groupgroupgroup = in the pool; default php.group
--socketpathlisten =; default <name>.sock next to php.socket
--max-childrenintegerpm.max_children; zero keeps the configured default
text
✔ php: created shop.conf, configuration is valid; pools reloaded{"ok": true, "cube": "php", "result": "created shop.conf, configuration is valid; pools reloaded"}

When the master is stopped the tail is php-fpm not running and the pool is picked up at the next start.

#pools delete

Destructive. Deletes pools.d/<name>.conf and reloads. A vhost still pointing at that pool's socket starts failing at its next request.

bash
aegis cubes php pools delete shopaegis --json cubes php pools delete api
ArgumentMeaning
namepool to delete; www is refused
text
✔ php: deleted shop.conf; configuration is valid; pools reloaded{"ok": true, "cube": "php", "result": "deleted shop.conf; configuration is valid; pools reloaded"}