Aegis documentation

#account

The account group owns the registry that ties one Linux user to everything it owns: domains, sites, databases, mailboxes, cron jobs, Supervisor programs, SSH keys and FTP users. It creates the user and the home tree, moves the account between active, suspended and deleted, and drives the per-account groups.

Rendering a vhost, writing a DNS zone or creating a mailbox stays with the web, dns and mail modules. What this group records is the association, so "whose vhost is this?" has exactly one place to answer.

bash
aegis account <command> options

#Invocation and the two spellings

The first token after account is either a command or an account name. A dispatcher decides before argparse runs, because a subparser tree cannot tell account create from account john db list.

bash
aegis account list                  # a commandaegis account john                  # an account name: same as `show`aegis account john db list          # account, group, verbaegis account cron list john        # group, verb, account
formexampleavailable for
commandaegis account create johncreate, list, show, info, suspend, resume, delete, cron, supervisor, check, repair, help
scopedaegis account john <group> …domains, sites, db, mail, cron, supervisor, perms, quota, ssh, ftp, backup
account-firstaegis account cron <verb> john …cron and supervisor only

Rules that follow from the dispatcher:

  • cron and supervisor are the only groups with a cross-account form. Every
  • other group is reached through the account name.

  • check and repair exist only at the top level; aegis account john check
  • answers unknown account command: check.

  • With no group after the account name, the account is shown:
  • aegis account john equals aegis account show john.

  • After the account name, show/info and delete/remove are aliases, and
  • in mail so are boxes/mailboxes.

  • An account name that is also a command word (list, create, cron) can
  • never be addressed: the word is taken as a command. Pick another name.

  • Names are case-insensitive; store.get lowercases before looking up.
  • The built-in short help exists because argparse cannot describe the two-level syntax:

    bash
    aegis account help
    argumentdefaultmeaning
    ——the command takes no options
    bash
    aegis account helpaegis account help   # when `--help` is not enough
    text
    ℹ aegis account create <username> [--password=…] [--ssh=yes|no] [--home=/path] [--quota-mb=N]ℹ aegis account list [--status=active|suspended|deleted]ℹ aegis account show <username>ℹ aegis account suspend|resume <username> [--note=…]ℹ aegis account delete <username> [--purge --yes]

    #The identity model

    An account has two names with two different jobs.

    fieldvaluechanges
    slugthe Linux user, for example johnalmost never
    identifieraegis-acc- plus 16 hex charactersnever
    bash
    aegis account show john
    text
    account     johnidentifier  aegis-acc-3f9c21ab77d04e15status      activehome        /home/johnlinux user  uid 1042, gid 1042, shell /bin/bashssh         yesshell       /bin/bashquota       20480 MBsites       1databases   1ftp         1

    A slug is validated before anything touches the host:

  • lowercase letters, digits, _ and -;
  • starts with a letter;
  • 2 to 31 characters in total;
  • not one of the names the platform itself owns — aegis, aegis-www,
  • root, daemon, bin, sys, nobody, www-data, mysql, mariadb, postgres, postgresql, redis, mail, postfix, dovecot, named, bind, ftp, vsftpd, supervisor, tasker, keeper, bird, pulse, collector, installer.

    The identifier is generated once, from eight random bytes, and is never derived from the slug. Renaming the account later therefore keeps every vhost, zone and mailbox attached to it.

    Every other database stores account_hash = "<slug>:<identifier>" with no foreign key, because the files are separate SQLite databases:

    databasetablecolumn
    web.dbnginx_vhostsaccount_hash, site_slug
    web.dbphp_poolsaccount_hash, site_slug
    dns.dbdns_zonesaccount_hash

    The registry itself is /aegis/database/storage/account/main.db:

    tableholds
    accountsslug, identifier, uid/gid, home, status, quotas, SSH
    account_domainsone row per domain: primary, addon, alias, subdomain
    account_sitesa name, one primary domain, UNIQUE(account_id, name)
    account_databasesserver (mariadb/postgresql), name, owner role
    account_ftp_accountsusername, home, quota
    account_ssh_keysone authorized key per row
    account_eventswho did what, when
    account_purgedone line per purged account, kept after the row is gone

    Statuses:

    statusmeaning
    activenormal
    suspendedthe flag the modules read: vhosts disabled, database roles locked, mailboxes deactivated, shell replaced, cron parked
    deletedkept for the record; the name is still taken

    The home tree is created with the user:

    text
    /home/john/├── htdocs/     # the document root of a plain site├── logs/├── tmp/        # mode 0700├── ssl/        # mode 0700└── backups/    # mode 0700

    #Output, JSON and exit codes

    Normal output goes to stdout; diagnostics (⚠, ✖) go to stderr. A finished step starts with ✔ and neutral information with ℹ.

    --json is accepted in two positions:

  • before the group, as the global flag: aegis --json account list;
  • anywhere on the account line, because the dispatcher strips the token before
  • the sub-parser sees it: aegis account list --json, aegis account john db list --json.

    The payload is printed as one JSON object on stdout. The account fields it may contain are slug, identifier, home, status, quota_mb, ssh_enabled, shell and created_at; notes and internal counters stay out.

    One caveat, visible in the code: create, suspend, resume and delete suppress their human lines in JSON mode. list, show/info, the per-account groups (domains, sites, db, mail, cron, supervisor, perms, quota, ssh, ftp, backup) and check/repair emit the payload and then print their usual table or message as well. When a script consumes those, read the first line of stdout as the object and ignore the rest.

    A command that reports a failure with a message prints this object on stdout and the same message on stderr, with exit code 1:

    text
    {"ok": false, "command": "account.domains.add", "error": "domain already added: example.com"}

    Commands that compute a problem list (account.perms.check, account.check) set ok: false and keep their payload; account.backup.create reports ok: false but still exits 0.

    exit codemeaning
    0the command finished
    1a command reported a failure
    2argparse rejected the arguments (missing value, unknown flag)
    130interrupted with Ctrl+C

    #Creating and inspecting accounts

    #aegis account create

    Creates the Linux user, the home tree, optionally the password, and the registry row. Every step is idempotent, so a run interrupted halfway is resumed by repeating the same command; only the registry row refuses a second run, because it carries the identifier that must stay unique.

    bash
    aegis account create <username> --password=<secret> --ssh=yes|no                     --home=<path> --quota-mb=<n> --notes=<text>
    argumentdefaultmeaning
    <username>—the slug; validated as described above
    --passwordemptypassed to chpasswd through stdin, never argv; omitted means no password step
    --sshnoyes gives the account /bin/bash, no gives /usr/sbin/nologin
    --home/home/<username>home directory passed to useradd --home-dir
    --quota-mb0stored on the account row; quota show compares usage against it
    --notesemptystored in the row; not printed by show and not part of the JSON payload

    The steps, in order:

  • linux user — useradd --create-home --user-group, or already exists;
  • home tree — htdocs, logs, tmp, ssl, backups, owned by the user;
  • password — only when --password was given;
  • registry — the row, then uid and gid from getpwnam.
  • bash
    aegis account create john --password='correct horse battery staple'aegis account create anna --ssh=yes --home=/srv/anna --quota-mb=20480     --notes='paid 2026-11'
    text
    account creation · john  [●●●●]  4/4✔ account john created · aegis-acc-3f9c21ab77d04e15 · /home/john

    The timeline is written to stderr and is silent when stderr is not a terminal. --ssh=yes does not install a key; add one with aegis account john ssh add.

    #aegis account list

    Every account, alphabetical, with its identifier, state and home. deleted rows are included unless a filter is given.

    bash
    aegis account list --status=<status>
    argumentdefaultmeaning
    --statusemptyfilter by the exact string; active, suspended and deleted match rows, anything else matches nothing
    bash
    aegis account listaegis account list --status=suspended
    text
    account  identifier                  status     home───────  ──────────────────────────  ─────────  ───────────anna     aegis-acc-1c04e5d29ab87310  active     /srv/annajohn     aegis-acc-3f9c21ab77d04e15  active     /home/johnmaria    aegis-acc-7b2f90c4de118a63  suspended  /home/maria

    When there is nothing to show, the command prints ℹ no accounts. Columns are separated by two spaces and padded to the widest cell; the rule under the header is ─ on a Unicode terminal.

    #aegis account show

    One account: the identity block, the Linux user as the host sees it, the counters, and the ten newest audit events.

    bash
    aegis account show <username>aegis account info <username>
    argumentdefaultmeaning
    <username>—the slug
    bash
    aegis account show johnaegis account info maria
    text
    account     johnidentifier  aegis-acc-3f9c21ab77d04e15status      activehome        /home/johnlinux user  uid 1042, gid 1042, shell /bin/bashssh         yesshell       /bin/bashquota       20480 MBsites       1databases   1ftp         1when                       action          target        detail─────────────────────────  ──────────────  ────────────  ──────────────────────────2026-11-12T18:05:10+00:00  site.create     john/example  example.com2026-11-12T18:03:44+00:00  domain.add      example.com   primary2026-11-10T09:14:02+00:00  account.create  john          aegis-acc-3f9c21ab77d04e15

    linux user reads missing when the registry has a row but the host has no such user. quota reads none when quota_mb is zero. Unknown name: ✖ unknown account: john, exit 1.

    #aegis account suspend

    Marks the account suspended and applies the effects: vhosts disabled, every database role locked, mailboxes deactivated, login shell replaced by /usr/sbin/nologin, and the cron drop-in renamed to aegis-<account>.off. Nothing is deleted.

    bash
    aegis account suspend <username> --note=<text>
    argumentdefaultmeaning
    <username>—the slug
    --noteemptystored in the account.suspended audit event
    bash
    aegis account suspend johnaegis account suspend maria --note='invoice 2026-10 unpaid'
    text
    ✔ account john suspendedℹ 2 vhosts disabledℹ 1 database roles lockedℹ 2 mailboxes disabledℹ shell /usr/sbin/nologinℹ cron parked

    An effect that fails is reported as its own line (effects failed: …) and the command still exits 0, because the state change itself succeeded.

    #aegis account resume

    Brings a suspended account back to active and restores exactly what suspension changed.

    bash
    aegis account resume <username> --note=<text>
    argumentdefaultmeaning
    <username>—the slug
    --noteemptystored in the account.resumed audit event
    bash
    aegis account resume johnaegis account resume maria --note='payment received'
    text
    ✔ account john activeℹ 2 vhosts enabledℹ 1 database roles unlockedℹ 2 mailboxes enabledℹ shell /bin/bashℹ cron restored

    The restored shell is /bin/bash only for an account with ssh_enabled; the rest are returned to /usr/sbin/nologin. cron restored requires a parked file; without one the line is no parked cron.

    #aegis account delete

    Destructive. --purge deletes the Linux user, the home tree, every Supervisor program, the cron file, the maildirs and mail domains, the FTP users, and then the registry row and its children. The data cannot be recovered from this command.

    Marks the account deleted; --purge also removes everything the account owns and frees the name. A purge writes one line to account_purged so the audit survives the account it describes.

    bash
    aegis account delete <username> --purge --yes
    argumentdefaultmeaning
    <username>—the slug
    --purgeoffremove user, home, programs, cron, mail and FTP users, then the rows
    --yesoffrequired with --purge; without it the command refuses and changes nothing
    bash
    aegis account delete mariaaegis account delete maria --purge --yes
    text
    ✔ account maria deleted (rows kept)
    text
    ✔ account maria deleted and purged

    Refusal without confirmation:

    text
    ✖ purging deletes the Linux user and the home: pass --yes

    The purge steps, visible in --json under steps, are: programs removed, cron file cleared or no schedule, maildirs and mail domains removed, FTP users removed, the user removed with the home, the tree deleted or already gone. There is no rollback: a failure part-way leaves the steps already done in place and the command exits 1.

    aegis account john remove is the scoped spelling of the same command; there is no top-level aegis account remove.

    #domains

    Every domain is a row owned by the account. With --dns the command also creates the zone through the dns module and stamps account_hash on dns_zones; without it the domain is only a reference.

    #aegis account <account> domains list

    bash
    aegis account <account> domains list
    argumentdefaultmeaning
    ——the group defaults to list
    bash
    aegis account john domains listaegis account anna domains
    text
    domain            kind       dns  mail  status────────────────  ─────────  ───  ────  ──────example.com       primary    yes  yes   activeshop.example.com  subdomain  no   yes   active

    dns is dns_managed — whether this account created the zone. mail is mail_enabled, an ownership flag; mail domains add is what actually creates the mail domain. Nothing is printed when the account has no domains.

    #aegis account <account> domains add

    bash
    aegis account <account> domains add <domain> --kind=<kind> --dns
    argumentdefaultmeaning
    <domain>—validated by the bind zone-name checker
    --kindprimaryprimary, addon, alias or subdomain
    --dnsoffcreate and serve the DNS zone, then record the account as its owner
    bash
    aegis account john domains add example.comaegis account john domains add shop.example.com --kind=subdomain --dns
    text
    ✔ domain shop.example.com added

    Failures are reported as one line: domain already added: example.com, or a dns module error. --dns needs a working dns module; a failure there leaves no domain row behind. --kind is checked by argparse first, so an unsupported value is a usage error (exit 2), not a runtime message.

    #aegis account <account> domains remove

    Destructive. Removes the domain row; with --dns it also removes the DNS zone and every record in it.

    bash
    aegis account <account> domains remove <domain> --dns
    argumentdefaultmeaning
    <domain>—must belong to this account
    --dnsoffalso remove the zone, when the row says this account manages it
    bash
    aegis account john domains remove shop.example.comaegis account john domains remove shop.example.com --dns
    text
    ✔ domain shop.example.com removed

    A domain used as the primary domain of a site is protected:

    text
    ✖ shop.example.com is the primary domain of a site; delete the site first

    #aegis account <account> sites list

    bash
    aegis account <account> sites list
    argumentdefaultmeaning
    ——the group defaults to list
    bash
    aegis account john sites listaegis account anna sites
    text
    site     domain            vhosts───────  ────────────────  ────────────example  example.com       john-exampleshop     shop.example.com  john-shop

    The vhosts column lists the rows in web.db with the same account_hash and site_slug, joined with , . Empty accounts print nothing.

    #aegis account <account> sites create

    Creates the site tree, the vhost and — unless --no-apply — renders and reloads nginx. The domain must already belong to the account.

    bash
    aegis account <account> sites create <domain> --name=<site>                              --php=<series> --preset=<shape>                              --docroot=<dir> --queue --no-apply
    argumentdefaultmeaning
    <domain>—must already be a domain of this account
    --namederived from the domainwww.example.com becomes example; lowercased, and the derived name is at most 31 characters
    --phpconfig php.versionPHP series the vhost serves with, for example 8.5; must be installed and enabled
    --presetstatic, or php when --php is givenstatic, php or laravel
    --docroothtdocs, public for laraveldirectory inside the site that nginx serves
    --queueoffadd a Supervisor program running artisan queue:work; needs a PHP series
    --no-applyoffwrite the rows and files but skip web apply
    bash
    aegis account john sites create example.com --preset=staticaegis account john sites create shop.example.com --preset=laravel     --php=8.5 --queue
    text
    ✔ site shop created · /home/john/shop · vhost john-shop · php 8.5 · queue on

    What lands where:

    itemvalue
    site tree/home/{account}/{site}/ plus logs, tmp, ssl
    Laravel extrastorage/framework/{cache,sessions,views}, storage/logs, bootstrap/cache
    placeholderindex.html in the document root, owned by the account
    vhostnamed {account}-{site}, the domain as its only server_name
    ownershipaccount_hash and site_slug stamped on the vhost
    ACLsaegis-www and the account, in both directions, with default entries
    queue program{account}_{site}_queue, running php artisan queue:work --sleep=3 --tries=3

    Common refusals:

    text
    ✖ add the domain first: shop.example.com✖ site already exists: john/shop✖ unknown preset: api (use static, php, laravel)✖ --queue needs PHP: pass --php or a preset✖ unknown PHP version: 8.2 (available: 8.5)

    --preset=static with --queue and no --php is refused: the static preset never selects a PHP series.

    #aegis account <account> sites delete

    Destructive. --purge deletes the whole site directory, not only the row and the vhost.

    bash
    aegis account <account> sites delete <site> --purge --yes --no-apply
    argumentdefaultmeaning
    <site>—the site name, not the domain
    --purgeoffdelete /home/{account}/{site} and everything in it
    --yesoffrequired with --purge
    --no-applyoffskip the nginx reload
    bash
    aegis account john sites delete exampleaegis account john sites delete shop --purge --yes
    text
    ✔ site shop removed

    The queue program {account}_{site}_queue is removed when it exists; a static site simply has none. Refusal without confirmation:

    text
    ✖ purging deletes the site files: pass --yes

    #db

    Databases are created and dropped through the postgresql and mariadb cubes. Every name is prefixed with the account slug, and the owner role gets a grant on that database only.

    #aegis account <account> db list

    bash
    aegis account <account> db list --server=<engine>
    argumentdefaultmeaning
    --serverboth enginespgsql, postgres, postgresql, mariadb or mysql
    bash
    aegis account john db listaegis account john db list --server=pgsql
    text
    database  server      owner     created────────  ──────────  ────────  ─────────────────────────john_app  postgresql  john_app  2026-11-12T18:20:31+00:00john_wp   mariadb     john_wp   2026-11-13T08:02:10+00:00

    #aegis account <account> db create

    Creates the database, its owner role and the grant, then records the pair. The password is printed once and never stored in the registry.

    bash
    aegis account <account> db create <name> --server=<engine>                              --username=<role> --password=<secret>
    argumentdefaultmeaning
    <name>—stored as {account}_{name}; - becomes _
    --serverrequiredengine alias, as in db list
    --usernamethe database namerole stored as {account}_{username}
    --passwordgenerateda random token_urlsafe(12) when omitted
    bash
    aegis account john db create app --server=pgsqlaegis account john db create wp --server=mariadb --username=blog --password='db-s3cret'
    text
    ✔ database john_app created · user john_app · password Q3f9c21ab77d04e1

    Names are cut to what the engine accepts: 63 characters for PostgreSQL, 64 for MariaDB, including the {account}_ prefix. A create that finds its database already there but its role missing finishes the role and reports role already existed; password and grant reset in the detail field of the JSON payload.

    #aegis account <account> db drop

    Destructive. Drops the database and its data, then removes the owner role. There is no dump in between.

    bash
    aegis account <account> db drop <name> --server=<engine> --yes
    argumentdefaultmeaning
    <name>—bare or already prefixed; both are found
    --serverrequiredengine alias
    --yesoffrequired; without it the command refuses and changes nothing
    bash
    aegis account john db drop app --server=pgsql --yesaegis account john db drop john_wp --server=mariadb --yes
    text
    ✔ database john_app dropped
    text
    ✖ dropping a database deletes its data: pass --yes

    #mail

    Mail data lives in PostgreSQL behind the mail cube. These commands check that a domain or address belongs to the account before handing it over.

    #aegis account <account> mail domains list

    bash
    aegis account <account> mail domains listaegis account <account> mail
    argumentdefaultmeaning
    ——mail defaults to domains, and domains to list
    bash
    aegis account john mail domains listaegis account john mail
    text
    domain       active  mailboxes───────────  ──────  ─────────example.com  1       3

    Only domains with mail_enabled = 1 that also exist in the mail cube appear.

    #aegis account <account> mail domains add

    Creates the mail domain and marks the account domain as mail-enabled. The account domain must exist first.

    bash
    aegis account <account> mail domains add <domain>
    argumentdefaultmeaning
    <domain>—must already be a domain of this account
    bash
    aegis account john mail domains add example.comaegis account john mail domains add shop.example.com
    text
    ✔ domain example.com created
    text
    ✖ add the domain first: shop.example.com

    #aegis account <account> mail domains remove

    Destructive. Removes the mail domain, its mailboxes, aliases, forwards and relocated addresses, and its TLS policy. The account domain row stays.

    bash
    aegis account <account> mail domains remove <domain>
    argumentdefaultmeaning
    <domain>—must be a mail domain of this account
    bash
    aegis account john mail domains remove example.comaegis account john mail domains delete old.example.com
    text
    ✔ domain example.com removed

    #aegis account <account> mail boxes list

    bash
    aegis account <account> mail boxes list --domain=<domain>aegis account <account> mail mailboxes list --domain=<domain>
    argumentdefaultmeaning
    --domainall owned domainsrestrict the listing to one domain
    bash
    aegis account john mail boxes listaegis account john mail boxes list --domain=example.com
    text
    address                 active  quota       name──────────────────────  ──────  ──────────  ──────────john@example.com        1       1073741824  John Doepostmaster@example.com  1       1073741824  Postmaster

    quota is printed in bytes, as the cube stores it.

    #aegis account <account> mail boxes add

    bash
    aegis account <account> mail boxes add <address> --password=<secret>                                     --quota-mb=<n> --name=<display>
    argumentdefaultmeaning
    <address>—an address whose domain this account owns
    --passwordrequiredat least 8 characters; hashed by the cube before storage
    --quota-mb0converted to bytes; 0 takes the domain default
    --nameemptydisplay name
    bash
    aegis account john mail boxes add info@example.com --password='mail-s3cret'aegis account john mail boxes add john@example.com --password='mail-s3cret'     --quota-mb=1024 --name='John Doe'
    text
    ✔ mailbox john@example.com created (quota 1073741824 bytes)

    A quota above the domain limit is refused by the cube with the limit in the message; a missing mail domain answers no such mail domain: example.com, and a password shorter than 8 characters answers password must be at least 8 characters.

    #aegis account <account> mail boxes remove

    Destructive. Deletes the mailbox row. The maildir stays on disk for the operator.

    bash
    aegis account <account> mail boxes remove <address>
    argumentdefaultmeaning
    <address>—an address of this account
    bash
    aegis account john mail boxes remove info@example.comaegis account john mail boxes delete temp@example.com
    text
    ✔ mailbox info@example.com removed (maildir left in place)

    #aegis account <account> mail boxes password

    bash
    aegis account <account> mail boxes password <address> --password=<secret>
    argumentdefaultmeaning
    <address>—an address of this account
    --passwordrequiredat least 8 characters; the new password
    bash
    aegis account john mail boxes password john@example.com --password='new-pass'aegis account john mail boxes password info@example.com --password="$(openssl rand -base64 18)"
    text
    ✔ password updated for john@example.com

    #aegis account <account> mail boxes quota

    bash
    aegis account <account> mail boxes quota <address> --quota-mb=<n>
    argumentdefaultmeaning
    <address>—an address of this account
    --quota-mbrequirednew quota in MiB; converted to bytes
    bash
    aegis account john mail boxes quota john@example.com --quota-mb=2048aegis account john mail boxes quota info@example.com --quota-mb=512
    text
    ✔ quota for john@example.com set to 2147483648 bytes

    #aegis account <account> mail forwards list

    bash
    aegis account <account> mail forwards list
    argumentdefaultmeaning
    ——the group defaults to list
    bash
    aegis account john mail forwards listaegis account john mail forwards
    text
    address            destination       keep local  active─────────────────  ────────────────  ──────────  ──────sales@example.com  john@example.com  1           1

    #aegis account <account> mail forwards add

    bash
    aegis account <account> mail forwards add <source> --to=<destination>
    argumentdefaultmeaning
    <source>—an address of this account
    --torequireddestination address
    bash
    aegis account john mail forwards add sales@example.com --to=john@example.comaegis account john mail forwards add billing@example.com --to=finance@example.org
    text
    ✔ forward sales@example.com -> john@example.com (keeping a local copy)

    The account command always keeps a local copy; it exposes no flag to change that.

    #aegis account <account> mail forwards remove

    Destructive. Removes the forward, or every forward of the address when --to is omitted.

    bash
    aegis account <account> mail forwards remove <source> --to=<destination>
    argumentdefaultmeaning
    <source>—an address of this account
    --toemptyremove only this destination; omitted removes them all
    bash
    aegis account john mail forwards remove sales@example.com     --to=john@example.comaegis account john mail forwards remove sales@example.com
    text
    ✔ forward removed for sales@example.com

    #cron

    Cron jobs are written to one drop-in per account, /etc/cron.d/aegis-{account} (or account.cron_dir). Each line is <schedule> <account> <command> with an # id: N comment above it, so the file stays reviewable as text.

    Both spellings reach the same code:

    bash
    aegis account <account> cron <verb> aegis account cron <verb> <account> 

    The account-first form takes the verb first: aegis account cron john list is read as verb john and answers unknown command: john. Without an account after the verb, the form answers usage: account cron list|add|remove <account>.

    #aegis account cron list

    bash
    aegis account <account> cron listaegis account cron list <account>
    argumentdefaultmeaning
    ——the group defaults to list
    bash
    aegis account john cron listaegis account cron list john
    text
    id  schedule    user  command                   note──  ──────────  ────  ────────────────────────  ──────────────1   @daily      john  /home/john/bin/backup.sh  nightly backup2   30 3 * * *  john  /home/john/bin/prune.sh

    Numbers are assigned in file order on every read and are what remove takes. An account without a cron file prints nothing.

    #aegis account cron add

    bash
    aegis account <account> cron add <schedule> --command=<command>                                     --comment=<text>aegis account cron add <account> <schedule> --command=<command>                         --comment=<text>
    argumentdefaultmeaning
    <schedule>—five fields, or one of @reboot, @yearly, @annually, @monthly, @weekly, @daily, @midnight, @hourly
    --commandrequiredone line; a newline is refused
    --commentemptywritten above the job as # id: N <comment>
    bash
    aegis account john cron add '@daily' --command='/home/john/bin/backup.sh'     --comment='nightly backup'aegis account cron add john '30 3 * * *' --command='/home/john/bin/prune.sh'
    text
    ✔ job 1 added: @daily /home/john/bin/backup.sh

    Refusals:

    text
    ✖ a schedule needs five fields or a word like @daily: 'every day'✖ invalid schedule field: '30x'✖ a command may not contain a newline

    #aegis account cron remove

    Destructive. Removes the job line and renumbers the rest.

    bash
    aegis account <account> cron remove <id>aegis account cron remove <account> <id>
    argumentdefaultmeaning
    <id>—the number shown by cron list
    bash
    aegis account john cron remove 2aegis account cron remove john 1
    text
    ✔ job 2 removed
    text
    ✖ unknown job: 9

    #supervisor

    A program is one Supervisor drop-in named {account}_{program}.conf, running as the account. Adding or removing one asks Supervisor to reread and update, so running programs keep running.

    Both spellings work, as for cron:

    bash
    aegis account <account> supervisor <verb> aegis account supervisor <verb> <account> 

    Without an account after the verb, the form answers usage: account supervisor list|add|remove <account>.

    #aegis account supervisor list

    bash
    aegis account <account> supervisor listaegis account supervisor list <account>
    argumentdefaultmeaning
    ——the group defaults to list
    bash
    aegis account john supervisor listaegis account supervisor list john
    text
    program  command                      directory   autostart───────  ───────────────────────────  ──────────  ─────────worker   /home/john/bin/worker        /home/john  truecleanup  /home/john/bin/cleanup --all  /home/john  false

    program is the short name: the {account}_ prefix is stripped. A program added with --no-autostart shows false. An account without programs prints nothing.

    #aegis account supervisor add

    bash
    aegis account <account> supervisor add <program> --command=<command>                                      --directory=<path> --no-autostartaegis account supervisor add <account> <program> --command=<command>                              --directory=<path> --no-autostart
    argumentdefaultmeaning
    <program>—stored as {account}_{program}; - becomes _; the full name must fit 32 characters
    --commandrequiredstored exactly as typed; Supervisor does not use a shell
    --directoryemptyworking directory of the process
    --no-autostartoffwrite autostart=false
    bash
    aegis account john supervisor add worker --command='/home/john/bin/worker'     --directory=/home/johnaegis account supervisor add john maintenance     --command='/home/john/bin/cleanup --all' --no-autostart
    text
    ✔ program john_worker written

    Re-running with the same name replaces the file: ✔ program john_worker replaced. A name that does not fit answers program name too long: 'john_this_program_name_is_far_too_long' (38 of 32).

    #aegis account supervisor remove

    Destructive. Deletes the program file and asks Supervisor to update.

    bash
    aegis account <account> supervisor remove <program>aegis account supervisor remove <account> <program>
    argumentdefaultmeaning
    <program>—the short name; {account}_ is added before the lookup
    bash
    aegis account john supervisor remove workeraegis account supervisor remove john maintenance
    text
    ✔ program john_worker removed

    #perms

    The tree is the home plus logs, tmp, ssl, backups and every site directory. Two grants are needed in both directions: aegis-www writes storage/ and uploads as the web account, while the operator runs artisan, git and composer as the account.

    #aegis account <account> perms check

    Read-only. Reports what the web account cannot reach.

    bash
    aegis account <account> perms checkaegis account <account> perms
    argumentdefaultmeaning
    ——perms defaults to check
    bash
    aegis account john perms checkaegis account john perms
    text
    ✔ permissions look correct

    When something is missing, a table is printed and the exit code is 1:

    text
    path             problem───────────────  ──────────────────────────────────────────────────────────────/home/john       no ACL entry for aegis-www (reachable through 'other' at most, never writable)/home/john/shop  no execute bit for aegis-www

    It runs check on every target, so one run reports the home, the four base directories and each site.

    #aegis account <account> perms fix

    Changes ownership metadata. Grants aegis-www and the account read/write/execute on every target, with default ACL entries so files created tomorrow by either side stay usable by the other. It does not change file contents.

    bash
    aegis account <account> perms fix --dry-run
    argumentdefaultmeaning
    --dry-runoffprint the setfacl lines without running them
    bash
    aegis account john perms fix --dry-runaegis account john perms fix
    text
    ℹ would run setfacl /home/john  (-R -m u:aegis-www:rwX)ℹ would run setfacl /home/john  (-m d:u:aegis-www:rwX)ℹ would run setfacl /home  (-m u:aegis-www:x)
    text
    ✔ 24 ACL grants applied on 6 paths

    This is the command to run when a site answers 403 or PHP cannot write after files were copied around. --dry-run prints one line per change, then exits 0.

    #quota

    #aegis account <account> quota show

    Reports three independent totals — the home tree measured with du, the databases asked from each engine, and the maildirs of the account's domains — plus the limit from the account row.

    bash
    aegis account <account> quota showaegis account <account> quota
    argumentdefaultmeaning
    ——quota defaults to show; it is the only verb
    bash
    aegis account john quota showaegis account john quota
    text
    group      where        used─────────  ───────────  ──────home       /home/john   1.4Gdatabases  2 databases  96.2Mmail       maildirs     312.0Mtotal                   1.8Glimit                   20.0Gfree                    18.2Gdatabase  server      size────────  ──────────  ──────john_app  postgresql  84.1Mjohn_wp   mariadb     12.1M

    Sizes are printed as 512B, 48.3M or 1.2G: one unit, and one decimal above bytes. Without a quota the limit and free rows are omitted and the command ends with ℹ no quota set on this account. The database table appears only when the account owns databases.

    #ssh

    The key list lives in account_ssh_keys and ~/.ssh/authorized_keys is rendered from it. A key never grants a login on its own: the shell has to be a real one, which --ssh=yes or ssh enable decides.

    #aegis account <account> ssh list

    bash
    aegis account <account> ssh list
    argumentdefaultmeaning
    ——the group defaults to list
    bash
    aegis account john ssh listaegis account john ssh
    text
    id  name    fingerprint       key──  ──────  ────────────────  ────────────────────────────────────────────────────────────1   laptop  3f9c21ab77d04e15  ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIJ8kQ2m0Xr7pLwVd4tYb1nFc2   ci      8a71c0de4b2f9911  ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIBx4mQ2pVr7kLw9d1tYb8nFj

    The key column is cut at 60 characters without an ellipsis. The fingerprint is the first 16 hex characters of a SHA-256 over type + base64.

    #aegis account <account> ssh add

    bash
    aegis account <account> ssh add '<public-key>' --name=<label>
    argumentdefaultmeaning
    <public-key>—one line: ssh-ed25519 AAAA… comment
    --namekeylabel shown by ssh list
    bash
    aegis account john ssh add 'ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIJ8kQ2m0Xr7pLwVd4tYb1nFc john@laptop'     --name=laptopaegis account john ssh add "$(cat ~/.ssh/id_ed25519.pub)" --name=ci
    text
    ✔ key 3f9c21ab77d04e15 added
    text
    ✖ that does not look like a public key✖ that key is already added

    The key is stored and the file rewritten immediately; the login starts working only when the shell is a real one.

    #aegis account <account> ssh remove

    Destructive. Removes the key from the registry and rewrites authorized_keys.

    bash
    aegis account <account> ssh remove <id>
    argumentdefaultmeaning
    <id>—the number from ssh list; a non-number is an argparse error (exit 2)
    bash
    aegis account john ssh remove 2aegis account john ssh delete 1
    text
    ✔ key 2 removed
    text
    ✖ unknown key: 7

    #aegis account <account> ssh enable

    Gives the account /bin/bash and sets ssh_enabled, which is what account create --ssh=yes does at creation time. Existing keys start working immediately.

    bash
    aegis account <account> ssh enable
    argumentdefaultmeaning
    ——no options
    bash
    aegis account john ssh enableaegis account john ssh enable   # idempotent
    text
    ✔ ssh enabled

    #ftp

    FTP users are virtual: they are created through the vsftpd cube, named {account}_{user} (cut at 32 characters), and their home is under the FTP tree, not the account home.

    #aegis account <account> ftp list

    bash
    aegis account <account> ftp list
    argumentdefaultmeaning
    ——the group defaults to list
    bash
    aegis account john ftp listaegis account john ftp
    text
    user         home                         quota  status───────────  ───────────────────────────  ─────  ──────john_upload  /aegis/data/ftp/john_upload  0      active

    #aegis account <account> ftp add

    bash
    aegis account <account> ftp add <user> --password=<secret> --quota-mb=<n>
    argumentdefaultmeaning
    <user>—stored as {account}_{user}
    --passwordrequiredat least 8 characters; the FTP password
    --quota-mb0stored on the account's FTP row
    bash
    aegis account john ftp add upload --password='ftp-s3cret'aegis account john ftp add deploy --password='ftp-s3cret' --quota-mb=5120
    text
    ✔ FTP user john_upload created · /aegis/data/ftp/john_upload

    An account with max_ftp set refuses beyond the limit: account already has 5 FTP users.

    #aegis account <account> ftp remove

    Destructive. Deletes the virtual user and its registry row. The FTP root directory stays on disk.

    bash
    aegis account <account> ftp remove <user>
    argumentdefaultmeaning
    <user>—the short name, without the account prefix
    bash
    aegis account john ftp remove uploadaegis account john ftp delete deploy
    text
    ✔ user john_upload removed (home left in place)

    #aegis account <account> ftp password

    bash
    aegis account <account> ftp password <user> --password=<secret>
    argumentdefaultmeaning
    <user>—the short name
    --passwordrequiredat least 8 characters; the new password
    bash
    aegis account john ftp password upload --password='new-pass'aegis account john ftp password deploy --password="$(openssl rand -base64 18)"
    text
    ✔ password updated for john_upload

    #backup

    A backup is one directory per run, <backup_dir>/<account>/<stamp>/, holding a manifest.json and the archives it lists:

    filecontent
    home.tar.gzthe account home, when it exists
    mail.tar.gzthe maildirs of the account's domains, when they exist
    db-<server>-<name>.dumpone per database: pg_dump -Fc or mariadb-dump
    manifest.jsonaccount identity, sites, databases, every file and its size, and the errors

    #aegis account <account> backup list

    bash
    aegis account <account> backup list
    argumentdefaultmeaning
    ——the group defaults to list; newest first
    bash
    aegis account john backup listaegis account john backup
    text
    stamp            size  databases  errors  path───────────────  ────  ─────────  ──────  ───────────────────────────────────20261117T030001  1.4G  2          0       /aegis/backups/john/20261117T03000120261116T030001  1.4G  2          0       /aegis/backups/john/20261116T030001

    #aegis account <account> backup create

    Creates a full archive on disk. Archives the home, the maildirs and every database. The size of the run is the size of the account; a database dump holds a consistent snapshot and can take a long time.

    bash
    aegis account <account> backup create
    argumentdefaultmeaning
    ——no options; the stamp is UTC %Y%m%dT%H%M%S
    bash
    aegis account john backup createaegis account john backup create   # a second, separate run
    text
    ✔ backup 20261117T030001: 4 files

    A failed step does not abort the run. It is recorded in the manifest, printed as an error line, and the exit code stays 0, because a partial backup with a known gap is still worth having. The JSON payload then carries ok: false and the errors list.

    #aegis account <account> backup prune

    Destructive. Deletes whole backup directories. At least one backup is always kept, even with --keep=0.

    bash
    aegis account <account> backup prune --keep=<n>
    argumentdefaultmeaning
    --keep7number of newest backups to keep; values below 1 are treated as 1
    bash
    aegis account john backup pruneaegis account john backup prune --keep=14
    text
    ✔ 9 backups removed, 7 kept

    #check and repair

    check answers whether every reference resolves and every account owns a vhost. repair clears references that name an account this host has never had; it never guesses a new owner.

    #aegis account check

    bash
    aegis account check
    argumentdefaultmeaning
    ——no options
    bash
    aegis account check
    text
    ✔ nothing to repair (2 accounts, 3 vhosts, 1 zones)

    With problems, a table is printed and the exit code is 1:

    text
    source   row          value                             problem───────  ───────────  ────────────────────────────────  ────────────────────────────────web      legacy-shop  john:aegis-acc-0000000000000000   unknown identifieraccount  maria        maria:aegis-acc-7b2f90c4de118a63  no vhost belongs to this account

    The problem kinds are unknown identifier, malformed account hash, identifier belongs to <other-slug>, and no vhost belongs to this account. The last one is reported for every account whose hash no vhost carries, so a fresh account with no site makes check exit 1 until a site exists.

    #aegis account repair

    Changes ownership metadata. --apply empties the ownership columns of rows whose account does not exist. It does not reassign them.

    bash
    aegis account repair --apply
    argumentdefaultmeaning
    --applyoffactually clear the references; without it the command is a dry run
    bash
    aegis account repairaegis account repair --apply
    text
    source   row          value                             action───────  ───────────  ────────────────────────────────  ───────────────web      legacy-shop  john:aegis-acc-0000000000000000   clear ownershipℹ dry run: pass --apply to clear them
    text
    source   row          value                             action───────  ───────────  ────────────────────────────────  ───────────────web      legacy-shop  john:aegis-acc-0000000000000000   clear ownership✔ 1 references cleared

    Only dangling references are touched. A vhost whose owner exists is never re-stamped, and the "no vhost belongs to this account" problem reported by check is not something repair can fix.

    #JSON payloads

    Every payload starts with ok; most carry command. A command that fails with a message adds error and exits 1. List commands embed the raw rows of the registry or of the module that answered.

    commandother keys
    account.createaccount, tasks
    account.listaccounts
    account.showaccount, counts, events
    account.suspend, account.resumeaccount, effects
    account.deleteaccount (the slug), purged, steps
    account.domains.listdomains
    account.domains.adddomain
    account.domains.removedomain, detail
    account.sites.listsites
    account.sites.createsite, root, vhost, domain, php, socket, docroot, queue, applied
    account.sites.deletesite, detail
    account.db.listdatabases
    account.db.createdatabase, user, password, server, detail
    account.db.dropdatabase, detail
    account.mail.domainsdomains
    account.mail.domains.add, .removedetail
    account.mail.boxesmailboxes
    account.mail.boxes.add, .remove, .password, .quotadetail
    account.mail.forwardsforwards
    account.mail.forwards.add, .removedetail
    account.cron.listjobs
    account.cron.add, .removejob
    account.supervisor.listprograms
    account.supervisor.add, .removeprogram, detail
    account.perms.checkaccount, problems
    account.perms.fixaccount, dry_run, paths, changes
    account.quota.showaccount, identifier, home, quota_bytes, disk_bytes, databases_bytes, mail_bytes, total_bytes, free_bytes, databases
    account.ssh.listkeys
    account.ssh.addkey
    account.ssh.removekey (the id)
    account.ssh.enableaccount
    account.ftp.listusers
    account.ftp.adduser
    account.ftp.remove, .passworddetail
    account.backup.listbackups
    account.backup.createstamp, files, errors
    account.backup.prunekeep, removed
    account.checkaccounts, vhosts, zones, problems
    account.repairapplied, actions

    A create, with its steps:

    bash
    aegis account create john --password=secret --json
    text
    {"ok": true, "command": "account.create", "account": {"slug": "john", "identifier": "aegis-acc-3f9c21ab77d04e15", "home": "/home/john", "status": "active", "quota_mb": 0, "ssh_enabled": 0, "shell": "/usr/sbin/nologin", "created_at": "2026-11-17T20:15:04+00:00"}, "tasks": [{"name": "linux user", "status": "done", "detail": "created (uid 1042)"}, {"name": "home tree", "status": "done", "detail": "5 directories (5 created)"}, {"name": "password", "status": "done", "detail": "updated"}, {"name": "registry", "status": "done", "detail": "aegis-acc-3f9c21ab77d04e15"}]}

    A failed create reports the steps that did finish:

    text
    {"ok": false, "command": "account.create", "error": "cannot give /home/john/tmp to john: [Errno 1] Operation not permitted (run as root)", "tasks": [{"name": "linux user", "status": "done", "detail": "created (uid 1042)"}]}

    A per-account read, with the event list cut to its newest row:

    text
    {"ok": true, "command": "account.show", "account": {"slug": "john", "identifier": "aegis-acc-3f9c21ab77d04e15", "home": "/home/john", "status": "active", "quota_mb": 20480, "ssh_enabled": 1, "shell": "/bin/bash", "created_at": "2026-11-10T09:14:02+00:00"}, "counts": {"sites": 1, "databases": 1, "ftp": 1}, "events": [{"id": 7, "account_id": 1, "actor": "", "action": "site.create", "target": "john/example", "detail": "example.com", "at": "2026-11-12T18:05:10+00:00"}]}

    A write that returns the row it created:

    text
    {"ok": true, "command": "account.cron.add", "job": {"id": "1", "schedule": "@daily", "user": "john", "command": "/home/john/bin/backup.sh", "comment": "nightly backup"}}