Aegis documentation

#Configuration

Two files describe a server:

FileRole
config/aegis.tomldefaults shipped with the code
config/server.tomlwhat this server chose (written by setup/config)

load_server() merges aegis.toml underneath server.toml. Code reads keys with dotted paths and falls back to a derived default when a key is absent:

python
config.get("nginx.worker_connections")   # None when unset

#[aegis]

toml
[aegis]root = "/aegis"                                     # install rootbin_dir = "/aegis/bin"app_dir = "/etc/aegis"                              # where the code liveslogs_dir = "/aegis/logs"run_dir = "/aegis/run"runtime_dir = "/etc/aegis/runtime/python/current"user = "aegis"timezone = "UTC"

run_dir and logs_dir are used by the keeper and by every cube.

#[apps]

toml
[apps]install_path = "/aegis/apps"

Layout of one application: <install_path>/<group>/<name>/<series>, for example /aegis/apps/libs/openssl/3.5. series is the first two version parts.

#[setup] (written by the installer)

toml
[setup]primary_ip = "203.0.113.10"primary_domain = "example.com"hostname = "server.example.com"timezone = "Europe/Bucharest"

primary_ip and primary_domain feed BIND, nginx vhosts and certificate issuance.

#[geo] (written by the installer)

Country, region, city, coordinates, ISP and ASN of the primary IP, filled once through ip-api.com with a 10 s timeout. A failed lookup never blocks: the previous values are kept.

#[apps] selection (written by the installer)

toml
[apps]install = "nginx" "php" "postgresql" "postfix"

#[nginx]

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"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"safe_www_paths = "/aegis/data/www"status_port = "8099"ssl_session_cache = "10m"real_ip_header = "X-Forwarded-For"real_ip_trusted = rate_zone_size = "10m"rate = "120r/s"rate_strict_zone_size = "1m"rate_strict = "5r/s"

real_ip_trusted is a list of extra networks (["10.0.0.0/8", "198.51.100.7"]). Private ranges are always trusted; X-Forwarded-For with real_ip_recursive also covers Cloudflare.

safe_www_paths is the prefix allow-list for a vhost document root. The panel resolves a submitted path first and accepts it only when it sits under one of these prefixes — and on a directory boundary, so /home/john/www-extra is not accepted for /home/john/www. A root outside the list is refused before a task is queued; see permissions.md.

#[php]

toml
[php]version = "8.5"user = "aegis-www"group = "aegis-www"config_dir = "/aegis/config/php"fpm_config_dir = "/aegis/config/php/fpm"log_dir = "/aegis/logs/php"run_dir = "/aegis/run/php"socket = "/aegis/run/php/php-fpm.sock"read_timeout = "300s"memory_limit = "512M"pm_max_children = 50

php.socket is consumed by nginx's aegis-php-fpm.conf snippet, which prefixes unix: on its own.

#[dns]

toml
[dns]ttl = 300ns1 = ""                       # empty -> ns1.<primary_domain>ns2 = ""config_dir = "/aegis/config/bind"zones_dir = "/aegis/data/bind/zones"key_name = "aegis-tsig"rate_limit = 20

#[certbot]

toml
[certbot]config_dir = "/aegis/config/certbot"data_dir = "/aegis/data/certbot"     # certbot's --config-dirwork_dir = "/aegis/data/certbot/work"logs_dir = "/aegis/logs/certbot"email = ""propagation_seconds = 30renew_days = 30              # renewal windowrenew_interval = 21600       # how often keeper.cron checks

With an empty email, issuance passes --register-unsafely-without-email. Lineage certificates end up in <data_dir>/live/<name>/.

#[ssl]

toml
[ssl]dir = "/aegis/config/ssl"days = 825

Local certificates: <dir>/local/<name>/{privkey.pem,cert.pem}.

#[geoip]

toml
[geoip]dir = "/aegis/data/geoip"country_db = "/aegis/data/geoip/GeoLite2-Country.mmdb"city_db = "/aegis/data/geoip/GeoLite2-City.mmdb"asn_db = "/aegis/data/geoip/GeoLite2-ASN.mmdb"country_csv_dir = "/aegis/data/geoip/country-csv"country_cidrs_dir = "/aegis/data/geoip/country-cidrs"default_country = "ZZ"account_id = "…"license_key = "…"[geoip.ip_api]base_url = "http://ip-api.com/json"lang = "en"timeout = 5connect_timeout = 3

The nginx geoip2 block is only rendered when country_db exists; without it, the JSON log records "geoip_country":"-" and nginx starts normally.

#[proxy], [panel], [postfix], [dovecot], [mail], [mariadb],

[postgresql], [redis], [beanstalkd]

Each holds the paths and tuning values their cube or template needs. They follow the same rule: file paths first, tunables second, and every key optional with a sensible fallback.

#Platform services

The panel, its queue and the realtime feed have their own sections.

toml
[tasker]enabled = trueworkers = 4              # tasks run at onceinterval = 1.0           # seconds between queue pollskeep_hours = 48          # finished (done, cancelled) tasks kept this long[bird]enabled = truelisten = "0.0.0.0"port = 9982private_token = "…"      # required for the private channelmax_clients = 256queue = 64               # buffered messages per subscriberping_interval = 20       # 0 disables keepalive pingsmax_frame = 1048576level = 6                # zlib level[pulse]enabled = trueinterval = 10            # fallback for an area without its own valuepulse.core              and pulse.web pulse.mail pulse.networkinterval = 5             # [pulse.connections], [pulse.nginx][collector]raw_dir = "/aegis/data/collector"interval = 30collector.net           and .nginx .mailenabled = true[web_admin]title = "Aegis"host = "0.0.0.0"port = 9981session_ttl_hours = 12cookie_name = "aegis_session"assets_dir = "public/assets/web-admin"log_tail_lines = 400

tasker.keep_hours applies only to done and cancelled rows: a failed task is what an operator returns to, so it stays until it is cleared on purpose. Workers above 1 are safe — a task owns its resource — but a host with little memory is better served by one or two.

bird.private_token is handed to the browser only after authentication, through /api/live; changing it invalidates open sockets, and the next page load picks the new one up.

The FTP and Supervisor sections follow the same pattern:

toml
[ftp]home_base = "/aegis/data/ftp"guest_user = "aegis-ftp"pasv_min = 40000pasv_max = 40100[supervisor]config_dir = "/aegis/config/supervisor"log_dir = "/aegis/logs/supervisor"run_dir = "/aegis/run/supervisor"

#Precedence summary

text
code default  →  config/aegis.toml              →  config/<area>.toml   (web, mail, db, dns, tls, misc, …)              →  config/server.toml   (what the installer wrote on this machine)              →  explicit CLI flag

server.toml wins over every area file, and aegis setup only writes the keys it asked about — an area file keeps its own defaults until someone changes them.

Nothing is taken from the environment except AEGIS_HOST, AEGIS_PASS, AEGIS_TARGET for bin/deploy.sh and AEGIS_PYTHON for bin/aegis-prepare.