Aegis documentation

#Cube: bind

BIND 9 as an authoritative resolver, configured from templates and driven by a TSIG key that certbot reuses for RFC 2136 updates.

In the panel: DNS Manager → Zones and records. Every write there is a task.

#Configuration

toml
[dns]ttl = 300ns1 = ""                          # default: ns1.<primary domain>ns2 = ""                          # default: ns2.<primary domain>config_dir = "/aegis/config/bind"zones_dir = "/aegis/data/bind/zones"key_name = "aegis-tsig"           # TSIG key certbot authenticates withrate_limit = 20                   # responses/second per client
KeyDefaultMeaning
ttl300TTL written into new zones
ns1, ns2emptynameservers advertised in new zones; empty uses ns1/ns2 of the primary domain
config_dir/aegis/config/bindnamed.conf and its includes
zones_dir/aegis/data/bind/zonesone .db file per zone plus the RNDC journal
key_nameaegis-tsigTSIG key shared with certbot for RFC 2136 updates
rate_limit20rate-limit responses per second, per client

Zone-wide identity (myhostname, primary_ip) is taken from server.toml, written by the installer, not from this section.

#Files

text
<aegis root>/config/bind/├── named.conf                     includes the two files below├── aegis-options.conf             listener, recursion no, rate limit├── aegis-local.conf               TSIG key, controls, zone includes├── keys/tsig.key                  shared with certbot (0600)└── zones.d/<domain>.conf          one stanza per zone<dns.zones_dir>/└── <domain>.db                    zone content

<run>/bind/named.pid and <logs>/bind/named.log are owned by the keeper.

#Commands

bash
aegis cubes bind configure      # render, seed the include, validateaegis cubes bind validate       # named-checkconf + named-checkzone for every zoneaegis cubes bind reload         # rndc reload, authenticated with the TSIG keyaegis cubes bind restart        # keeper restartaegis cubes bind start|stop|statusaegis cubes bind fix-journals   # drop stale .jnl files, then restartaegis cubes bind tsig           # print key name and secret

#expose

bash
aegis cubes bind exposecube           bindinstalled      /aegis/apps/dns/bind/9.21state          running pid 680051main config    /aegis/config/bind/named.confzones          1tsig key       /aegis/config/bind/keys/tsig.keypublished      /aegis/bin/named /aegis/bin/rndc /aegis/bin/dig 

configure also creates the zone for setup.primary_domain when it does not exist yet, and writes zones.d/00-empty.conf so include "zones.d/*.conf" never matches zero files.

#Zones

bash
aegis cubes bind zone listaegis cubes bind zone add example.comaegis cubes bind zone show example.comaegis cubes bind zone check example.comaegis cubes bind zone delete example.com

Initial content: SOA, two NS records, apex A, MX, SPF and DMARC TXT, serial YYYYMMDD01.

#Records

Fields, the same ones the panel form has:

bash
aegis cubes bind record add --domain example.com --type A --name www     --value 203.0.113.10 --ttl 300aegis cubes bind record add --domain example.com --type MX --name @     --value mail.example.com --priority 10aegis cubes bind record add --domain example.com --type SRV --name _sip._tcp     --value sip.example.com --priority 10 --weight 5 --port 5060aegis cubes bind record add --domain example.com --type CAA --name @     --value letsencrypt.org --tag issue --flags 0aegis cubes bind record add --domain example.com --type A --name www     --value 203.0.113.10 --wildcardaegis cubes bind record remove --domain example.com --type A --name www     --value 203.0.113.10

--wildcard (A records only) also writes the zone's * A record with the same address, so every name that has no record of its own answers with it. An existing wildcard is never overwritten: the command says what it found and leaves it alone.

text
record added: www IN A 203.0.113.10; wildcard added * -> 203.0.113.10; …record added: api IN A 203.0.113.11; wildcard left alone (* -> 203.0.113.10); …
OptionMeaning
--domainzone name
--namerecord name, relative to the zone; @ is the apex (default)
--typeA, AAAA, CNAME, MX, TXT, NS, SRV, PTR, CAA
--value (--content)the data: an address, a target, a text
--ttloptional TTL for this record
--priority, --weight, --portMX and SRV fields
--flags, --tagCAA fields (issue, issuewild, iodef)

Validation happens before anything is written, and it is the same validator the panel uses — one module, one set of messages:

text
✖ invalid IPv4 address: 999.1.1.1✖ 192.0.2.1 is not an IPv6 address✖ CAA tag must be one of issue, issuewild, iodef✖ an SRV record needs a port between 1 and 65535✖ a target must be a host name, not an address: 1.2.3.4✖ record not found: nope IN A 192.0.2.1

remove matches the record by its RDATA, so an MX is found with its priority and an SRV with its port; it deletes every row that matches and bumps the serial once.

#Zones the panel owns

The DNS Manager keeps its zones in dns.db and renders the files from those rows. For such a zone the command line writes the row and re-renders, so a record added here is visible in the panel and survives the next apply. The old raw-line form is refused for those zones:

bash
aegis cubes bind record add example.com "www  IN  A  203.0.113.10" zone example.com is managed by the panel; use --domain with --type and  --value so the record is stored where it renders from

A zone that exists only as a file (created with bind zone add and never imported) still accepts the raw-line form; spacing is normalised before the line is compared, so www IN A … and www IN A … are the same record. The two lines below are equivalent, and the serial is bumped automatically either way:

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

#TSIG

The key is generated once (hmac-sha256, 32 random bytes, base64) and never rotated behind certbot's back:

bash
aegis cubes bind tsigaegis-tsig 1a2b3c==

aegis-local.conf also declares the control channel:

text
controls {    inet 127.0.0.1 port 953 allow { 127.0.0.1; } keys { "aegis-tsig"; };};

reload therefore talks to 127.0.0.1:953 with -k keys/tsig.key.

#Journals

A zone rewritten while dynamic updates were enabled can fail with journal rollforward failed or answer SERVFAIL. fix-journals deletes *.jnl files and restarts the daemon.

bash
aegis cubes bind fix-journals

#Typical sequence

bash
aegis cubes bind configureaegis keeper start          # or: aegis cubes bind startaegis cubes bind zone add example.comaegis cubes bind zone check example.comaegis cubes bind reload# verificationdig @127.0.0.1 example.com SOA +short

#Troubleshooting

SymptomCause
named-checkconf failed with libisc-…sotools are called without the prefix libraries; the cube sets LD_LIBRARY_PATH, a manual run needs it too
named-checkconf missing in …BIND installed its tools in bin/; the cube searches both bin and sbin
rndc reload failedcontrols or the TSIG key mismatch; check keys/tsig.key and aegis-local.conf
zone answers SERVFAIL after a rewritefix-journals