Aegis documentation

#Command line

text
./bin/aegis <command> [options]
GroupPurpose
installverify the host, run the setup, build applications
thorcatalog, downloads, bundled runtime
cubesmanage an installed application
keepersupervise daemons
collectorcollect and store platform counters
pulsesample the platform for the live feed
taskerrun and inspect tasks
syshost-level operations (permissions)
sslcertificates for services
geoipMaxMind databases
webnginx vhosts and PHP versions
dbSQLite databases of the panel
docsbuild and serve the documentation
web-adminrun the panel
status, check, restartone-screen state, health check, full restart
build, configure, setupthe install phases, one at a time

#aegis install

bash
aegis install                 # checks -> prompts -> build every selected appaegis install nginx           # one app and its libraries, no promptsaegis install openssl         # a library on its own

What happens with no argument:

  • verification/server, verification/vendor, core/requirements;
  • setup/config — IP confirmation, geo lookup, primary domain, hostname,
  • timezone, application multi-select, database backend for postfix/dovecot;

  • base/toolchain, then one apps/<name> step per missing application in
  • dependency order.

    Current values are pre-filled when server.toml already exists; pressing Enter keeps everything.

    Exit codes: 0 success, 1 aborted or invalid configuration, 130 cancelled.


    #aegis status

    bash
    aegis status            # keeper, services with pid and uptime, scheduled jobsaegis --json status     # the same as data

    One screen for the state of the platform: whether the keeper daemon runs (and for how long), whether every supervised service is up, how long each one has been up, and when the scheduled jobs last ran.


    #aegis configure

    bash
    aegis configure            # configure every selected application + keeperaegis configure nginx      # one application only

    Runs the cube configure of each application, in dependency order, then the services/keeper step: boot hook, keeper daemon, and a check that every supervised service is running. Idempotent; it is the phase aegis install runs after the build.


    #aegis thor

    bash
    aegis thor apps                       # catalog with local artifact stateaegis thor download                   # fetch missing artifactsaegis thor download nginx             # one appaegis thor runtime status             # interpreter, packages, modulesaegis thor runtime prepare --force    # rebuild the bundled runtime

    thor is what bin/aegis-prepare calls:

    bash
    ./bin/aegis-prepare./bin/aegis-prepare --forceAEGIS_PYTHON=/usr/bin/python3.12 ./bin/aegis-prepare

    #aegis cubes

    bash
    aegis cubes list                      # cubes available on this installationaegis cubes help                      # one line per cubeaegis cubes help mail                 # commands and examples for one cubeaegis cubes mail help                 # the same, from the cube sideaegis cubes bind --help               # argparse help, with an examples block

    Every cube answers help with its description, the full command list and copy-paste examples; --help ends with the same examples.

    Every cube answers expose, validate and reload, and usually also configure, start, stop, restart, status.

    expose prints where the application lives, whether it runs, its pid, the configuration and log paths — and publishes its commands into <aegis.bin_dir> (/aegis/bin by default), so nginx, dig, certbot work from any shell that has that directory on PATH:

    bash
    aegis cubes nginx exposecube           nginxinstalled      /aegis/apps/web/nginx/1.30configuration  /aegis/config/nginxstate          running pid 732003pid            732003log            /aegis/logs/nginx/error.logmain config    /aegis/config/nginx/nginx.confvhosts         6json log       /aegis/logs/nginx/access_json.logpublished      /aegis/bin/nginx
    bash
    aegis cubes bind configureaegis cubes bind validateaegis cubes bind reloadaegis cubes bind statusaegis cubes nginx configureaegis cubes nginx reload

    Grouped commands live under their own cube:

    bash
    aegis cubes postgresql databases listaegis cubes mariadb databases create shopaegis cubes postfix relays listaegis cubes postfix security add header "X-Spam-Flag: YES" --action rejectaegis cubes postfix hooks add audit --handler /usr/local/bin/audit.shaegis cubes opendkim keys generate example.comaegis cubes opendkim keys publishaegis cubes mail domains add example.comaegis cubes mail mailboxes add postmaster@example.com --password 'secret123'aegis cubes mail aliases add info@example.com postmaster@example.comaegis cubes mail storage usage

    See the per-cube documents under cubes/ for the full surface: bind, nginx, certbot, php, postgresql, mariadb, postfix, dovecot, opendkim, postsrsd and mail.


    #aegis keeper

    bash
    aegis keeper services      # table: service, state, pid fileaegis keeper start         # start the supervisor in the backgroundaegis keeper statusaegis keeper stopaegis keeper restartaegis keeper daemon        # run the loop in the foreground (debugging)aegis keeper enable        # install /etc/init.d/aegis-keeperaegis keeper disable

    The loop restarts any registered service that is down, every 10 seconds, and logs to <logs>/keeper.log.


    #aegis ssl

    bash
    aegis ssl list                         # local certificates and remaining daysaegis ssl show example.com             # what a service would get for this nameaegis ssl ensure 203.0.113.10          # local self-signed certificate for an IPaegis ssl ensure intranet --san=intranet.local --san=10.0.0.5aegis ssl ensure intranet --force      # regenerate

    show prefers a Let's Encrypt lineage when one exists and falls back to a local certificate; it prints source, paths and remaining days.


    #aegis geoip

    bash
    aegis geoip status                 # which databases are presentaegis geoip update                 # GeoLite2-Country (default)aegis geoip update --edition city --edition asn

    Downloads come from download.maxmind.com using geoip.license_key and land flat in geoip.dir (GeoLite2-Country.mmdb, …). nginx picks the Country database up on the next cubes nginx configure.

    #aegis db

    bash
    aegis db listaegis db info panelaegis db create extraaegis db drop extraaegis db migrateaegis db migrate --database panelaegis db seedaegis db statusaegis db rollback --steps 1aegis db freshaegis db make:migration add_hosts_tableaegis db make:seeder DefaultsSeeder

    #aegis tasker

    bash
    aegis tasker status               # counts per stateaegis tasker list --limit 20      # recent tasksaegis tasker show 42 --lines 40   # one task with its logaegis tasker run command '["/bin/true"]' --name smokeaegis tasker run internal web.vhost.create --arg vhost_id=3aegis tasker run webhook https://example.org/hook --arg body='{"x":1}'aegis tasker cancel 42            # cancel a pending task, or a running containeraegis tasker retry 42             # queue a failed task againaegis tasker daemon               # run the loop in the foreground

    run --wait follows the task and exits with its status. Every panel write is a task too; see tasker.md.

    #aegis sys

    bash
    aegis sys perms --path /home/john/www --checkaegis sys perms --path /home/john/www --fixaegis sys perms --path /home/john/www --to johnaegis sys perms --path /srv/shared --everyone --dry-run

    sys is the home for operations on the host itself; perms grants or inspects access to a tree with ACLs. See permissions.md.

    #aegis pulse

    bash
    aegis pulse status            # what each area published lastaegis pulse daemon            # foreground

    Samples the platform and publishes each area through Bird. See live.md.

    #aegis collector

    bash
    aegis collector status        # the sampling daemons and their storageaegis collector list          # stored counters

    #aegis web

    bash
    aegis web vhosts listaegis web vhosts create --domain=example.com --location=php-mvc

    The same operations the Web section of the panel performs; see cubes/nginx.md.

    #aegis web-admin

    bash
    aegis web-admin setup         # dependencies, first admin account, data filesaegis web-admin start         # background, default 0.0.0.0:9981aegis web-admin stopaegis web-admin restartaegis web-admin statusaegis web-admin passwd        # change an account password

    The panel itself: panel.md.

    #aegis docs

    bash
    aegis docs build              # Markdown in docs/ -> HTML in public/docsaegis docs web                # build, then serve it locally

    The site is generated from this directory; the sidebar order is written by hand in app/modules/docs/pages.py.

    #aegis check, aegis restart

    bash
    aegis check                   # every health check, with the command that fixes itaegis restart                 # keeper, every supervised service, then the panel

    check exits non-zero when something is wrong. restart stops the keeper first, so it does not race the restarts, and leaves the panel for last.


    #bin/deploy.sh

    bash
    ./bin/deploy.sh                    # code + vendor./bin/deploy.sh --full             # also the local runtime tree./bin/deploy.sh --delete           # delete remote files missing locally

    Environment: AEGIS_HOST, AEGIS_PORT, AEGIS_USER, AEGIS_TARGET, AEGIS_PASS. Uses rsync when the server has it and falls back to tar over ssh.


    #--json

    Every command accepts a global --json flag and prints one JSON object on stdout instead of the human lines:

    bash
    ./bin/aegis --json cubes list"ok": true "cubes": "bind" "certbot" "nginx"./bin/aegis --json cubes nginx config get workers"ok": true "cube": "nginx" "result": "workers=auto"./bin/aegis --json cubes nginx config get nope"ok": false "cube": "nginx" "error": "unknown setting: nope"

    The exit code keeps its meaning, so a script can check ok or the status without parsing text. Errors are never written to stderr in this mode.

    #Exit codes and output

  • normal output goes to stdout, diagnostics to stderr;
  • a failing task prints its detail under the task line (up to 12 lines), so the
  • compiler error itself is visible, not just the make summary;

  • Ctrl+C always prints cancelled and exits 130.