Configuring DNS Tutorials with Reserved TLDs Safely

DNS tutorials have an odd constraint: they need hostnames that look realistic, yet must not collide with anything on the public Internet. A single copy-pasted command from a training guide can trigger real DNS queries, web requests, or emails, and those can land on systems you did not intend to touch. Reserved top-level domains (TLDs) exist to prevent that class of mistake, and they make instructional material safer when they are used with the right resolver and lab setup.

Reserved TLDs and reserved example domains

The IETF set aside several names in RFC 2606, and later reinforced behaviors in RFC 6761, so authors can write documentation and build tests without accidentally targeting real domains. These names are intentionally non-delegated in the global DNS (or treated as special-use), which keeps examples from turning into production dependencies.

The core set from RFC 2606 is small, and each item has a distinct job.

Name	Primary intent	Expected behavior in resolvers	Good fit for
`.test`	Testing DNS code and lab environments	Often treated as “do not send to the Internet” unless explicitly served locally	Hands-on labs with a local zone
`.example`	Documentation examples	No special resolver behavior required	Static documentation and diagrams
`.invalid`	Names that must be invalid	Should always yield NXDOMAIN without external lookup	Error paths and negative tests
`.localhost`	Loopback naming	Should resolve locally to loopback and not be sent to DNS	Local-only service examples
`example.com/.net/.org`	Reserved second-level domains maintained by IANA	They exist and resolve publicly to informational content	Prose examples, screenshots, not lab endpoints

Two related names show up often in technical writing but require extra care: .local is designated for multicast DNS (mDNS) on a link, and .onion is for Tor services. Neither is a general-purpose DNS tutorial namespace.

Choosing the reserved name that matches the lesson

A tutorial typically mixes two kinds of examples: names you want learners to read, and names you want systems to resolve during exercises. Treat those as separate requirements.

.example is suited to “read-only” documentation: configuration excerpts in a book, slides, or diagrams where no one should run the command. If a reader does run it, normal DNS rules apply, which can lead to confusing results if their resolver finds something unexpected on their network.

.test is better when you expect learners to run dig, point a resolver at a lab server, or load a web app in a sandbox. It communicates “this is not real” while still looking like a typical private domain. It also pushes you toward the correct practice: serve the zone locally inside the lab.

.invalid is useful when the point of the exercise is failure. It prevents accidental “success” caused by search suffixes, split-horizon DNS, or wildcarding in a corporate environment.

.localhost is only for loopback. Treat it as a statement that the service is on the same machine, not as a domain you will delegate, host in BIND, or publish in a tutorial zone.

A practical naming pattern many instructors adopt is: use .example in prose, and reserve .test for anything learners will type and execute.

Preventing accidental outbound DNS traffic

Reserved names reduce the chance of namespace collisions, but they do not automatically guarantee isolation. A lab can still leak queries to an upstream resolver if the client is misconfigured, the recursive resolver forwards everything, or a “helpful” search list expands names into other suffixes.

To keep tutorials safe and repeatable, set an explicit boundary: either a local authoritative zone, a recursive resolver with local-zone rules, or full network isolation (or all three).

Common control points that work well in classroom and self-guided labs include:

• Local authoritative DNS: Serve lab.test. from a DNS server in the sandbox so all answers are local.

• Recursive resolver policy: Configure Unbound, dnsmasq, or systemd-resolved to synthesize NXDOMAIN or loopback for reserved suffixes.

• Host overrides: Pin a small set of names to specific IPs via a hosts file when you want zero resolver variability.

• Network isolation: Remove a default route, block outbound UDP/TCP 53, or use a host-only VM network so “leaks” cannot leave the machine.

• Search list hygiene: Keep search domains empty in the lab, or teach fully qualified domain names with a trailing dot.

A lab pattern that works: lab.test as the zone apex

If learners will run real queries, define a dedicated zone and keep it inside the environment. A simple approach is one authoritative server plus one client resolver that points to it.

Example: BIND authoritative zone for lab.test.

A minimal named.conf fragment:

zone "lab.test" {
  type master;
  file "/etc/bind/zones/db.lab.test";
  allow-transfer { none; };
};

A minimal zone file:

$TTL 300
@   IN SOA ns1.lab.test. admin.lab.test. (
        2026012401  ; serial
        3600        ; refresh
        900         ; retry
        1209600     ; expire
        300 )       ; negative TTL
    IN NS  ns1.lab.test.

ns1 IN A   192.0.2.53
www IN A   192.0.2.80
api IN A   192.0.2.81

Two notes matter for tutorials:

1. Use documentation IP ranges (192.0.2.0/24, 198.51.100.0/24, 203.0.113.0/24) in printed examples, then tell learners what IPs to substitute in their lab.

2. Keep TTLs short so changes during exercises take effect quickly.

Example: Unbound local-zone controls for reserved suffixes

If the goal is “nothing leaves the box,” Unbound can enforce that even when the upstream network is present:

server:
  # For a tutorial machine that should not query the public DNS for these:
  local-zone: "invalid." always_nxdomain
  local-zone: "test." always_nxdomain
  local-zone: "localhost." static

  local-data: "localhost. 60 IN A 127.0.0.1"
  local-data: "localhost. 60 IN AAAA ::1"

When you actually want .test to work inside a lab, override the default negative behavior by serving the specific zone you control, such as lab.test..

Example: dnsmasq quick mapping for a contained demo

For small demos, mapping an entire suffix to a single address can be enough:

# Send all names under .test to a local web server for a UI demo
address=/.test/127.0.0.1

This is not a substitute for teaching proper zone design, but it is effective for lightweight workshops.

Documentation examples: where Example Domain fits

Example Domain, in the general sense of the reserved “example” naming space, works best when you are illustrating syntax:

• dig www.example.com

• curl https://example.com/

• server_name app.example; (in a configuration excerpt)

Avoid using example.com as an endpoint for lab steps that must succeed with a particular IP or service behavior. Because it is real and reachable, it can mask problems in a learner’s local DNS setup by “working” even when the lab resolver is wrong.

Naming conventions that reduce student error

Clear naming is part of safety. A learner who can immediately spot the boundary between “lab-only” and “Internet” is less likely to copy a name into a production terminal.

A simple convention is to reserve one suffix per purpose, and to make the role visible in the left-most label: ns1.lab.test, www.lab.test, db01.lab.test.

A few practical habits help prevent resolver surprises:

• Fully qualified names: Use a trailing dot in diagnostic commands when teaching DNS fundamentals, like dig www.lab.test..

• Lowercase everywhere: DNS is case-insensitive, yet lowercase avoids visual ambiguity in tutorials.

• No mixed namespaces: Do not switch between .test and a corporate internal suffix in the same lab narrative.

• Avoid .local for DNS labs: It often routes into mDNS behavior, which changes the debugging story.

Security and correctness pitfalls that still show up

Reserved names are a safety net, not a security boundary. A few issues occur repeatedly in training environments.

One is query expansion from search lists. A learner types www and the system tries www.corp.example, www.home, and other suffixes, generating noise and confusing packet captures. If you teach short names, teach the resolver rules at the same time, and keep the lab’s search list empty.

Another is spoofing inside the local network. If the lab network is shared, a malicious or misconfigured DNS server can answer .test queries with unexpected data. The fix is operational: give the resolver address explicitly, isolate the network, and, when appropriate, show learners how to verify the destination of DNS traffic with a packet capture.

The last is misuse of .localhost. Many systems treat localhost and *.localhost as special and do not send them to DNS at all. That is good for safety, but it means .localhost is a poor choice when the educational goal is “observe DNS packets” or “configure an authoritative zone.”

Standards to cite in training material

Reserved names are easier to defend in reviews when the tutorial references the standards bodies that reserved them.

RFC 2606 defines the reserved names for documentation and testing, RFC 6761 documents special-use domain name behaviors for resolvers, and IANA maintains a public registry page for reserved domains (including example.com, example.net, and example.org). Including one short citation near the first use of .test or .example usually prevents confusion and reduces the chance that someone “improves” the tutorial by replacing safe names with real ones.