Aegis documentation

#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.

VerbEffect
configurecreate the worker account, render every file, install the baseline vhosts, validate
validaterun nginx -t -c <nginx.conf>
reloadsend the reload signal to the running master
statusread run/nginx/nginx.pid: running (pid N) or stopped
startstart the master through the keeper
stopSIGTERM, then SIGKILL after 15 seconds
restartstop, then start
exposeprint paths, state and counts, then publish /aegis/bin/nginx
helpprint 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

bash
aegis cubes nginx configureaegis --json cubes nginx configure

Creates 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.

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

#validate

bash
aegis cubes nginx validateaegis --json cubes nginx validate

Runs 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.

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

#reload

bash
aegis cubes nginx reloadaegis --json cubes nginx reload

Runs nginx -s reload. The master must already be running; a reload of a stopped daemon fails with nginx's own message.

text
✔ nginx: configuration reloaded{"ok": true, "cube": "nginx", "result": "configuration reloaded"}

#status

bash
aegis cubes nginx statusaegis --json cubes nginx status

Reads the pid file and checks that the process is alive; it never contacts the daemon.

text
✔ nginx: running (pid 732003){"ok": true, "cube": "nginx", "result": "running (pid 732003)"}

A stopped daemon answers ✔ nginx: stopped and still exits 0.

#start

bash
aegis cubes nginx startaegis --json cubes nginx start

Starts the master through the keeper. A second call reports the running pid instead of starting another copy.

text
✔ nginx: started (pid 732003){"ok": true, "cube": "nginx", "result": "started (pid 732003)"}

#stop

bash
aegis cubes nginx stopaegis --json cubes nginx stop

Sends SIGTERM and waits up to fifteen seconds; a process that ignores it is killed and the result says killed (pid N).

text
✔ nginx: stopped (pid 732003){"ok": true, "cube": "nginx", "result": "stopped (pid 732003)"}

#restart

bash
aegis cubes nginx restartaegis --json cubes nginx restart

Stop followed by start, reported as one line.

text
✔ nginx: stopped (pid 732003), started (pid 732114){"ok": true, "cube": "nginx", "result": "stopped (pid 732003), started (pid 732114)"}

#expose

bash
aegis cubes nginx exposeaegis --json cubes nginx expose

Prints 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.

text
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
text
{"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

bash
aegis cubes nginx helpaegis cubes help nginx

Prints 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.

text
ℹ Nginx — Web server, vhosts, proxies and client-IP handlingCommands  validate   Check the configuration  reload     Reload the running daemon  configure  Write the configuration and validate

The 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

bash
aegis cubes nginx config showaegis --json cubes nginx config show

Prints every setting as name=value, sorted by name. It takes no options.

text
✔ 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

bash
aegis cubes nginx config get worker-connectionsaegis --json cubes nginx config get workers
ArgumentMeaning
nameone of the setting names accepted by config set

An unknown name fails with unknown setting: <name>.

text
✔ nginx: worker-connections=8192{"ok": true, "cube": "nginx", "result": "workers=auto"}

#config set

bash
aegis cubes nginx config set --worker-connections=4096 --client-body-size=256maegis --json cubes nginx config set --workers=4

Only 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.

OptionAccepted value
--workerstext, e.g. auto or 4
--worker-connectionspositive integer
--client-body-sizesize, e.g. 128m
--keepalive-timeouttext, e.g. 65
--keepalive-requestspositive integer
--sendfile, --tcp-nopush, --tcp-nodelay, --gzipon or off
--types-hash-max-sizepositive integer
--rate-zone-size, --rate-strict-zone-sizesize, e.g. 10m
--rate, --rate-strictrate, e.g. 120r/s
--status-portport 1–65535
--ssl-session-cachesize, e.g. 10m
--real-ip-headerheader name, e.g. X-Forwarded-For
text
✔ 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

bash
aegis cubes nginx realip showaegis --json cubes nginx realip show

Takes no options. Reports the header, how many Cloudflare ranges are cached, and the extra networks.

text
✔ 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

bash
aegis cubes nginx realip refreshaegis --json cubes nginx realip refresh

Downloads 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.

text
✔ 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

bash
aegis cubes nginx realip trusted add 198.51.100.7aegis --json cubes nginx realip trusted add 10.20.0.0/16
ArgumentMeaning
networkan 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>.

text
✔ 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

bash
aegis cubes nginx realip trusted remove 198.51.100.7aegis --json cubes nginx realip trusted remove 10.20.0.0/16

Removes one entry from the trusted list and applies the change. A network that is not listed fails with not in the trusted list: <network>.

text
✔ 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.

text
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

bash
aegis cubes nginx vhosts listaegis --json cubes nginx vhosts list

Lists every .conf file in sites/, including the baseline vhosts, sorted by name. It takes no options and does not contact nginx.

text
✔ 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

bash
aegis cubes nginx vhosts checkaegis --json cubes nginx vhosts check

The same operation as validate, under the name an operator looks for while working on vhosts.

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

#vhosts show

bash
aegis cubes nginx vhosts show example.comaegis --json cubes nginx vhosts show shop.example.com
ArgumentMeaning
namethe 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>.

text
✔ 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

bash
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=30

Renders 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.

OptionValueEffect
--namenamefile name; defaults to the primary domain
--domaindomain, repeatablefirst is primary, the rest become server_name aliases
--rootpathdocument root; default <nginx.web_root>/<primary domain>
--locationdefault, php-mvc, customtemplate family (default default)
--ssl-cert-path, --ssl-cert-key-pathpathsserve an existing certificate
--phpoptional versionimplies php-mvc; a given version must equal php.version
--php-poolpool nameinclude the FPM snippet that points at that pool's socket
--limitflagadd limit_req with zone req_limit
--limit-strictflaguse zone req_limit_strict instead
--limit-burstinteger, default 40burst for the request limit
--limit-conninteger, default 0limit_conn addr_conn when above zero
--client-body-sizesizeper-vhost client_max_body_size
--redirectflagalso write the HTTP→HTTPS vhost
--templatefiletemplate 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.

text
✔ 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.conf companion are removed. The document root and its files stay on disk.

bash
aegis cubes nginx vhosts delete example.comaegis --json cubes nginx vhosts delete shop.example.com
ArgumentMeaning
namethe 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.

text
✔ 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

bash
aegis cubes nginx proxy listaegis --json cubes nginx proxy list

Lists the *-proxy.conf files under sites/ by their file name. It takes no options.

text
✔ 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

bash
aegis cubes nginx proxy show app.example.com-proxyaegis --json cubes nginx proxy show api.example.com-proxy
ArgumentMeaning
namethe base name (<domain>-proxy), with or without .conf
text
✔ 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

bash
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 --ssl

Upstream 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/.

OptionValueEffect
--namenamebase name; defaults to <primary domain>-proxy
--domaindomain, repeatableat least one is required
--upstreamorigin, repeatableat least one is required
--sslflagTLS vhost plus an HTTP→HTTPS companion
--keepaliveinteger 1–1024, default 32keepalive in the upstream block
--ssl-cert-path, --ssl-cert-key-pathpathscertificate used with --ssl
text
✔ 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.conf companion. The backend is not touched.

bash
aegis cubes nginx proxy delete app.example.com-proxyaegis --json cubes nginx proxy delete api.example.com-proxy
ArgumentMeaning
namethe base name (<domain>-proxy), with or without .conf
text
✔ 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"}