DNS/DHCP(at)Work

1. Purpose

DNS/DHCP(at)Work is a DNS server and a DHCPv4 server for closed test networks and labs. It answers from its own zones and records, and it can give wrong answers on purpose – NXDOMAIN, SERVFAIL, REFUSED, no answer, slow answers, truncated answers or other addresses – so you can test how equipment and software handle failures in name lookups and address assignment.

It is delivered as an offline package for Rocky Linux 9 and uses only Python 3.9+ and the standard library. It does not use dnsmasq, BIND or Kea.

2. Structure

One Python process (python3 -m dnsdhcp serve) with three parts that share the settings and the event log: the DNS server, the DHCP server and the web GUI.

                 +--------------------------- dns-dhcp-tester.service ---------------------------+
 DNS clients  -> | UDP/TCP 53   dns_server.py  -- rules -> records -> PTR -> zones -> forwarding   |
 DHCP clients -> | UDP 67       dhcp_server.py -- address choice, leases, fault mode --> names to DNS|
 browser      -> | TCP 8053     web.py         -- JSON API + static/ (EN/NO)                         |
                 |              store.py (config.json)   eventlog.py (events.jsonl)                  |
                 +-----------------------------------------------------------------------------------+

The settings are read again for every query and every DHCP message, so changes to records, rules, pool and fault mode apply at once. Only a new address, port or interface restarts a listener.

3. DNS

3.1. Order for a query

1. Rules, top to bottom. The first rule that matches the name (pattern with * and ?), the type and the client network decides.
2. Own data: the records and the names from DHCP (leases and reservations with a host name). First the exact name, otherwise the closest *. wildcard. CNAMEs are followed up to 8 steps. A name that exists without the type asked for gives NODATA (NOERROR without answers) with the SOA.
3. Automatic PTR from the A and AAAA records, for in-addr.arpa and ip6.arpa.
4. Own zones: a name in a zone that does not exist gives NXDOMAIN with the SOA. SOA and NS for the zone apex are made automatically.
5. Other names are forwarded to the configured servers (UDP, 2 s timeout per server). Without forwarding the server answers REFUSED, or NXDOMAIN or SERVFAIL if chosen.

Answers from own data and zones have the AA flag set. RA is set when forwarding is configured.

3.2. Rules

Delay ms (0–30 000) applies to every action. The clients field takes addresses and networks (CIDR) for IPv4 and IPv6. The rule that matched is shown in the log and counted in the statistics.

3.3. Answer size and TCP

Over UDP the limit is 512 bytes, or the EDNS size the client announces (512–4096). A larger answer is sent without records and with the TC flag, and the client asks again over TCP. When the query has an OPT record, the answer has one too (UDP size 1232). TCP uses the 2-byte length prefix (RFC 1035 4.2.2), and several queries can be sent on the same connection.

3.4. Record types

4. DHCP

• Address choice: reservation → the client’s existing lease → requested address (option 50) → the first free address in the pool.
• An offer is held for 60 s. An address a client rejects with DECLINE is held back for 600 s.
• A REQUEST with another server’s identifier frees the offer. When the server is authoritative, a client asking for an address that is not valid here gets a NAK.
• Replies go to the relay agent (giaddr, port 67), to the client’s address (ciaddr, port 68) on renewal, and otherwise as a broadcast to 255.255.255.255, port 68.
• Options: 1 subnet mask, 3 router, 6 DNS, 12 host name, 15 domain, 28 broadcast address, 42 NTP, 51 lease time, 54 server identifier, 58 T1, 59 T2, 66 TFTP server, 67 boot file.
• Without configured DNS servers, clients get the server’s own address when the DNS server is on.
• With an interface chosen, the listener is bound with SO_BINDTODEVICE, and the server address is taken from the interface (SIOCGIFADDR). Otherwise the address towards the router is used.
• Leases are stored in leases.json and survive a restart.

DHCP clients that send a host name (option 12) get the name <host name>.<domain> in DNS while the lease is valid. Reservations with a host name are always included.

5. Settings and validation

The settings are stored in /var/lib/dns-dhcp-tester/config.json, with one part for DNS and one for DHCP. Everything from the web GUI is checked before it is saved. An error gives HTTP 400 with a readable message, and nothing is saved.

• Names, zones and name patterns are checked against allowed characters and lengths.
• Addresses, networks, ports, TTLs, delays and lease time are checked against valid ranges.
• The DHCP pool must be within one network, the start must come before the end, and the pool can have at most 65 536 addresses. Reservations must be in the network, and no MAC or IP address can be used twice.
• If the file is damaged or invalid at start-up, the defaults are used and a warning is shown in the web GUI and the log.

6. Web API

Every call requires login. Every POST also requires the header X-Requested-With: dnsdhcp-ui.

7. Security

• Login: HTTP Basic with the user admin. The password is stored as PBKDF2-SHA256 with 200 000 rounds and a random salt. Ten wrong passwords within a minute from one address give a one-minute pause.
• CSRF: a POST without the header X-Requested-With: dnsdhcp-ui is rejected with 403. Other web sites cannot set the header.
• Headers: Content-Security-Policy without inline scripts and styles and without external sources, X-Frame-Options DENY, nosniff, no-referrer and no-store.
• The service runs as the system user dnsdhcp with only CAP_NET_BIND_SERVICE (ports 53 and 67) and CAP_NET_RAW (binding to an interface), and with full systemd hardening. It can only write to /var/lib/dns-dhcp-tester.
• DHCP is off after installation, and the web GUI asks before it is turned on.
• The web GUI uses HTTP. Limit access with install.sh --admin-net <network> or a separate management network.

8. Files and service

install.sh checks the package checksums and that the ports are free, shows which process uses port 53, 8053 or 67 if any, opens the ports in firewalld or ufw and ends by checking the web GUI and DNS. Running install.sh again is an upgrade that keeps settings, leases, log and password.

9. Port map of the (at)Work tools

All the tools can therefore run on the same server.

10. Self test and tools

python3 tools/selftest.py starts DNS, DHCP and the web GUI on random high ports on 127.0.0.1 and runs 44 tests without touching the service:

• lookups of all record types, CNAME, wildcards, NXDOMAIN, NODATA, SOA/NS, PTR, truncation and EDNS;
• every rule action, type filter, client filter and order;
• forwarding (when the test runs as root and port 53 is free);
• the DHCP exchange DISCOVER–OFFER–REQUEST–ACK, reservation, NAK, full pool, RELEASE, DECLINE and every fault mode;
• validation of settings, login, CSRF protection and the API.

tools/probe.py dns <name> asks a DNS server over UDP or TCP. tools/probe.py dhcp sends a DISCOVER and shows every offer, without taking an address.

11. Limitations of the draft

• DHCP for IPv4 and one network only. No DHCPv6.
• DNS without DNSSEC, zone transfer (AXFR) and dynamic updates (RFC 2136).
• Forwarding over UDP to port 53, without a cache.
• The web GUI uses HTTP, not HTTPS.