Aegis documentation

#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

toml
[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"
KeyDefaultMeaning
useraegis-wwwworker account, created by the cube if missing
worker_processesautoone worker per core by default
worker_connections8192per worker; needs a matching ulimit -n
keepalive_timeout65seconds an idle client connection stays open
keepalive_requests1000requests served per connection
client_max_body_size128mupload limit in the http block
sendfile, tcp_nopush, tcp_nodelayonkernel send path tuning
gziponcompression for text responses
server_tokensoffhides the nginx version in headers
types_hash_max_size2048MIME type table size
prefixinstalled prefixwhere nginx was built
config_dir/aegis/config/nginxgenerated configuration
log_dir/aegis/logs/nginxerror.log, access.log, access_json.log
run_dir/aegis/run/nginxnginx.pid
web_root/aegis/data/wwwdocument root used when a vhost passes none
status_port8099loopback port of the local status vhost
ssl_session_cache10mshared TLS session cache
real_ip_headerX-Forwarded-Forheader trusted for the client address
real_ip_trustedemptyextra networks besides loopback, private ranges and Cloudflare
rate_zone_size10mmemory for the request-rate zone
rate120r/sdefault request rate used by --limit
rate_strict_zone_size1mmemory for the strict zone
rate_strict5r/srate used by --limit-strict
panel.domainemptywhen set, a vhost is generated for the panel
panel.root/etc/aegisdocument root for that vhost
panel.client_max_body_size128mupload 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

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

snippets/ are not included at http level: several of them contain location, which is only valid inside a server.

#Commands

bash
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

bash
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/nginx

configure also:

  • creates the worker account (nginx.user) when missing;
  • creates the proxy cache directory;
  • creates html/index.html from default-index.html without overwriting;
  • writes the baseline vhosts once: aegis-default.conf (port 80),
  • aegis-catchall-https.conf (rejects unknown SNI), aegis-status.conf (127.0.0.1:<status_port>);

  • skips aegis-20-geoip2.conf and removes a stale copy when the MaxMind
  • database 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.logevery vhost, json format, if=$loggable
    access.loghttp fallback, for anything without its own file
    <site>-access.loga site vhost (vhosts create, proxy create)
    <site>-redirect-access.logthe HTTP→HTTPS vhost of a site
    panel-access.log, webmail-access.log, relay-access.logthe panel, webmail and relay vhosts
    default-access.log, default-ssl-access.log, status-access.logthe 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:

    text
    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

    bash
    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.com

    Options:

    FlagEffect
    --namefile name; defaults to the primary domain
    --domainrepeatable; first is primary, the rest become server_name aliases
    --rootdocument root; default <nginx.web_root>/<primary domain>
    --locationdefault (static) or php-mvc (Laravel-style front controller)
    --ssl-cert-path, --ssl-cert-key-pathserve an existing certificate
    --php[=version]implies php-mvc; an explicit version must match php.version
    --php-poolserve PHP from one FPM pool instead of the default one
    --limit, --limit-strictenable limit_req with req_limit / req_limit_strict
    --limit-burst, --limit-connburst size and connection cap
    --client-body-sizeper-vhost client_max_body_size
    --redirectalso write the HTTP→HTTPS vhost
    --location=custom --template=<file>render your own template with the same variables

    Template choice:

    locationTLStemplate
    defaultnoaegis-default.conf
    defaultyesaegis-default-ssl.conf
    php-mvcnoaegis-laravel.conf
    php-mvcyesaegis-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

    bash
    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-proxy
  • upstream entries accept host, host:port, http://…, https://…;
  • HTTPS origins get proxy_ssl_server_name on and proxy_ssl_verify off;
  • --ssl also writes an HTTP vhost that redirects to HTTPS;
  • files are <name>-proxy.conf (and <name>-proxy-redirect.conf), so listing,
  • showing and deleting use that name.

    #Layout of a request (example)

    nginx
    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

    bash
    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=20m

    Accepted 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

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

    refresh 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

    bash
    aegis geoip update                 # GeoLite2-Countryaegis cubes nginx configure        # renders aegis-20-geoip2.confaegis cubes nginx reload

    Without 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

    bash
    aegis cubes nginx vhosts create --domain=app.example.com --location=php-mvc   --limit --limit-burst=30 --limit-conn=15 --client-body-size=64m

    The vhost file then carries:

    nginx
    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

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

    vhosts 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).