#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.
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.
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| form | example | available for |
|---|---|---|
| command | aegis account create john | create, list, show, info, suspend, resume, delete, cron, supervisor, check, repair, help |
| scoped | aegis account john <group> … | domains, sites, db, mail, cron, supervisor, perms, quota, ssh, ftp, backup |
| account-first | aegis 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. Everyother group is reached through the account name.
check and repair exist only at the top level; aegis account john checkanswers unknown account command: check.
aegis account john equals aegis account show john.
show/info and delete/remove are aliases, andin mail so are boxes/mailboxes.
list, create, cron) cannever be addressed: the word is taken as a command. Pick another name.
store.get lowercases before looking up.The built-in short help exists because argparse cannot describe the two-level syntax:
aegis account help| argument | default | meaning |
|---|---|---|
| — | — | the command takes no options |
aegis account helpaegis account help # when `--help` is not enoughℹ 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.
| field | value | changes |
|---|---|---|
slug | the Linux user, for example john | almost never |
identifier | aegis-acc- plus 16 hex characters | never |
aegis account show johnaccount johnidentifier aegis-acc-3f9c21ab77d04e15status activehome /home/johnlinux user uid 1042, gid 1042, shell /bin/bashssh yesshell /bin/bashquota 20480 MBsites 1databases 1ftp 1A slug is validated before anything touches the host:
_ and -;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:
| database | table | column |
|---|---|---|
web.db | nginx_vhosts | account_hash, site_slug |
web.db | php_pools | account_hash, site_slug |
dns.db | dns_zones | account_hash |
The registry itself is /aegis/database/storage/account/main.db:
| table | holds |
|---|---|
accounts | slug, identifier, uid/gid, home, status, quotas, SSH |
account_domains | one row per domain: primary, addon, alias, subdomain |
account_sites | a name, one primary domain, UNIQUE(account_id, name) |
account_databases | server (mariadb/postgresql), name, owner role |
account_ftp_accounts | username, home, quota |
account_ssh_keys | one authorized key per row |
account_events | who did what, when |
account_purged | one line per purged account, kept after the row is gone |
Statuses:
| status | meaning |
|---|---|
active | normal |
suspended | the flag the modules read: vhosts disabled, database roles locked, mailboxes deactivated, shell replaced, cron parked |
deleted | kept for the record; the name is still taken |
The home tree is created with the user:
/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:
aegis --json account list;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:
{"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 code | meaning |
|---|---|
0 | the command finished |
1 | a command reported a failure |
2 | argparse rejected the arguments (missing value, unknown flag) |
130 | interrupted 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.
aegis account create <username> --password=<secret> --ssh=yes|no --home=<path> --quota-mb=<n> --notes=<text>| argument | default | meaning |
|---|---|---|
<username> | — | the slug; validated as described above |
--password | empty | passed to chpasswd through stdin, never argv; omitted means no password step |
--ssh | no | yes gives the account /bin/bash, no gives /usr/sbin/nologin |
--home | /home/<username> | home directory passed to useradd --home-dir |
--quota-mb | 0 | stored on the account row; quota show compares usage against it |
--notes | empty | stored 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.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'account creation · john [●●●●] 4/4✔ account john created · aegis-acc-3f9c21ab77d04e15 · /home/johnThe 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.
aegis account list --status=<status>| argument | default | meaning |
|---|---|---|
--status | empty | filter by the exact string; active, suspended and deleted match rows, anything else matches nothing |
aegis account listaegis account list --status=suspendedaccount identifier status home─────── ────────────────────────── ───────── ───────────anna aegis-acc-1c04e5d29ab87310 active /srv/annajohn aegis-acc-3f9c21ab77d04e15 active /home/johnmaria aegis-acc-7b2f90c4de118a63 suspended /home/mariaWhen 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.
aegis account show <username>aegis account info <username>| argument | default | meaning |
|---|---|---|
<username> | — | the slug |
aegis account show johnaegis account info mariaaccount 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-3f9c21ab77d04e15linux 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.
aegis account suspend <username> --note=<text>| argument | default | meaning |
|---|---|---|
<username> | — | the slug |
--note | empty | stored in the account.suspended audit event |
aegis account suspend johnaegis account suspend maria --note='invoice 2026-10 unpaid'✔ account john suspendedℹ 2 vhosts disabledℹ 1 database roles lockedℹ 2 mailboxes disabledℹ shell /usr/sbin/nologinℹ cron parkedAn 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.
aegis account resume <username> --note=<text>| argument | default | meaning |
|---|---|---|
<username> | — | the slug |
--note | empty | stored in the account.resumed audit event |
aegis account resume johnaegis account resume maria --note='payment received'✔ account john activeℹ 2 vhosts enabledℹ 1 database roles unlockedℹ 2 mailboxes enabledℹ shell /bin/bashℹ cron restoredThe 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.
--purgedeletes 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.
aegis account delete <username> --purge --yes| argument | default | meaning |
|---|---|---|
<username> | — | the slug |
--purge | off | remove user, home, programs, cron, mail and FTP users, then the rows |
--yes | off | required with --purge; without it the command refuses and changes nothing |
aegis account delete mariaaegis account delete maria --purge --yes✔ account maria deleted (rows kept)✔ account maria deleted and purgedRefusal without confirmation:
✖ purging deletes the Linux user and the home: pass --yesThe 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
aegis account <account> domains list| argument | default | meaning |
|---|---|---|
| — | — | the group defaults to list |
aegis account john domains listaegis account anna domainsdomain kind dns mail status──────────────── ───────── ─── ──── ──────example.com primary yes yes activeshop.example.com subdomain no yes activedns 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
aegis account <account> domains add <domain> --kind=<kind> --dns| argument | default | meaning |
|---|---|---|
<domain> | — | validated by the bind zone-name checker |
--kind | primary | primary, addon, alias or subdomain |
--dns | off | create and serve the DNS zone, then record the account as its owner |
aegis account john domains add example.comaegis account john domains add shop.example.com --kind=subdomain --dns✔ domain shop.example.com addedFailures 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
--dnsit also removes the DNS zone and every record in it.
aegis account <account> domains remove <domain> --dns| argument | default | meaning |
|---|---|---|
<domain> | — | must belong to this account |
--dns | off | also remove the zone, when the row says this account manages it |
aegis account john domains remove shop.example.comaegis account john domains remove shop.example.com --dns✔ domain shop.example.com removedA domain used as the primary domain of a site is protected:
✖ shop.example.com is the primary domain of a site; delete the site first#aegis account <account> sites list
aegis account <account> sites list| argument | default | meaning |
|---|---|---|
| — | — | the group defaults to list |
aegis account john sites listaegis account anna sitessite domain vhosts─────── ──────────────── ────────────example example.com john-exampleshop shop.example.com john-shopThe 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.
aegis account <account> sites create <domain> --name=<site> --php=<series> --preset=<shape> --docroot=<dir> --queue --no-apply| argument | default | meaning |
|---|---|---|
<domain> | — | must already be a domain of this account |
--name | derived from the domain | www.example.com becomes example; lowercased, and the derived name is at most 31 characters |
--php | config php.version | PHP series the vhost serves with, for example 8.5; must be installed and enabled |
--preset | static, or php when --php is given | static, php or laravel |
--docroot | htdocs, public for laravel | directory inside the site that nginx serves |
--queue | off | add a Supervisor program running artisan queue:work; needs a PHP series |
--no-apply | off | write the rows and files but skip web apply |
aegis account john sites create example.com --preset=staticaegis account john sites create shop.example.com --preset=laravel --php=8.5 --queue✔ site shop created · /home/john/shop · vhost john-shop · php 8.5 · queue onWhat lands where:
| item | value |
|---|---|
| site tree | /home/{account}/{site}/ plus logs, tmp, ssl |
| Laravel extra | storage/framework/{cache,sessions,views}, storage/logs, bootstrap/cache |
| placeholder | index.html in the document root, owned by the account |
| vhost | named {account}-{site}, the domain as its only server_name |
| ownership | account_hash and site_slug stamped on the vhost |
| ACLs | aegis-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:
✖ 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.
--purgedeletes the whole site directory, not only the row and the vhost.
aegis account <account> sites delete <site> --purge --yes --no-apply| argument | default | meaning |
|---|---|---|
<site> | — | the site name, not the domain |
--purge | off | delete /home/{account}/{site} and everything in it |
--yes | off | required with --purge |
--no-apply | off | skip the nginx reload |
aegis account john sites delete exampleaegis account john sites delete shop --purge --yes✔ site shop removedThe queue program {account}_{site}_queue is removed when it exists; a static site simply has none. Refusal without confirmation:
✖ 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
aegis account <account> db list --server=<engine>| argument | default | meaning |
|---|---|---|
--server | both engines | pgsql, postgres, postgresql, mariadb or mysql |
aegis account john db listaegis account john db list --server=pgsqldatabase 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.
aegis account <account> db create <name> --server=<engine> --username=<role> --password=<secret>| argument | default | meaning |
|---|---|---|
<name> | — | stored as {account}_{name}; - becomes _ |
--server | required | engine alias, as in db list |
--username | the database name | role stored as {account}_{username} |
--password | generated | a random token_urlsafe(12) when omitted |
aegis account john db create app --server=pgsqlaegis account john db create wp --server=mariadb --username=blog --password='db-s3cret'✔ database john_app created · user john_app · password Q3f9c21ab77d04e1Names 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.
aegis account <account> db drop <name> --server=<engine> --yes| argument | default | meaning |
|---|---|---|
<name> | — | bare or already prefixed; both are found |
--server | required | engine alias |
--yes | off | required; without it the command refuses and changes nothing |
aegis account john db drop app --server=pgsql --yesaegis account john db drop john_wp --server=mariadb --yes✔ database john_app dropped✖ dropping a database deletes its data: pass --yesMail 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
aegis account <account> mail domains listaegis account <account> mail| argument | default | meaning |
|---|---|---|
| — | — | mail defaults to domains, and domains to list |
aegis account john mail domains listaegis account john maildomain active mailboxes─────────── ────── ─────────example.com 1 3Only 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.
aegis account <account> mail domains add <domain>| argument | default | meaning |
|---|---|---|
<domain> | — | must already be a domain of this account |
aegis account john mail domains add example.comaegis account john mail domains add shop.example.com✔ domain example.com created✖ 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.
aegis account <account> mail domains remove <domain>| argument | default | meaning |
|---|---|---|
<domain> | — | must be a mail domain of this account |
aegis account john mail domains remove example.comaegis account john mail domains delete old.example.com✔ domain example.com removed#aegis account <account> mail boxes list
aegis account <account> mail boxes list --domain=<domain>aegis account <account> mail mailboxes list --domain=<domain>| argument | default | meaning |
|---|---|---|
--domain | all owned domains | restrict the listing to one domain |
aegis account john mail boxes listaegis account john mail boxes list --domain=example.comaddress active quota name────────────────────── ────── ────────── ──────────john@example.com 1 1073741824 John Doepostmaster@example.com 1 1073741824 Postmasterquota is printed in bytes, as the cube stores it.
#aegis account <account> mail boxes add
aegis account <account> mail boxes add <address> --password=<secret> --quota-mb=<n> --name=<display>| argument | default | meaning |
|---|---|---|
<address> | — | an address whose domain this account owns |
--password | required | at least 8 characters; hashed by the cube before storage |
--quota-mb | 0 | converted to bytes; 0 takes the domain default |
--name | empty | display name |
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'✔ 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.
aegis account <account> mail boxes remove <address>| argument | default | meaning |
|---|---|---|
<address> | — | an address of this account |
aegis account john mail boxes remove info@example.comaegis account john mail boxes delete temp@example.com✔ mailbox info@example.com removed (maildir left in place)#aegis account <account> mail boxes password
aegis account <account> mail boxes password <address> --password=<secret>| argument | default | meaning |
|---|---|---|
<address> | — | an address of this account |
--password | required | at least 8 characters; the new password |
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)"✔ password updated for john@example.com#aegis account <account> mail boxes quota
aegis account <account> mail boxes quota <address> --quota-mb=<n>| argument | default | meaning |
|---|---|---|
<address> | — | an address of this account |
--quota-mb | required | new quota in MiB; converted to bytes |
aegis account john mail boxes quota john@example.com --quota-mb=2048aegis account john mail boxes quota info@example.com --quota-mb=512✔ quota for john@example.com set to 2147483648 bytes#aegis account <account> mail forwards list
aegis account <account> mail forwards list| argument | default | meaning |
|---|---|---|
| — | — | the group defaults to list |
aegis account john mail forwards listaegis account john mail forwardsaddress destination keep local active───────────────── ──────────────── ────────── ──────sales@example.com john@example.com 1 1#aegis account <account> mail forwards add
aegis account <account> mail forwards add <source> --to=<destination>| argument | default | meaning |
|---|---|---|
<source> | — | an address of this account |
--to | required | destination address |
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✔ 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
--tois omitted.
aegis account <account> mail forwards remove <source> --to=<destination>| argument | default | meaning |
|---|---|---|
<source> | — | an address of this account |
--to | empty | remove only this destination; omitted removes them all |
aegis account john mail forwards remove sales@example.com --to=john@example.comaegis account john mail forwards remove sales@example.com✔ 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:
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
aegis account <account> cron listaegis account cron list <account>| argument | default | meaning |
|---|---|---|
| — | — | the group defaults to list |
aegis account john cron listaegis account cron list johnid schedule user command note── ────────── ──── ──────────────────────── ──────────────1 @daily john /home/john/bin/backup.sh nightly backup2 30 3 * * * john /home/john/bin/prune.shNumbers 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
aegis account <account> cron add <schedule> --command=<command> --comment=<text>aegis account cron add <account> <schedule> --command=<command> --comment=<text>| argument | default | meaning |
|---|---|---|
<schedule> | — | five fields, or one of @reboot, @yearly, @annually, @monthly, @weekly, @daily, @midnight, @hourly |
--command | required | one line; a newline is refused |
--comment | empty | written above the job as # id: N <comment> |
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'✔ job 1 added: @daily /home/john/bin/backup.shRefusals:
✖ 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.
aegis account <account> cron remove <id>aegis account cron remove <account> <id>| argument | default | meaning |
|---|---|---|
<id> | — | the number shown by cron list |
aegis account john cron remove 2aegis account cron remove john 1✔ job 2 removed✖ 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:
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
aegis account <account> supervisor listaegis account supervisor list <account>| argument | default | meaning |
|---|---|---|
| — | — | the group defaults to list |
aegis account john supervisor listaegis account supervisor list johnprogram command directory autostart─────── ─────────────────────────── ────────── ─────────worker /home/john/bin/worker /home/john truecleanup /home/john/bin/cleanup --all /home/john falseprogram 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
aegis account <account> supervisor add <program> --command=<command> --directory=<path> --no-autostartaegis account supervisor add <account> <program> --command=<command> --directory=<path> --no-autostart| argument | default | meaning |
|---|---|---|
<program> | — | stored as {account}_{program}; - becomes _; the full name must fit 32 characters |
--command | required | stored exactly as typed; Supervisor does not use a shell |
--directory | empty | working directory of the process |
--no-autostart | off | write autostart=false |
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✔ program john_worker writtenRe-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.
aegis account <account> supervisor remove <program>aegis account supervisor remove <account> <program>| argument | default | meaning |
|---|---|---|
<program> | — | the short name; {account}_ is added before the lookup |
aegis account john supervisor remove workeraegis account supervisor remove john maintenance✔ 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.
aegis account <account> perms checkaegis account <account> perms| argument | default | meaning |
|---|---|---|
| — | — | perms defaults to check |
aegis account john perms checkaegis account john perms✔ permissions look correctWhen something is missing, a table is printed and the exit code is 1:
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-wwwIt 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-wwwand 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.
aegis account <account> perms fix --dry-run| argument | default | meaning |
|---|---|---|
--dry-run | off | print the setfacl lines without running them |
aegis account john perms fix --dry-runaegis account john perms fixℹ 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)✔ 24 ACL grants applied on 6 pathsThis 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.
aegis account <account> quota showaegis account <account> quota| argument | default | meaning |
|---|---|---|
| — | — | quota defaults to show; it is the only verb |
aegis account john quota showaegis account john quotagroup 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.1MSizes 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
aegis account <account> ssh list| argument | default | meaning |
|---|---|---|
| — | — | the group defaults to list |
aegis account john ssh listaegis account john sshid name fingerprint key── ────── ──────────────── ────────────────────────────────────────────────────────────1 laptop 3f9c21ab77d04e15 ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIJ8kQ2m0Xr7pLwVd4tYb1nFc2 ci 8a71c0de4b2f9911 ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIBx4mQ2pVr7kLw9d1tYb8nFjThe 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
aegis account <account> ssh add '<public-key>' --name=<label>| argument | default | meaning |
|---|---|---|
<public-key> | — | one line: ssh-ed25519 AAAA… comment |
--name | key | label shown by ssh list |
aegis account john ssh add 'ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIJ8kQ2m0Xr7pLwVd4tYb1nFc john@laptop' --name=laptopaegis account john ssh add "$(cat ~/.ssh/id_ed25519.pub)" --name=ci✔ key 3f9c21ab77d04e15 added✖ that does not look like a public key✖ that key is already addedThe 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.
aegis account <account> ssh remove <id>| argument | default | meaning |
|---|---|---|
<id> | — | the number from ssh list; a non-number is an argparse error (exit 2) |
aegis account john ssh remove 2aegis account john ssh delete 1✔ key 2 removed✖ 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.
aegis account <account> ssh enable| argument | default | meaning |
|---|---|---|
| — | — | no options |
aegis account john ssh enableaegis account john ssh enable # idempotent✔ 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
aegis account <account> ftp list| argument | default | meaning |
|---|---|---|
| — | — | the group defaults to list |
aegis account john ftp listaegis account john ftpuser home quota status─────────── ─────────────────────────── ───── ──────john_upload /aegis/data/ftp/john_upload 0 active#aegis account <account> ftp add
aegis account <account> ftp add <user> --password=<secret> --quota-mb=<n>| argument | default | meaning |
|---|---|---|
<user> | — | stored as {account}_{user} |
--password | required | at least 8 characters; the FTP password |
--quota-mb | 0 | stored on the account's FTP row |
aegis account john ftp add upload --password='ftp-s3cret'aegis account john ftp add deploy --password='ftp-s3cret' --quota-mb=5120✔ FTP user john_upload created · /aegis/data/ftp/john_uploadAn 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.
aegis account <account> ftp remove <user>| argument | default | meaning |
|---|---|---|
<user> | — | the short name, without the account prefix |
aegis account john ftp remove uploadaegis account john ftp delete deploy✔ user john_upload removed (home left in place)#aegis account <account> ftp password
aegis account <account> ftp password <user> --password=<secret>| argument | default | meaning |
|---|---|---|
<user> | — | the short name |
--password | required | at least 8 characters; the new password |
aegis account john ftp password upload --password='new-pass'aegis account john ftp password deploy --password="$(openssl rand -base64 18)"✔ 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:
| file | content |
|---|---|
home.tar.gz | the account home, when it exists |
mail.tar.gz | the maildirs of the account's domains, when they exist |
db-<server>-<name>.dump | one per database: pg_dump -Fc or mariadb-dump |
manifest.json | account identity, sites, databases, every file and its size, and the errors |
#aegis account <account> backup list
aegis account <account> backup list| argument | default | meaning |
|---|---|---|
| — | — | the group defaults to list; newest first |
aegis account john backup listaegis account john backupstamp 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.
aegis account <account> backup create| argument | default | meaning |
|---|---|---|
| — | — | no options; the stamp is UTC %Y%m%dT%H%M%S |
aegis account john backup createaegis account john backup create # a second, separate run✔ backup 20261117T030001: 4 filesA 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.
aegis account <account> backup prune --keep=<n>| argument | default | meaning |
|---|---|---|
--keep | 7 | number of newest backups to keep; values below 1 are treated as 1 |
aegis account john backup pruneaegis account john backup prune --keep=14✔ 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
aegis account check| argument | default | meaning |
|---|---|---|
| — | — | no options |
aegis account check✔ nothing to repair (2 accounts, 3 vhosts, 1 zones)With problems, a table is printed and the exit code is 1:
source row value problem─────── ─────────── ──────────────────────────────── ────────────────────────────────web legacy-shop john:aegis-acc-0000000000000000 unknown identifieraccount maria maria:aegis-acc-7b2f90c4de118a63 no vhost belongs to this accountThe 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.
--applyempties the ownership columns of rows whose account does not exist. It does not reassign them.
aegis account repair --apply| argument | default | meaning |
|---|---|---|
--apply | off | actually clear the references; without it the command is a dry run |
aegis account repairaegis account repair --applysource row value action─────── ─────────── ──────────────────────────────── ───────────────web legacy-shop john:aegis-acc-0000000000000000 clear ownershipℹ dry run: pass --apply to clear themsource row value action─────── ─────────── ──────────────────────────────── ───────────────web legacy-shop john:aegis-acc-0000000000000000 clear ownership✔ 1 references clearedOnly 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.
command | other keys |
|---|---|
account.create | account, tasks |
account.list | accounts |
account.show | account, counts, events |
account.suspend, account.resume | account, effects |
account.delete | account (the slug), purged, steps |
account.domains.list | domains |
account.domains.add | domain |
account.domains.remove | domain, detail |
account.sites.list | sites |
account.sites.create | site, root, vhost, domain, php, socket, docroot, queue, applied |
account.sites.delete | site, detail |
account.db.list | databases |
account.db.create | database, user, password, server, detail |
account.db.drop | database, detail |
account.mail.domains | domains |
account.mail.domains.add, .remove | detail |
account.mail.boxes | mailboxes |
account.mail.boxes.add, .remove, .password, .quota | detail |
account.mail.forwards | forwards |
account.mail.forwards.add, .remove | detail |
account.cron.list | jobs |
account.cron.add, .remove | job |
account.supervisor.list | programs |
account.supervisor.add, .remove | program, detail |
account.perms.check | account, problems |
account.perms.fix | account, dry_run, paths, changes |
account.quota.show | account, identifier, home, quota_bytes, disk_bytes, databases_bytes, mail_bytes, total_bytes, free_bytes, databases |
account.ssh.list | keys |
account.ssh.add | key |
account.ssh.remove | key (the id) |
account.ssh.enable | account |
account.ftp.list | users |
account.ftp.add | user |
account.ftp.remove, .password | detail |
account.backup.list | backups |
account.backup.create | stamp, files, errors |
account.backup.prune | keep, removed |
account.check | accounts, vhosts, zones, problems |
account.repair | applied, actions |
A create, with its steps:
aegis account create john --password=secret --json{"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:
{"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:
{"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:
{"ok": true, "command": "account.cron.add", "job": {"id": "1", "schedule": "@daily", "user": "john", "command": "/home/john/bin/backup.sh", "comment": "nightly backup"}}