Aegis documentation

#BIND

The BIND cube owns the authoritative resolver: named.conf, the included aegis-options.conf and aegis-local.conf, one stanza per zone under zones.d/<domain>.conf, the zone bodies <zones_dir>/<domain>.db, the TSIG key in keys/tsig.key and run/named.pid. dns.config_dir defaults to /aegis/config/bind and dns.zones_dir to /aegis/data/bind/zones.

Zone data has two homes. A zone the panel manages lives in the DNS Manager database (database/storage/dns/dns.db) and the file is rendered from it, so record add --domain … writes a row and regenerates the zone. A zone that exists only as a file is edited in place, and the line form of record is refused for a panel-managed zone. The daemon runs as the keeper service aegis-bind with named -c <named.conf> -u root.

#Common commands

Cube operations share one wrapper: ✔ bind: <detail> on success, ✖ <message> on failure (exit 1), and {"ok": true, "cube": "bind", "result": "<detail>"} with the global --json.

expose is the only verb that prints a block instead of that line.

VerbEffect
configurecreate directories, generate the TSIG key if absent, render every file, seed the zone include, validate
validatenamed-checkconf plus named-checkzone over every zone
reloadrestart named — see below
statusread run/bind/named.pid: running (pid N) or stopped
startstart named through the keeper
stopSIGTERM, then SIGKILL after 15 seconds
restartstop, then start
fix-journalsdelete every *.jnl and restart
tsigprint the TSIG key name and secret
exposeprint paths and zone count, then publish the BIND tools
helpprint the command list with examples

Every zone carries allow-update for the certbot key, which makes it a dynamic zone: rndc reload <zone> answers "dynamic zone" and a global rndc reload keeps the in-memory journal. reload therefore performs a restart, which is the only reliable way to serve a zone file edited behind the daemon's back.

#configure

bash
aegis cubes bind configureaegis --json cubes bind configure

Writes keys/tsig.key with mode 0600, the two include files, named.conf and a placeholder zones.d/00-empty.conf while no zone exists. It also creates the zone for setup.primary_domain when that domain has none.

text
✔ bind: configuration written, configuration valid, 3 zones valid{"ok": true, "cube": "bind", "result": "configuration written, configuration valid, 3 zones valid"}

#validate

bash
aegis cubes bind validateaegis --json cubes bind validate

Runs named-checkconf on the main file and named-checkzone on every zone; the first failing zone aborts the command with its message.

text
✔ bind: configuration valid, 3 zones valid{"ok": true, "cube": "bind", "result": "configuration valid, 3 zones valid"}

#reload

bash
aegis cubes bind reloadaegis --json cubes bind reload

Stops and starts named, because a restart is what makes the daemon re-read zone files that changed on disk. The reported detail is the restart's:

text
✔ bind: stopped (pid 481), started (pid 902){"ok": true, "cube": "bind", "result": "stopped (pid 481), started (pid 902)"}

#status

bash
aegis cubes bind statusaegis --json cubes bind status
text
✔ bind: running (pid 902){"ok": true, "cube": "bind", "result": "running (pid 902)"}

#start

bash
aegis cubes bind startaegis --json cubes bind start
text
✔ bind: started (pid 902){"ok": true, "cube": "bind", "result": "started (pid 902)"}

#stop

bash
aegis cubes bind stopaegis --json cubes bind stop

DNS for every hosted zone stops answering until the next start.

text
✔ bind: stopped (pid 902){"ok": true, "cube": "bind", "result": "stopped (pid 902)"}

#restart

bash
aegis cubes bind restartaegis --json cubes bind restart
text
✔ bind: stopped (pid 902), started (pid 947){"ok": true, "cube": "bind", "result": "stopped (pid 902), started (pid 947)"}

#fix-journals

Destructive. Deletes every *.jnl file in the zone directory, then restarts named. A journal holds dynamic updates that were not yet written to the zone file, so records only present in a journal are lost. Use it when named refuses a zone with "journal rollforward failed".

bash
aegis cubes bind fix-journalsaegis --json cubes bind fix-journals
text
✔ bind: 2 journals dropped, stopped (pid 902), started (pid 981){"ok": true, "cube": "bind", "result": "2 journals dropped, stopped (pid 902), started (pid 981)"}

#tsig

bash
aegis cubes bind tsigaegis --json cubes bind tsig

Prints <key name> <secret>. The name is dns.key_name (default aegis-tsig) and the secret is the one certbot's RFC 2136 plugin uses. It takes no options.

text
✔ bind: aegis-tsig q7Zk3m0R2c9pXf1sV8tYb4nJ6dL5hA0eWc={"ok": true, "cube": "bind", "result": "aegis-tsig q7Zk3m0R2c9pXf1sV8tYb4nJ6dL5hA0eWc="}

#expose

bash
aegis cubes bind exposeaegis --json cubes bind expose
text
cube           bindinstalled      /aegis/apps/dns/bind/9.21configuration  /aegis/config/bindstate          running (pid 902)pid            902log            /aegis/logs/bind/named.logmain config    /aegis/config/bind/named.confzones          3zone files     /aegis/data/bind/zonestsig key       /aegis/config/bind/keys/tsig.keypublished      /aegis/bin/named, /aegis/bin/rndc, /aegis/bin/dig, /aegis/bin/nslookup, /aegis/bin/nsupdate
text
{"ok": true, "cube": "bind", "installed": "/aegis/apps/dns/bind/9.21", "configuration": "/aegis/config/bind", "state": "running (pid 902)", "pid": "902", "log": "/aegis/logs/bind/named.log", "main config": "/aegis/config/bind/named.conf", "zones": "3", "zone files": "/aegis/data/bind/zones", "tsig key": "/aegis/config/bind/keys/tsig.key", "published": "/aegis/bin/named, /aegis/bin/rndc, /aegis/bin/dig, /aegis/bin/nslookup, /aegis/bin/nsupdate"}

#help

bash
aegis cubes bind helpaegis cubes help bind
text
ℹ Bind — Authoritative DNS: named.conf, TSIG, zones and recordsCommands  validate      Check the configuration  reload        Reload the running daemon  configure     Write the configuration and validate

The list continues with start, stop, status, restart, fix-journals, tsig, expose, zone, record and help, then the examples.

#Zones

A zone is two files: the stanza in zones.d/ and the body in the zone directory. zones.d/00-empty.conf keeps the include glob valid while no zone exists.

text
aegis cubes bind zone  Manage DNS zonesCommands  list    List configured zones  add     Create a zone  show    Print a zone  check   Validate a zone  delete  Delete a zoneRun 'aegis cubes bind zone <command> --help' for the options of one command.

#zone list

bash
aegis cubes bind zone listaegis --json cubes bind zone list

Lists the zone stanzas, without .conf and without the placeholder. No options.

text
✔ bind: example.com, example.org{"ok": true, "cube": "bind", "result": "example.com, example.org"}

#zone add

bash
aegis cubes bind zone add example.netaegis --json cubes bind zone add example.net
ArgumentMeaning
domainthe zone name, lowercased, trailing dot removed

Renders the SOA skeleton (NS records, glue, apex and wildcard A, MX, SPF and DMARC) and the stanza, removes the placeholder, validates every zone and applies the result. An existing zone fails with zone already exists: <name>.

text
✔ bind: zone example.net created; configuration valid, 3 zones valid; stopped (pid 902), started (pid 1011){"ok": true, "cube": "bind", "result": "zone example.net created; configuration valid, 3 zones valid; stopped (pid 902), started (pid 1011)"}

#zone show

bash
aegis cubes bind zone show example.comaegis --json cubes bind zone show example.com
ArgumentMeaning
domainthe zone whose body is printed
text
✔ bind: ; Aegis — authoritative zone skeleton; Deployed to: /aegis/data/bind/zones/example.com.db; SOA serial format: YYYYMMDDNN$TTL 300$ORIGIN example.com.@   IN  SOA ns1.example.com. hostmaster.example.com. (        2026010101   ; serial        3600         ; refresh        900          ; retry        604800       ; expire        300          ; minimum    )

The rest of the file (NS, glue, apex, mail and TXT records) follows.

#zone check

bash
aegis cubes bind zone check example.comaegis --json cubes bind zone check example.com
ArgumentMeaning
domainthe zone to test

Runs named-checkzone on one file and prints its last line, which is OK for a valid zone. It does not touch the daemon.

text
✔ bind: OK{"ok": true, "cube": "bind", "result": "OK"}

#zone delete

Destructive. Removes the stanza and the zone body. The zone stops being served as soon as the restart completes, and any panel row for it is not touched.

bash
aegis cubes bind zone delete example.netaegis --json cubes bind zone delete example.net
ArgumentMeaning
domainthe zone to remove

If it was the last zone, the 00-empty.conf placeholder is written back so the include glob keeps matching something.

text
✔ bind: zone example.net deleted; configuration valid, 2 zones valid; stopped (pid 1011), started (pid 1044){"ok": true, "cube": "bind", "result": "zone example.net deleted; configuration valid, 2 zones valid; stopped (pid 1011), started (pid 1044)"}

#Records

Two forms address the same data. With --domain the record is stored in the database when the panel manages the zone, or appended as a line otherwise. With <zone> "<line>" the line is appended to the file, which the cube refuses for a panel-managed zone because the next render would overwrite it.

text
aegis cubes bind record  Manage records inside a zoneCommands  add     Append a record  remove  Remove a recordRun 'aegis cubes bind record <command> --help' for the options of one command.

#record add

bash
aegis cubes bind record add --domain example.com --type A --name www --value 203.0.113.10aegis cubes bind record add example.com "www IN A 203.0.113.10"
bash
aegis cubes bind record add --domain example.com --type MX --name @ --value mail.example.com --priority 10aegis cubes bind record add --domain example.com --type A --name www --value 203.0.113.10 --wildcard
OptionMeaning
zone, linethe file form: zone name and a complete record line
--domainthe field form: zone name; switches to the database when the panel owns the zone
--namerecord name, default @
--typeA, AAAA, CNAME, MX, TXT, NS, SRV, PTR, CAA or RAW
--value, --contentthe record data
--ttloptional TTL written after the name
--priorityMX and SRV preference
--weight, --portSRV fields; SRV requires a port 1–65535
--flags, --tagCAA fields; tag is issue, issuewild or iodef
--wildcardadd only: also write or add the * A record with the same address

Duplicate records are refused (record already exists for a panel zone, record already present for a file zone), names and values are validated per type, and the SOA serial is bumped before the zone is validated. --wildcard applies to an A record only.

text
✔ bind: record added: www IN A 203.0.113.10; configuration valid, 3 zones valid; stopped (pid 1044), started (pid 1079){"ok": true, "cube": "bind", "result": "record added: www IN A 203.0.113.10; configuration valid, 3 zones valid; stopped (pid 1044), started (pid 1079)"}

With --wildcard the result gains a note, for example ; wildcard added * -> 203.0.113.10 (* IN A 203.0.113.10) when the record is new, or ; wildcard left alone (a * A record is already present) when a * A record already exists.

#record remove

Destructive. Removes every stored record that matches the given fields, or every line identical to the one given. There is no confirmation step.

bash
aegis cubes bind record remove --domain example.com --type A --name www --value 203.0.113.10aegis cubes bind record remove example.com "www IN A 203.0.113.10"

Options are the same as record add, without --wildcard. In the database form the count of deleted rows is reported; in the file form a line that is not there fails with record not found: <line>.

text
✔ bind: 1 record(s) removed: www IN A 203.0.113.10; configuration valid, 3 zones valid; stopped (pid 1079), started (pid 1102){"ok": true, "cube": "bind", "result": "1 record(s) removed: www IN A 203.0.113.10; configuration valid, 3 zones valid; stopped (pid 1079), started (pid 1102)"}