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.