#nginx
The nginx cube owns everything the web server reads: nginx.conf, the conf.d/ snippets, the reusable snippets/, one file per site under sites/, the static html/ tree and the cached cloudflare.txt, all below nginx.config_dir (/aegis/config/nginx). Logs and the pid file live under nginx.log_dir and nginx.run_dir. There is no database: a vhost is a file, and the file is the source of truth. The daemon runs as the keeper service aegis-nginx with nginx -c <config_dir>/nginx.conf.
configure renders the generated files and installs three baseline vhosts (aegis-default.conf, aegis-catchall-https.conf, aegis-status.conf) the first time; vhosts create and proxy create stage a new file, run nginx -t and only then move it into sites/.
#Common commands
Cube operations share one wrapper. A success prints ✔ nginx: <detail> on stdout and exits 0, and a failure prints ✖ <message> on stderr and exits 1. Adding the global --json switch prints {"ok": true, "cube": "nginx", "result": "<detail>"} on stdout instead. expose is the exception: it prints a key/value block.
| Verb | Effect |
|---|---|
configure | create the worker account, render every file, install the baseline vhosts, validate |
validate | run nginx -t -c <nginx.conf> |
reload | send the reload signal to the running master |
status | read run/nginx/nginx.pid: running (pid N) or stopped |
start | start the master through the keeper |
stop | SIGTERM, then SIGKILL after 15 seconds |
restart | stop, then start |
expose | print paths, state and counts, then publish /aegis/bin/nginx |
help | print the command list with examples |
aegis cubes nginx help and aegis cubes help nginx print the same manual, and aegis cubes nginx <group> with no action prints that group's command list.
#configure
aegis cubes nginx configureaegis --json cubes nginx configureCreates nginx.user when it is missing, creates every directory, renders the main file and the conf.d snippets, copies default-index.html to index.html only when no index.html exists, writes the baseline vhosts that are not there yet, and removes aegis-20-geoip2.conf when the MaxMind database is absent. nginx.conf is only rewritten when its content changed.
✔ nginx: configuration written, configuration is valid{"ok": true, "cube": "nginx", "result": "configuration written, configuration is valid"}#validate
aegis cubes nginx validateaegis --json cubes nginx validateRuns nginx -t -c <config_dir>/nginx.conf. On failure the last twelve lines of nginx's answer are appended to the error and the exit code is 1.
✔ nginx: configuration is valid{"ok": true, "cube": "nginx", "result": "configuration is valid"}#reload
aegis cubes nginx reloadaegis --json cubes nginx reloadRuns nginx -s reload. The master must already be running; a reload of a stopped daemon fails with nginx's own message.
✔ nginx: configuration reloaded{"ok": true, "cube": "nginx", "result": "configuration reloaded"}#status
aegis cubes nginx statusaegis --json cubes nginx statusReads the pid file and checks that the process is alive; it never contacts the daemon.
✔ nginx: running (pid 732003){"ok": true, "cube": "nginx", "result": "running (pid 732003)"}A stopped daemon answers ✔ nginx: stopped and still exits 0.
#start
aegis cubes nginx startaegis --json cubes nginx startStarts the master through the keeper. A second call reports the running pid instead of starting another copy.
✔ nginx: started (pid 732003){"ok": true, "cube": "nginx", "result": "started (pid 732003)"}#stop
aegis cubes nginx stopaegis --json cubes nginx stopSends SIGTERM and waits up to fifteen seconds; a process that ignores it is killed and the result says killed (pid N).
✔ nginx: stopped (pid 732003){"ok": true, "cube": "nginx", "result": "stopped (pid 732003)"}#restart
aegis cubes nginx restartaegis --json cubes nginx restartStop followed by start, reported as one line.
✔ nginx: stopped (pid 732003), started (pid 732114){"ok": true, "cube": "nginx", "result": "stopped (pid 732003), started (pid 732114)"}#expose
aegis cubes nginx exposeaegis --json cubes nginx exposePrints the install prefix, the configuration directory, the live state, the log path and the cube's own rows, then publishes nginx into the shared bin directory. Publishing writes a wrapper that exports the cube's LD_LIBRARY_PATH, so the binary finds its vendored libraries.
cube nginxinstalled /aegis/apps/web/nginx/1.30configuration /aegis/config/nginxstate running (pid 732003)pid 732003log /aegis/logs/nginx/error.logmain config /aegis/config/nginx/nginx.confvhosts 5proxies 2json log /aegis/logs/nginx/access_json.logpublished /aegis/bin/nginx{"ok": true, "cube": "nginx", "installed": "/aegis/apps/web/nginx/1.30", "configuration": "/aegis/config/nginx", "state": "running (pid 732003)", "pid": "732003", "log": "/aegis/logs/nginx/error.log", "main config": "/aegis/config/nginx/nginx.conf", "vhosts": "5", "proxies": "2", "json log": "/aegis/logs/nginx/access_json.log", "published": "/aegis/bin/nginx"}#help
aegis cubes nginx helpaegis cubes help nginxPrints the title, every command with its help line, and the example block. The output is plain text in both modes: --json does not change it.
ℹ Nginx — Web server, vhosts, proxies and client-IP handlingCommands validate Check the configuration reload Reload the running daemon configure Write the configuration and validateThe list continues with start, stop, status, restart, expose, vhosts, proxy, config, realip and help, followed by the examples.
#Tuning values
config set writes server.toml under [nginx] and then re-renders, validates and reloads, so a value never sits in the file without being applied.
#config show
aegis cubes nginx config showaegis --json cubes nginx config showPrints every setting as name=value, sorted by name. It takes no options.
✔ nginx: client-body-size=128m, gzip=on, keepalive-requests=1000, keepalive-timeout=65, rate=120r/s, rate-strict=5r/s, rate-strict-zone-size=1m, rate-zone-size=10m, real-ip-header=X-Forwarded-For, sendfile=on, ssl-session-cache=10m, status-port=8099, tcp-nodelay=on, tcp-nopush=on, types-hash-max-size=2048, worker-connections=8192, workers=auto{"ok": true, "cube": "nginx", "result": "client-body-size=128m, gzip=on, keepalive-requests=1000, keepalive-timeout=65, rate=120r/s, rate-strict=5r/s, rate-strict-zone-size=1m, rate-zone-size=10m, real-ip-header=X-Forwarded-For, sendfile=on, ssl-session-cache=10m, status-port=8099, tcp-nodelay=on, tcp-nopush=on, types-hash-max-size=2048, worker-connections=8192, workers=auto"}#config get
aegis cubes nginx config get worker-connectionsaegis --json cubes nginx config get workers| Argument | Meaning |
|---|---|
name | one of the setting names accepted by config set |
An unknown name fails with unknown setting: <name>.
✔ nginx: worker-connections=8192{"ok": true, "cube": "nginx", "result": "workers=auto"}#config set
aegis cubes nginx config set --worker-connections=4096 --client-body-size=256maegis --json cubes nginx config set --workers=4Only the flags you pass are written. Values are validated before anything is saved; nothing is changed when the whole command is rejected. With no flag at all it prints nothing to change; pass at least one --flag and exits 0.
| Option | Accepted value |
|---|---|
--workers | text, e.g. auto or 4 |
--worker-connections | positive integer |
--client-body-size | size, e.g. 128m |
--keepalive-timeout | text, e.g. 65 |
--keepalive-requests | positive integer |
--sendfile, --tcp-nopush, --tcp-nodelay, --gzip | on or off |
--types-hash-max-size | positive integer |
--rate-zone-size, --rate-strict-zone-size | size, e.g. 10m |
--rate, --rate-strict | rate, e.g. 120r/s |
--status-port | port 1–65535 |
--ssl-session-cache | size, e.g. 10m |
--real-ip-header | header name, e.g. X-Forwarded-For |
✔ nginx: worker-connections=4096, client-body-size=256m; configuration written, configuration is valid; configuration reloaded{"ok": true, "cube": "nginx", "result": "workers=4; configuration written, configuration is valid; configuration reloaded"}#Real client IP
realip manages the networks trusted for X-Forwarded-For and the cached Cloudflare ranges. Loopback and the private ranges are always trusted; this adds to them.
#realip show
aegis cubes nginx realip showaegis --json cubes nginx realip showTakes no options. Reports the header, how many Cloudflare ranges are cached, and the extra networks.
✔ nginx: header=X-Forwarded-For, cloudflare=22 ranges, trusted=198.51.100.7{"ok": true, "cube": "nginx", "result": "header=X-Forwarded-For, cloudflare=22 ranges, trusted=198.51.100.7"}#realip refresh
aegis cubes nginx realip refreshaegis --json cubes nginx realip refreshDownloads the Cloudflare IPv4 and IPv6 lists, validates every entry, stores them in <config_dir>/cloudflare.txt, re-renders and reloads. A network error leaves the previous file untouched.
✔ nginx: 22 Cloudflare ranges; configuration written, configuration is valid; configuration reloaded{"ok": true, "cube": "nginx", "result": "22 Cloudflare ranges; configuration written, configuration is valid; configuration reloaded"}#realip trusted add
aegis cubes nginx realip trusted add 198.51.100.7aegis --json cubes nginx realip trusted add 10.20.0.0/16| Argument | Meaning |
|---|---|
network | an address or CIDR to trust |
Appends to nginx.real_ip_trusted in server.toml, re-renders, validates and reloads. Adding a network twice fails with already trusted: <network>.
✔ nginx: added 198.51.100.7; configuration written, configuration is valid; configuration reloaded{"ok": true, "cube": "nginx", "result": "added 10.20.0.0/16; configuration written, configuration is valid; configuration reloaded"}#realip trusted remove
aegis cubes nginx realip trusted remove 198.51.100.7aegis --json cubes nginx realip trusted remove 10.20.0.0/16Removes one entry from the trusted list and applies the change. A network that is not listed fails with not in the trusted list: <network>.
✔ nginx: removed 198.51.100.7; configuration written, configuration is valid; configuration reloaded{"ok": true, "cube": "nginx", "result": "removed 10.20.0.0/16; configuration written, configuration is valid; configuration reloaded"}#Vhosts
One file per site under sites/. The file name is the site name with .conf enforced, so example.com and example.com.conf address the same vhost.
aegis cubes nginx vhosts Manage vhostsCommands list List configured vhosts check Validate the configuration show Print one vhost delete Delete one vhost create Create a vhostRun 'aegis cubes nginx vhosts <command> --help' for the options of one command.#vhosts list
aegis cubes nginx vhosts listaegis --json cubes nginx vhosts listLists every .conf file in sites/, including the baseline vhosts, sorted by name. It takes no options and does not contact nginx.
✔ nginx: aegis-catchall-https.conf, aegis-default.conf, aegis-status.conf, example.com.conf, shop.example.com.conf{"ok": true, "cube": "nginx", "result": "aegis-catchall-https.conf, aegis-default.conf, aegis-status.conf, example.com.conf, shop.example.com.conf"}#vhosts check
aegis cubes nginx vhosts checkaegis --json cubes nginx vhosts checkThe same operation as validate, under the name an operator looks for while working on vhosts.
✔ nginx: configuration is valid{"ok": true, "cube": "nginx", "result": "configuration is valid"}#vhosts show
aegis cubes nginx vhosts show example.comaegis --json cubes nginx vhosts show shop.example.com| Argument | Meaning |
|---|---|
name | the vhost file name, with or without .conf |
Prints the file exactly as it is on disk. A missing file fails with vhost not found: <path>.
✔ nginx: # Aegis — Laravel / PHP application over HTTPserver { listen 80; server_name example.com www.example.com; root /aegis/data/www/example.com/public; index index.php; access_log /aegis/logs/nginx/example.com-access.log main; access_log /aegis/logs/nginx/access_json.log json if=$loggable; error_log /aegis/logs/nginx/example.com-error.log warn;The include lines, the optional limits block and the location block follow.
#vhosts create
aegis cubes nginx vhosts create --domain=example.com --location=php-mvcaegis cubes nginx vhosts create --domain=shop.example.com --location=php-mvc --php-pool=shop --limit --limit-burst=30Renders the template that matches the options, writes it as aegis-stage-<name>.conf, validates the whole configuration and only then moves it to its final name. A rejected vhost is deleted, so the next reload cannot fail because of it. The document root must resolve inside nginx.web_root; anything else is refused before a file is written.
| Option | Value | Effect |
|---|---|---|
--name | name | file name; defaults to the primary domain |
--domain | domain, repeatable | first is primary, the rest become server_name aliases |
--root | path | document root; default <nginx.web_root>/<primary domain> |
--location | default, php-mvc, custom | template family (default default) |
--ssl-cert-path, --ssl-cert-key-path | paths | serve an existing certificate |
--php | optional version | implies php-mvc; a given version must equal php.version |
--php-pool | pool name | include the FPM snippet that points at that pool's socket |
--limit | flag | add limit_req with zone req_limit |
--limit-strict | flag | use zone req_limit_strict instead |
--limit-burst | integer, default 40 | burst for the request limit |
--limit-conn | integer, default 0 | limit_conn addr_conn when above zero |
--client-body-size | size | per-vhost client_max_body_size |
--redirect | flag | also write the HTTP→HTTPS vhost |
--template | file | template used with --location=custom |
Without an explicit certificate the cube resolves one covering every name; a vhost with TLS is rendered from the -ssl template and given the certificate paths.
✔ nginx: created example.com.conf, configuration is valid; configuration reloaded{"ok": true, "cube": "nginx", "result": "created shop.example.com.conf, configuration is valid; configuration reloaded"}With --redirect and a resolved certificate, the companion <name>-redirect.conf is committed as well.
#vhosts delete
Destructive. The vhost file and its
<name>-redirect.confcompanion are removed. The document root and its files stay on disk.
aegis cubes nginx vhosts delete example.comaegis --json cubes nginx vhosts delete shop.example.com| Argument | Meaning |
|---|---|
name | the vhost to remove, with or without .conf |
The file is deleted first, then the configuration is validated and reloaded, so a broken remainder is reported instead of being hidden.
✔ nginx: deleted example.com.conf; configuration is valid; configuration reloaded{"ok": true, "cube": "nginx", "result": "deleted shop.example.com.conf; configuration is valid; configuration reloaded"}#Proxy vhosts
A proxy vhost is one file holding an upstream block and a server block. The file name is built by appending -proxy.conf to the base name, and the base itself already ends in -proxy, so a proxy for api.example.com is stored as api.example.com-proxy-proxy.conf. show and delete take the base (api.example.com-proxy), which maps to that file.
#proxy list
aegis cubes nginx proxy listaegis --json cubes nginx proxy listLists the *-proxy.conf files under sites/ by their file name. It takes no options.
✔ nginx: api.example.com-proxy-proxy.conf, app.example.com-proxy-proxy.conf{"ok": true, "cube": "nginx", "result": "api.example.com-proxy-proxy.conf, app.example.com-proxy-proxy.conf"}#proxy show
aegis cubes nginx proxy show app.example.com-proxyaegis --json cubes nginx proxy show api.example.com-proxy| Argument | Meaning |
|---|---|
name | the base name (<domain>-proxy), with or without .conf |
✔ nginx: # Aegis — reverse proxy over HTTPupstream app_example_com_proxy_proxy_upstream { server 10.0.0.5:8080; server 10.0.0.6:8080; keepalive 64;}The server block with the domain names, the TLS lines and the location / follow in the same file.
#proxy create
aegis cubes nginx proxy create --domain=api.example.com --upstream=127.0.0.1:8080aegis cubes nginx proxy create --domain=app.example.com --upstream=10.0.0.5:8080 --upstream=10.0.0.6:8080 --keepalive=64 --sslUpstream entries accept host, host:port, http://… and https://…; a missing port becomes 80, or 443 for an https:// origin. HTTPS origins get proxy_ssl_server_name on and proxy_ssl_verify off. The staged file is validated before it is moved into sites/.
| Option | Value | Effect |
|---|---|---|
--name | name | base name; defaults to <primary domain>-proxy |
--domain | domain, repeatable | at least one is required |
--upstream | origin, repeatable | at least one is required |
--ssl | flag | TLS vhost plus an HTTP→HTTPS companion |
--keepalive | integer 1–1024, default 32 | keepalive in the upstream block |
--ssl-cert-path, --ssl-cert-key-path | paths | certificate used with --ssl |
✔ nginx: created api.example.com-proxy-proxy.conf, configuration is valid; configuration reloaded{"ok": true, "cube": "nginx", "result": "created app.example.com-proxy-proxy.conf, configuration is valid; configuration reloaded"}#proxy delete
Destructive. Removes the proxy file and its
-redirect.confcompanion. The backend is not touched.
aegis cubes nginx proxy delete app.example.com-proxyaegis --json cubes nginx proxy delete api.example.com-proxy| Argument | Meaning |
|---|---|
name | the base name (<domain>-proxy), with or without .conf |
✔ nginx: deleted app.example.com-proxy-proxy.conf; configuration is valid; configuration reloaded{"ok": true, "cube": "nginx", "result": "deleted api.example.com-proxy-proxy.conf; configuration is valid; configuration reloaded"}