Aegis documentation

#Accounts — one Linux user and everything it owns

An account is the unit a customer pays for. It owns a Linux user, a home directory, and — through the modules that already exist — domains, sites, databases, mailboxes and FTP users.

The account module is deliberately thin. It does not render a vhost, write a zone or create a mailbox: those stay with web, dns and mail. What it owns is the association, so the answer to "whose vhost is this?" has one place to live.

#Two names, two jobs

fieldwhat it ischanges?
slugthe Linux user: johnalmost never
identifieraegis-acc- + 16 hex charactersnever

Every other database stores account_hash = "slug:identifier":

sql
-- web.dbSELECT name, account_hash, site_slug FROM nginx_vhosts;web1  john:aegis-acc-3f9c21ab77d04e15  example

The slug keeps the row readable in a database browser; the identifier is what the code trusts, so renaming an account later does not orphan its vhosts. There is no foreign key between two SQLite files, and a partial restore of dns.db must still work alone — that is the whole reason for the pair.

#Layout

text
/home/john/└── example/    ├── htdocs/     # the document root, the only thing a browser reaches    ├── logs/    ├── tmp/    ├── ssl/    └── backups/

htdocs exists so .env, .git and composer.json never sit next to index.php where a bad location could serve them.

#Tables

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

A site owns no vhost list here: its vhosts are the rows in web.db with the same (account_hash, site_slug) pair. Nothing to synchronise.

The columns added to the other databases:

sql
nginx_vhosts.account_hash, nginx_vhosts.site_slug   -- web.dbphp_pools.account_hash,    php_pools.site_slug      -- web.dbdns_zones.account_hash                              -- dns.db

#States

statusmeaning
activenormal
suspendedthe flag the modules read: nginx answers 503, the PHP pool stops, mail auth is refused, the database role cannot log in
deletedkept for the record and for a later purge

aegis account delete --purge --yes removes the Linux user and the home; without --purge the rows stay and the files remain on disk.

#Command line

bash
aegis account create john --password=secret --ssh=yesaegis account create john --home=/srv/john --quota-mb=20480aegis account listaegis account show johnaegis account suspend john --note="invoice unpaid"aegis account resume johnaegis account delete john --purge --yes

create runs as a timeline of idempotent steps — linux user, home tree, password, registry — so a run interrupted halfway is resumed by repeating the same command.

--json is accepted anywhere on the line:

bash
aegis account create john --password=secret --json
json
{  "ok": true,  "command": "account.create",  "account": {"slug": "john", "identifier": "aegis-acc-…", "home": "/home/john"},  "tasks": [{"name": "linux user", "status": "done", "detail": "created (uid 1042)"}]}

The progress line goes to stderr, the payload to stdout, so a dashboard can parse the output without stripping a timeline.

#Scoped commands

bash
aegis account john domains listaegis account john domains add example.com --kind=primary --dnsaegis account john domains remove example.com --dnsaegis account john sites listaegis account john sites create example.com --name=example --preset=phpaegis account john sites create shop.example.com --preset=laravel --queueaegis account john sites delete example --purge --yes --no-applyaegis account john db list --server=pgsql|mariadbaegis account john db create app --server=pgsql --username=app --password=aegis account john db drop app --server=pgsql --yesaegis account john cron listaegis account john cron add "@daily" --command="/home/john/bin/backup.sh"aegis account john cron remove 1aegis account john supervisor listaegis account john supervisor add worker --command="/home/john/bin/worker"     --directory=/home/john/appaegis account john supervisor remove workeraegis account john perms checkaegis account john perms fix --dry-run

Both groups also work at the top level, with the account first: aegis account cron list john, aegis account supervisor list john.

domains add --dns creates the zone through the dns module and stamps it with the account's hash; without the flag the domain is only a reference.

sites create writes /home/{account}/{site}/ with an index.html placeholder, creates the vhost named {account}-{site} with the domain as its only server_name, stamps account_hash and site_slug on it, then runs web apply — pass --no-apply to leave the render for later.

--preset decides the shape of the site:

presetdocument rootlocationsextra
statichtdocsone static block—
phphtdocsphp preset, fastcgi_pass at the series socket—
laravelpublicphp-mvc presetstorage/…, bootstrap/cache

There is no pool per site: one PHP-FPM master serves every series, which is the point — a pool per client multiplies the daemons without isolating much, because the FPM master runs as root either way.

--queue adds a Supervisor program {account}_{site}_queue running php artisan queue:work as the account, in the site directory.

The site tree is granted with ACLs in both directions — aegis-www and the account, with default entries — because PHP writes storage/ as the web account while the operator runs artisan and git as themselves. One direction only is the classic half-broken Laravel site.

cron add writes one line into /etc/cron.d/aegis-{account}; supervisor add writes {account}_{program}.conf in the supervisor cube's programs directory and reloads it.

perms check answers what the web account cannot reach — the home, the site directories and the parents — without changing anything. perms fix re-grants aegis-www and the account on every target, with default entries, so a file created by either side tomorrow is still usable by the other. --dry-run prints the setfacl lines first. It is the command to run when a site answers 403 or PHP cannot write after someone copied files around.

db create prefixes both the database and the role with the account (john_app), creates the role with a grant on that database only, and prints the generated password once. Engines are called through their cubes, never through a shell.

delete --purge also removes the rows: the name becomes free, and one line stays in account_purged so the audit survives the account it describes.

#Not built yet

  • aegis account backup
  • aegis account check / repair — orphan detection between this database and
  • the modules

  • the effects of suspended in nginx, PHP, mail, FTP and the engines
  • --allow-remote for a database role