#Cube: nginx
nginx is built with the official modules plus ndk, set-misc, echo, geoip2, headers-more, cache-purge, fancyindex and nchan.
Not included: brotli (the module wants the brotli sources in its own deps/ directory; requires a vendoring step) and upstream-fair (does not compile with nginx 1.30).
In the panel: Web → Vhosts, Cache, Guards. Every write there is a task.
#Configuration
[nginx]user = "aegis-www"worker_processes = "auto"worker_connections = 8192keepalive_timeout = "65"keepalive_requests = 1000client_max_body_size = "128m"sendfile = "on"tcp_nopush = "on"tcp_nodelay = "on"gzip = "on"server_tokens = "off"types_hash_max_size = 2048prefix = "/aegis/apps/web/nginx/1.30"config_dir = "/aegis/config/nginx"log_dir = "/aegis/logs/nginx"run_dir = "/aegis/run/nginx"web_root = "/aegis/data/www"status_port = "8099"ssl_session_cache = "10m"real_ip_header = "X-Forwarded-For"real_ip_trusted = # extra CIDRs, Cloudflare is added automaticallyrate_zone_size = "10m"rate = "120r/s"rate_strict_zone_size = "1m"rate_strict = "5r/s"[panel]domain = "" # vhost for the panel itself, when setroot = "/etc/aegis"client_max_body_size = "128m"| Key | Default | Meaning |
|---|---|---|
user | aegis-www | worker account, created by the cube if missing |
worker_processes | auto | one worker per core by default |
worker_connections | 8192 | per worker; needs a matching ulimit -n |
keepalive_timeout | 65 | seconds an idle client connection stays open |
keepalive_requests | 1000 | requests served per connection |
client_max_body_size | 128m | upload limit in the http block |
sendfile, tcp_nopush, tcp_nodelay | on | kernel send path tuning |
gzip | on | compression for text responses |
server_tokens | off | hides the nginx version in headers |
types_hash_max_size | 2048 | MIME type table size |
prefix | installed prefix | where nginx was built |
config_dir | /aegis/config/nginx | generated configuration |
log_dir | /aegis/logs/nginx | error.log, access.log, access_json.log |
run_dir | /aegis/run/nginx | nginx.pid |
web_root | /aegis/data/www | document root used when a vhost passes none |
status_port | 8099 | loopback port of the local status vhost |
ssl_session_cache | 10m | shared TLS session cache |
real_ip_header | X-Forwarded-For | header trusted for the client address |
real_ip_trusted | empty | extra networks besides loopback, private ranges and Cloudflare |
rate_zone_size | 10m | memory for the request-rate zone |
rate | 120r/s | default request rate used by --limit |
rate_strict_zone_size | 1m | memory for the strict zone |
rate_strict | 5r/s | rate used by --limit-strict |
panel.domain | empty | when set, a vhost is generated for the panel |
panel.root | /etc/aegis | document root for that vhost |
panel.client_max_body_size | 128m | upload limit for the panel vhost |
configure reads the TLS certificate through the ssl module for the primary IP, so it is not a key here; per-vhost certificates come from vhosts create --ssl-cert-path/--ssl-cert-key-path.
#Files
<nginx.config_dir>/├── nginx.conf main configuration├── conf.d/ http-level blocks, loaded in name order│ ├── aegis-05-logging.conf log_format main + json│ ├── aegis-06-logging-access.conf│ ├── aegis-10-real-ip.conf│ ├── aegis-20-geoip2.conf only when the MaxMind DB exists│ ├── aegis-25-geoip-countries.conf│ ├── aegis-30-bad-bots.conf│ ├── aegis-35-whitelist.conf│ ├── aegis-40-proxy-cache.conf│ ├── aegis-45-rate-limit.conf│ └── aegis-50-ssl-http.conf├── snippets/ blocks included by vhosts (location level!)├── sites/ one file per vhost└── html/ blocked.html, challenge.html, index.htmlsnippets/ are not included at http level: several of them contain location, which is only valid inside a server.
#Commands
aegis cubes nginx configure # render nginx.conf, conf.d, snippets, html, # then install the baseline vhosts and validateaegis cubes nginx validate # nginx -taegis cubes nginx reload # nginx -s reloadaegis cubes nginx start|stop|restart|status#expose
aegis cubes nginx exposecube nginxinstalled /aegis/apps/web/nginx/1.30state running pid 732003vhosts 6proxies 1json log /aegis/logs/nginx/access_json.logpublished /aegis/bin/nginxconfigure also:
nginx.user) when missing;html/index.html from default-index.html without overwriting;aegis-default.conf (port 80),aegis-catchall-https.conf (rejects unknown SNI), aegis-status.conf (127.0.0.1:<status_port>);
aegis-20-geoip2.conf and removes a stale copy when the MaxMinddatabase is missing, so nginx still starts.
#Logging
Every vhost writes its own access log plus the shared JSON tracking log:
File under <logs>/ | Written by |
|---|---|
access_json.log | every vhost, json format, if=$loggable |
access.log | http fallback, for anything without its own file |
<site>-access.log | a site vhost (vhosts create, proxy create) |
<site>-redirect-access.log | the HTTP→HTTPS vhost of a site |
panel-access.log, webmail-access.log, relay-access.log | the panel, webmail and relay vhosts |
default-access.log, default-ssl-access.log, status-access.log | the baseline vhosts |
access_json.log is the tracking log: one file for all sites, so a traffic report has a single source. The $loggable map (aegis-05-logging.conf) drops static assets, and the json format carries remote_addr (real client), proxy_ip ($realip_remote_addr), upstream_*, TLS protocol and cipher, and geoip_country (- when the database is absent).
A vhost that defines any access_log replaces the http-level pair, so every template declares both lines explicitly; location = /favicon.ico turns logging off for that one URI. The TLS catch-all is the only vhost without a log: it answers with ssl_reject_handshake, so no HTTP request is ever created.
Existing vhosts keep the file they were rendered with. A site created before a template change gets the new log lines only when it is recreated, or by editing its file under sites/ — the files are the source of truth.
#Real client IP
Always on:
set_real_ip_from 127.0.0.1/32;set_real_ip_from 10.0.0.0/8;… (private ranges)set_real_ip_from 203.0.113.7; # nginx.real_ip_trustedreal_ip_header X-Forwarded-For;real_ip_recursive on;Cloudflare sets X-Forwarded-For, so recursive parsing resolves the client behind it, and $realip_remote_addr keeps the proxy address for the log.
#Vhosts
aegis cubes nginx vhosts listaegis cubes nginx vhosts create --domain=example.com --location=php-mvcaegis cubes nginx vhosts create --domain=shop.example.com --location=php-mvc --php-pool=shop # its own FPM pool and socketaegis cubes nginx vhosts create --name=app.example.com --domain=app.example.com --domain=www.app.example.com --root=/aegis/data/www/app --location=php-mvcaegis cubes nginx vhosts show example.comaegis cubes nginx vhosts checkaegis cubes nginx vhosts delete example.comOptions:
| Flag | Effect |
|---|---|
--name | file name; defaults to the primary domain |
--domain | repeatable; first is primary, the rest become server_name aliases |
--root | document root; default <nginx.web_root>/<primary domain> |
--location | default (static) or php-mvc (Laravel-style front controller) |
--ssl-cert-path, --ssl-cert-key-path | serve an existing certificate |
--php[=version] | implies php-mvc; an explicit version must match php.version |
--php-pool | serve PHP from one FPM pool instead of the default one |
--limit, --limit-strict | enable limit_req with req_limit / req_limit_strict |
--limit-burst, --limit-conn | burst size and connection cap |
--client-body-size | per-vhost client_max_body_size |
--redirect | also write the HTTP→HTTPS vhost |
--location=custom --template=<file> | render your own template with the same variables |
Template choice:
| location | TLS | template |
|---|---|---|
| default | no | aegis-default.conf |
| default | yes | aegis-default-ssl.conf |
| php-mvc | no | aegis-laravel.conf |
| php-mvc | yes | aegis-laravel-ssl.conf |
With no explicit certificate, the cube calls ssl.ensure_domains, so a vhost with several names gets one certificate covering all of them (see ../ssl-and-tls.md).
PHP locations include snippets/aegis-php-fpm.conf, which uses php.socket (prefixing unix: itself) and {{nginx_prefix}}/conf/fastcgi_params.
#Proxy vhosts
aegis cubes nginx proxy listaegis cubes nginx proxy create --domain=app.example.com --upstream=10.0.0.5:8080aegis cubes nginx proxy create --domain=app.example.com --upstream=10.0.0.5:8080 --upstream=10.0.0.6:8080 --keepalive=64aegis cubes nginx proxy create --domain=app.example.com --ssl --upstream=https://origin.internal:443aegis cubes nginx proxy show app.example.com-proxyaegis cubes nginx proxy delete app.example.com-proxyhost, host:port, http://…, https://…;proxy_ssl_server_name on and proxy_ssl_verify off;--ssl also writes an HTTP vhost that redirects to HTTPS;<name>-proxy.conf (and <name>-proxy-redirect.conf), so listing,showing and deleting use that name.
#Layout of a request (example)
upstream app_example_com_upstream server 10.0.0.5:8080; server 10.0.0.6:8080; keepalive 64;server listen 443 ssl; server_name app.example.com www.app.example.com; ssl_certificate /aegis/data/certbot/live/app.example.com/fullchain.pem; ssl_certificate_key /aegis/data/certbot/live/app.example.com/privkey.pem; location / proxy_pass http://app_example_com_upstream; include /aegis/config/nginx/snippets/aegis-proxy-params.conf; #Tuning values
aegis cubes nginx config showaegis cubes nginx config get worker-connectionsaegis cubes nginx config set --worker-connections=4096 --client-body-size=256maegis cubes nginx config set --rate=200r/s --rate-zone-size=20mAccepted keys: workers, worker-connections, client-body-size, keepalive-timeout, keepalive-requests, sendfile, tcp-nopush, tcp-nodelay, gzip, types-hash-max-size, rate-zone-size, rate, rate-strict-zone-size, rate-strict, status-port, ssl-session-cache, real-ip-header.
Values are validated, written to server.toml under [nginx], then the configuration is re-rendered, tested and reloaded.
#Real client IP commands
aegis cubes nginx realip showaegis cubes nginx realip refresh # Cloudflare rangesaegis cubes nginx realip trusted add 203.0.113.7aegis cubes nginx realip trusted remove 203.0.113.7refresh downloads the Cloudflare v4/v6 lists (~22 ranges), validates them and stores them in <nginx.config_dir>/cloudflare.txt; they are added to set_real_ip_from on the next render. Trusted networks also enter the geo $is_whitelisted block, so they skip country and bot guards.
#GeoIP
aegis geoip update # GeoLite2-Countryaegis cubes nginx configure # renders aegis-20-geoip2.confaegis cubes nginx reloadWithout the database the block is skipped and the JSON log records "geoip_country":"-"; with it, requests carry the country code ("geoip_country":"DE"). aegis-25-geoip-countries.conf turns codes into the $blocked_country gate used by edge vhosts.
#Per-vhost limits
aegis cubes nginx vhosts create --domain=app.example.com --location=php-mvc --limit --limit-burst=30 --limit-conn=15 --client-body-size=64mThe vhost file then carries:
limit_req zone=req_limit burst=30 nodelay;limit_conn addr_conn 15;client_max_body_size 64m;--limit-strict swaps the zone for req_limit_strict (slower rate, defined in conf.d/aegis-45-rate-limit.conf).
#Redirect and custom templates
# TLS vhost plus the matching :80 redirectaegis cubes nginx vhosts create --domain=example.com --redirect# your own template, rendered with the usual variablesaegis cubes nginx vhosts create --domain=api.example.com --location=custom --template=/root/api-vhost.confvhosts delete removes the redirect companion too.
#Status
Complete: render, validate, reload, start/stop via keeper, baseline vhosts, vhosts with PHP/Laravel/TLS/limits/redirect/custom templates, proxy vhosts, tuning values, real client IP, GeoIP, JSON output, expose.
Optional, not enabled: brotli (module needs its brotli sources vendored) and upstream-fair (incompatible with nginx 1.30).