Network architecture

The DNF network operates at two scales: an isolated local zone, then multiple zones connected by a mesh VPN. The vocabulary is defined in Concepts.

Simple network (one zone)

A zone is a gateway and its machines.

• The gateway shares Internet (NAT) and protects the zone (firewall).
• dnsmasq distributes addresses (DHCP) and resolves local names (<host>.<zone>).
• On the Internet side (WAN), everything is closed. On the local side (LAN), only SSH, DNS, DHCP and the home page are open.

Ad blocking (AdGuardHome)

Optional service, enabled on the gateway. It inserts itself in front of dnsmasq.

• AdGuardHome becomes the DNS resolver for workstations (port 53).
• It blocks ads and trackers, and encrypts queries to the outside.
• dnsmasq moves to an internal port and keeps local names and DHCP.

Extended network (VPN)

Multiple zones are connected by a mesh VPN, coordinated by the coordination server (HCS).

• The HCS (Headscale) is public and orchestrates the mesh.
• Each gateway is a subnet router: it publishes its zone’s subnet into the VPN.
• Zones can see each other; remote machines (smartphone, PC) join the network via Tailscale.
• A forwarder resolver on the HCS routes each zone to its own DNS.

Optional VPN

The mesh is only enabled if network.coordination.enable is true in etc/config.yaml. Without it, zones remain local and independent.

DNS names and resolution

Three families of names coexist on the network. All are generated from etc/config.yaml.

Name	Form	Scope	Example
Simple name	<host>	Entire internal network	server
Zone FQDN	<name>.<zone>.<domain>	Entire internal network	cloud.home.domain.tld
Global service	<name>.<domain>	Internet included	git.domain.tld

• Simple names : these are the machines (declared hosts). Resolved everywhere on the network, to the machine’s real address, regardless of its zone.
• Zone FQDNs : these are the services of a zone. They point to the gateway of that zone, which serves them via its reverse proxy.
• Global services : services marked global in etc/config.yaml. Exposed on the HCS with public DNS : reachable from anywhere.

Who resolves what :

• dnsmasq, on each gateway, knows all internal names (machines and services of all zones) : it resolves simple names and FQDNs.
• The current zone is resolved locally ; other zones and the global domain are routed to the correct gateway, or to the HCS pivot resolver.
• Public (Internet) names go to upstream encrypted DNS, filtered by AdGuardHome if enabled.

The pivot resolver (HCS)

On the coordination server (HCS), a pivot resolver centralizes the internal DNS resolution of the VPN. It knows the zone layout and merely routes :

• each zone FQDN to its zone’s gateway ;
• the rest to an encrypted external DNS.

All VPN machines query it on the HCS’s VPN address. It bridges zones together for name resolution.

Resolution from outside

A machine outside any zone (laptop on the go, smartphone) joins the network via the VPN. Its DNS resolution is split (split-DNS) according to the type of name requested:

• internal names: routed, through the VPN, to the HCS hub resolver, which then directs them to the correct gateway;
• public names: resolved by the local resolver of the visited network (ISP box, public access point), without going through the VPN.

Why not route public names through the VPN

Routing everything through the HCS resolver tunnels all DNS traffic inside the VPN. If the VPN path degrades (intermediate relay, blocked UDP), nothing resolves anymore. Leaving public names to the local resolver preserves Internet access even when the VPN link is unstable.

Device reconnected in a zone

A roaming laptop reconnected via ethernet in a zone no longer needs the VPN to reach it. Its VPN client then pauses to hand control back to the local gateway (direct resolution and routing), then reactivates upon departure.

Machines outside their zone

A machine is declared in one zone, but it is not always there. A laptop goes on the road. A new gateway is installed from another zone, before being delivered on site.

Without special provision, this machine receives an arbitrary address from the DHCP range of the visited zone, and its name keeps pointing to its original address, unreachable from there. Nothing allows reaching it reliably.

A reserved address in each zone

Each zone reserves the <prefix>.6.x block for machines from the other zones. The generator places a DHCP reservation there for every MAC address known on the network that does not belong to the zone.

The number is assigned at the scale of the whole network : a machine keeps the same last octet in every zone it visits.

Machine	Declared zone	At home	Visiting atelier
portable	maison	10.0.2.4	10.1.6.3
serveur	atelier	10.1.1.2	(it is at home there)

The address is therefore known before the machine boots, without observing anything on the network.

A name that designates the place

The reservation comes with a DNS name in the visited zone. The simple name, for its part, keeps its meaning.

Name	Resolves to
portable	its original address, everywhere on the network
portable.atelier.domain.tld	its address in the atelier zone

A lease that never changes

dnsmasq indexes leases on the MAC address alone, and not on the DHCP client identifier.

The reason : the same device does not advertise the same identifier depending on the system running on it. An installation image and the installed system pass for two different machines, and receive two addresses. By relying on the MAC, the address no longer changes between installation and the first real boot.

Machines without a declared MAC address

The reservation requires a mac key in etc/config.yaml. Without it, the machine stays reachable at home, but not elsewhere.

What the tooling does

The installation recipes compute the address by themselves. They first identify the zone where the administration machine is located, from its real default gateway and not from its declared zone (an administration laptop is precisely what moves around), then deduce the address of the target.

What remains is deployment : Colmena 🡕 addresses a node by its name, which designates the original address. For a visiting host, just configure therefore sets up a temporary SSH redirect, removed at the end of the installation or by hand :

just roaming             # show the current redirects
just roaming-clear       # remove them all