feature: the name server's domains have wan.local_fqdn and dns.secondary as their name servers, and a site with dns router gets records of the router's public, internal or external address.
Release / release (push) Successful in 35s

This commit is contained in:
slawek committed 2026-11-06 19:06:48 +01:00
1 parent c2c33cfca0
commit 7f85a1a2e5
16 files changed
+497 -304

No files matched your search

+43 -29
View File
@@ -15,7 +15,7 @@ A Debian package that configures a Linux host or virtual machine as a VPN router
- metrics of the router kept in PostgreSQL, served for an OpenTelemetry Collector and pushed
over OTLP
- static web sites served by Caddy, uploaded through the web service or WebDAV, and an optional
primary name server (PowerDNS) of the router's domains, with secondaries and records for the sites
primary name server (PowerDNS) of the router's domains, with a secondary and records for the sites
Nothing in the package is specific to a cloud provider. It is built on the external and
internal NIC names, and a `mode` setting says how much of the rest you are supplying and
@@ -108,7 +108,8 @@ must have the type shown below; an unknown section or setting is an error.
| `general` | `mode` | string | `manual` | How much you supply: `manual`, `interfaces` or `auto` |
| `interfaces` | `external` | string | | Name of the NIC facing the untrusted network |
| `interfaces` | `internal` | string | | Name of the NIC facing the protected network |
| `wan` | `local_fqdn` | string | | This router's name or IP address: its IKE identity in `fqdn` mode, the name resolved in `public_ip` mode, and the name of HTTPS, IKEv2 and OpenVPN |
| `wan` | `local_fqdn` | string | | This router's name or IP address: its IKE identity in `fqdn` mode, the name resolved in `public_ip` mode, the name of HTTPS, IKEv2 and OpenVPN, and the primary name server of its domains |
| `wan` | `public_address` | string | | The router's public IP address, which its own interfaces do not show behind a cloud's NAT: the address of the records of the sites with `dns_address` `public` |
| `local` | `cidrs` | list | | Local subnets routed via the internal side, masqueraded to the external one, and offered to IKEv2 and OpenVPN clients |
| `local` | `int_addr` | string | | This host's address on the internal network |
| `local` | `int_gateway_ip` | string | | Next hop on the internal side |
@@ -148,9 +149,8 @@ must have the type shown below; an unknown section or setting is an error.
| `sites` | `upload_max_mb` | integer | `512` | The largest upload of a site's file or zip archive, in MiB, 1 to 10240 |
| `sites` | `webdav` | boolean | `false` | WebDAV of the sites' folders, which needs `https.enabled` and `wan.local_fqdn` (see WebDAV) |
| `sites` | `webdav_port` | integer | `7445` | HTTPS port of WebDAV |
| `dns` | `enabled` | boolean | `false` | The primary name server of the router's domains, which needs `dns.nameserver` and `dns.addresses` (see Name server) |
| `dns` | `nameserver` | string | | The name server's host name, the primary NS of every domain |
| `dns` | `addresses` | list | | The public addresses of the name server, the domains' apexes and the sites' host names |
| `dns` | `enabled` | boolean | `false` | The primary name server of the router's domains, `wan.local_fqdn`, which must then be a DNS name (see Name server) |
| `dns` | `secondary` | string | | The secondary name server of every domain, a host name other than `wan.local_fqdn`; it may transfer the domains |
| `dns` | `listen` | string | `external` | The interfaces the name server answers on: `internal`, `external` or `both` |
| `dns` | `ttl` | integer | `300` | TTL of the records, 60 to 86400 seconds |
| `pki` | `root_name` | string | `VPN Router Root CA` | Common name of the root CA, when the router creates it |
@@ -1226,13 +1226,11 @@ curl -X PUT -H "Authorization: Bearer $TOKEN" --data-binary @site.zip \
| Request | Answer |
| --- | --- |
| `GET /dns` | `{"settings", "installed", "running", "domains", "problem"}`: the `dns` section, whether PowerDNS is installed and runs, the domains, each `{"name", "sites", "ttl", "secondaries", "manual", "records"}` with its secondaries `{"nameserver", "address"}`, its manual records and the records it serves, and why they cannot be read, `null` when they can |
| `PUT /dns` | Changes any of the settings of the `dns` section |
| `POST /dns/domains` | Adds a domain: `{"name", "sites"?, "ttl"?}`; an existing name is 409 |
| `PUT /dns/domains/<domain>` | Changes `sites` or `ttl` of the domain |
| `DELETE /dns/domains/<domain>` | Removes the domain with its secondaries and manual records |
| `POST /dns/domains/<domain>/secondaries` | Adds a secondary name server, or changes its address: `{"nameserver", "address"}` |
| `DELETE /dns/domains/<domain>/secondaries/<nameserver>` | Removes the secondary name server |
| `GET /dns` | `{"settings", "nameserver", "public_address", "installed", "running", "domains", "problem"}`: the `dns` section, `wan.local_fqdn`, the primary name server, `wan.public_address`, whether PowerDNS is installed and runs, the domains, each `{"name", "ttl", "manual", "records"}` with its manual records and the records it serves, and why they cannot be read, `null` when they can |
| `PUT /dns` | Changes any of the settings of the `dns` section, and with `public_address` `wan.public_address`; answers `{"settings", "public_address"}` |
| `POST /dns/domains` | Adds a domain: `{"name", "ttl"?}`; an existing name is 409 |
| `PUT /dns/domains/<domain>` | Changes `ttl` of the domain |
| `DELETE /dns/domains/<domain>` | Removes the domain with its manual records |
| `POST /dns/domains/<domain>/records` | Adds a manual record: `{"name", "type", "content", "ttl"?}`; `name` is relative to the domain, `@` for the domain itself, or absolute with a final dot, and `ttl` is the domain's without it |
| `DELETE /dns/domains/<domain>/records?name=&type=&content=` | Removes the manual records of the name and type, only the one of `content` when it is given |
@@ -1741,10 +1739,15 @@ Router Manager, each change applied by restarting `vpn-router-setup`. A site has
| `index_file` | The file served for a folder, `index.html` by default |
| `spa` | Whether a path without a file is served the site's `index_file`, for single-page applications |
| `editors` | The group whose members may change the site's files besides the admins |
| `dns` | Who serves the records of its host names: `user` (the default), a DNS provider outside the router, or `router`, the router's name server (see Name server) |
| `dns_address` | With `dns` `router`, the router's address in the records: `public` (the default, `wan.public_address`), `internal` or `external` |
A site may not take a port of the router's own services (SSH, `web.port`, the HTTPS ports, the
metrics ports, the Router Manager's, `sites.webdav_port`, 7446, 53, the bootstrap ports, a TCP
`openvpn.port` and `docker.exposed_ports`) or `wan.local_fqdn`. Enabled sites on one port need host
`openvpn.port` and `docker.exposed_ports`). It may use `wan.local_fqdn` as a host name, on a port
of its own, such as 443, which the router's services leave free; its record is then kept where the
domain of `wan.local_fqdn` is, so `dns` `router` takes neither it, nor wildcards or addresses, and
`public` needs `wan.public_address`. Enabled sites on one port need host
names of their own, the same `listen` and the same kind of TLS (plain HTTP or HTTPS). A site of
`acme` needs host names, without wildcards or addresses, that resolve to the router, and port 80,
which setup opens on the external interface. The certificate of `file` must be the key's and name
@@ -1803,32 +1806,43 @@ missing, without the recommended bind backend.
| Setting | Meaning |
| --- | --- |
| `dns.nameserver` | The name server's host name, the primary NS and the SOA's primary of every domain |
| `dns.addresses` | The public addresses of the domains' apexes, of the name server in a domain it is inside, and of the sites' host names |
| `wan.local_fqdn` | The primary name server of every domain: the SOA's primary and the first NS |
| `dns.secondary` | The secondary name server of every domain, the second NS; the addresses it resolves to are notified of every change and may transfer the domains (AXFR) |
| `dns.ttl` | The TTL of the records and the SOA's negative TTL of a domain without its own, 60 to 86400 seconds, 300 by default |
A domain the router hosts, for example `example.com`, with `wan.local_fqdn` `router.other.net`,
`dns.secondary` `ns2.provider.net` and a site of `www.example.com` and `example.com` with `dns`
`router` and `dns_address` `public` (`wan.public_address` `203.0.113.10`):
```text
example.com. SOA router.other.net. hostmaster.example.com. <serial> 10800 3600 604800 300
example.com. NS router.other.net.
example.com. NS ns2.provider.net.
example.com. A 203.0.113.10
www.example.com. A 203.0.113.10
```
The domains are added with `/dns` or the Router Manager, each with:
- **Site records**: every host name of an enabled site gets A and AAAA records of `dns.addresses`
in the closest domain it is in, when that domain has site records;
- **TTL**: the TTL of its records, `dns.ttl` when not set;
- **Secondaries**: name servers, each a host name, which becomes an NS of the domain, and the
address it transfers the domain from. The router notifies that address of every change and
allows it zone transfers (AXFR); a secondary's name inside the domain gets an A or AAAA record of
that address;
- **Manual records** (A, AAAA, CNAME, TXT, MX, SRV, CAA), served too, but not those of a name and
type the domain's own records have.
A domain inside another domain of the router is delegated from it with NS records. Setup writes the
domains at each run, and after each change through `/dns`; the SOA's serial grows only when the
records change. While IKEv2, OpenVPN or WireGuard is enabled, dnsmasq answers their clients on port 53
of the addresses of `p2s.dns_listen`, by default the internal address, so `dns.listen` must not
share an interface with it. The parent zone of each domain must delegate it to `dns.nameserver` and
the secondaries, with glue records for name servers inside the domain.
The host names of an enabled site with `dns` `router` get an A or AAAA record of its `dns_address`
in the closest domain they are in; a site with `dns` `user` gets none, and a host name in no domain
of the router gets none either. `wan.local_fqdn` gets no record in the domains: its A record is kept
by the DNS of its own domain, wherever that is. A domain inside another domain of the router is
delegated from it with NS records. Setup writes the domains at each run, and after each change
through `/dns`; the SOA's serial grows only when the records change. While IKEv2, OpenVPN or
WireGuard is enabled, dnsmasq answers their clients on port 53 of the addresses of
`p2s.dns_listen`, by default the internal address, so `dns.listen` must not share an interface with
it. The parent zone of each domain must delegate it to `wan.local_fqdn` and `dns.secondary`, with
glue records for those of them inside the domain. While `dns.secondary` is not set, the domains have
`wan.local_fqdn` as their only name server, and setup warns.
```sh
vpn-config-edit set dns.nameserver ns1.example.com
vpn-config-edit set dns.addresses 203.0.113.10
vpn-config-edit set dns.secondary ns2.provider.net
vpn-config-edit set wan.public_address 203.0.113.10
vpn-config-edit set --restart dns.enabled true
```