Homelab Academy
Full learning cycle with mandatory Feynman teach-back, retrieval practice, lab, and mastery gate. Prefer current official docs in References.
Learning objective: Explain the roles of stub resolvers, recursive resolvers, authoritative data, and DNS caches.; Create local A records that map friendly service names to private IPv4 addresses.; Use home.arpa instead of invented top-level domains or the multicast-oriented local suffix.; Query a specific DNS server and nonstandard port with dig.; Interpret NOERROR, NXDOMAIN, answer sections, record types, and time-to-live values.; Describe the operational requirements for making local names available to an entire LAN.; Identify common causes of inconsistent local name resolution.
Bloom level: Understand / Apply
Track: Networking and Core Services · Difficulty: intermediate · Duration: ~75 minutes · Lab risk: low
Mastery unlock: ≥80% quiz + completed Feynman teach-back + lab verification + homework evidence.
Last reviewed: 2025-03-08
Compatibility: ### platforms
Linux systems capable of running dnsmasq and dig
Virtual machines
Physical homelab hosts
Linux containers with loopback networking and permission to create the specified workspace
dnsmasq with support for host-record, local, listen-address, bind-interfaces, and configuration testing
dig with support for selecting a DNS server and port
A POSIX-compatible shell
Permission to create /opt/lab-classroom/class65/
Available loopback port 1053
Command output formatting can vary across dnsmasq and dig releases.
The lab uses IPv4 loopback and synthetic private IPv4 answers; it does not require the target service addresses to exist.
Systems with mandatory access-control policies may deny dnsmasq access to an unconventional configuration or log path. Do not weaken host policy for this exercise.
The lab does not alter resolver configuration and therefore does not make the names available to ordinary applications.
Teach learners how local DNS converts memorable service names into IP addresses, why home.arpa is the appropriate namespace for residential networks, and how to test a private DNS namespace safely without changing the host resolver or exposing a DNS service to the LAN.
Answer briefly before reading Instruction.
| Term | Meaning |
|---|---|
| DNS | The Domain Name System, a distributed naming system that maps names to records such as IPv4 and IPv6 addresses. |
| Stub resolver | The client-side component that sends DNS questions to a configured resolver on behalf of applications. |
| Recursive resolver | A DNS service that obtains answers for clients, commonly by consulting other DNS servers and caching the results. |
| Authoritative data | DNS data served from the source responsible for a namespace rather than learned from another resolver. |
| A record | A DNS resource record that maps a name to an IPv4 address. |
| AAAA record | A DNS resource record that maps a name to an IPv6 address. |
| CNAME record | A record that aliases one DNS name to another DNS name. |
| PTR record | A record generally used for reverse lookup from an address-oriented DNS name to a host name. |
| FQDN | A fully qualified domain name that identifies a name within the complete DNS hierarchy, such as dashboard.home.arpa. |
| TTL | Time to live, the number of seconds for which a DNS response may normally be cached. |
| NXDOMAIN | A DNS response code indicating that the requested domain name does not exist. |
| Split DNS | A design in which the answer for a name depends on which resolver or network view receives the query. |
| home.arpa | The special-use domain reserved by RFC 8375 for names within residential home networks. |
People remember names more reliably than addresses. A bookmark such as https://dashboard.home.arpa is easier to recognize and maintain than https://10.20.30.40. DNS supplies the translation, but it does not create application connectivity, configure a reverse proxy, or guarantee that a service is healthy. It only returns records in response to questions. A typical application asks the operating system's stub resolver for an address. The stub resolver sends the question to a configured recursive resolver, which may answer from cache, consult authoritative servers, or return an error. In a homelab, one resolver can also hold private records for internal services.
Local naming should use a deliberate namespace. RFC 8375 reserves home.arpa for residential home networks. The local suffix should generally be avoided for ordinary unicast DNS because it is conventionally associated with multicast DNS and may be handled differently by operating systems. Public domains that you do not control are also poor choices because future public records can conflict with private assumptions. Organizations that own a public domain may instead delegate or privately serve a subdomain, but that requires disciplined administration.
An A record maps a name to an IPv4 address, while an AAAA record maps a name to an IPv6 address. A CNAME points one name at another name and is useful for aliases, although clients must still resolve the target. DNS record design should represent stable service identities. For example, dashboard.home.arpa can remain constant while its address changes. Update the central record rather than editing bookmarks and application configurations across many clients.
Caching improves speed and reduces repeated work, but it also explains why DNS changes do not always appear immediately. A cached answer can remain in use until its TTL expires. Multiple clients can see different answers when they use different resolvers, retain different cache entries, or bypass the intended LAN resolver. Troubleshooting should therefore identify the exact resolver being queried, test the full name, inspect the response code, and compare direct queries with application behavior.
This lab runs dnsmasq only on 127.0.0.1:1053 and supplies an explicit configuration file. Port 1053 avoids the privileged standard DNS port and prevents the exercise from replacing the machine's configured resolver. The no-resolv and no-hosts settings make the source of the lab answers clear: only records written into the lab configuration are available. The local directive declares home.arpa as locally answered, so a missing name under that suffix should produce NXDOMAIN instead of being forwarded elsewhere. Because clients are not reconfigured, every test explicitly selects the server and port with dig.
A production design normally places a redundant or highly available resolver at stable LAN addresses, distributes those addresses to clients through network configuration, restricts who may query or administer the service, maintains both IPv4 and IPv6 records where appropriate, and monitors response health. Friendly names also belong in service documentation and certificates. If an HTTPS certificate does not contain the friendly name, DNS may resolve correctly while the browser still reports an identity error. Treat DNS as one layer in the service path, not as a substitute for routing, transport security, access control, or application monitoring.
A client shell running dig.
A dnsmasq process bound only to 127.0.0.1 on UDP and TCP port 1053.
A lab-owned configuration file containing records for dashboard.home.arpa and nas.home.arpa.
A query log and process identifier stored beneath /opt/lab-classroom/class65/.
dig sends a DNS question directly to 127.0.0.1 port 1053.
dnsmasq checks the records defined in the lab configuration.
A known name receives an A-record answer.
An unknown name under home.arpa receives an NXDOMAIN response.
No upstream DNS server is consulted because the lab disables resolver-file processing and treats home.arpa as local.
The exercise is loopback-only. It does not modify the operating system resolver configuration, advertise DNS to other clients, or listen on a LAN interface.
dig client -> 127.0.0.1:1053 -> dnsmasq -> local host-record data -> DNS response
See the worked example embedded in Instruction; reproduce it on your disposable lab path.
Complete the guided lab steps with hints allowed, then restate results in your own words.
Design a naming plan for at least five homelab services using home.arpa. Include the service purpose, chosen name, address family, owner, and expected change frequency.
Draw the query path from an application to a stub resolver, then to a recursive resolver, cache, and authoritative source.
Explain how you would provide two resilient DNS resolver addresses to LAN clients without creating a circular dependency.
Research the difference between A, AAAA, CNAME, and PTR records and provide one appropriate homelab use case for each.
Write a change procedure for moving dashboard.home.arpa to a new address while minimizing the impact of cached answers.
Document how you would determine whether a client is bypassing the intended local resolver.
Explain local DNS to someone who knows that computers have IP addresses but has never administered a network.
A local DNS server is like a private address book. Instead of remembering that a dashboard lives at 10.20.30.40, a user asks for dashboard.home.arpa. The computer sends that question to a DNS resolver, and the resolver replies with the address stored for that name. The name can stay the same even if the service later moves to another address. Cached copies make repeated lookups faster, but they can temporarily preserve an old answer after a change. DNS only tells the client where to try connecting; it does not prove that the service is running or trusted.
Can you distinguish a DNS answer from proof that an application is healthy?
Can you explain why two clients might temporarily receive different answers?
Can you explain why home.arpa is preferable to an invented suffix?
Can you describe why this lab uses 127.0.0.1:1053 instead of replacing the host resolver?
Answers save in this browser (localStorage). Completing all five fields is part of the mastery unlock.
Build and query an isolated home.arpa namespace
/opt/lab-classroom/class65/
All files created or changed by the lab remain under /opt/lab-classroom/class65/.
The DNS listener is restricted to the loopback address.
The host resolver configuration is not changed.
The service uses nonstandard port 1053.
Do not continue if another process already owns 127.0.0.1:1053.
1
Confirm required commands
command -v dnsmasq
command -v dig
Both commands must print an executable path. If either check fails, stop and arrange for the prerequisite to be provided outside this lab.
2
Create the isolated workspace
sudo install -d -m 0755 -o "$(id -un)" -g "$(id -gn)" /opt/lab-classroom/class65
This creates only the approved class directory and assigns it to the current user so the service can write its local log and process identifier.
3
Check that the selected loopback port is unused
if command -v ss >/dev/null 2>&1; then ss -lntu | grep -E '127.0.0.1:1053([[:space:]]|$)' || true; else echo "ss is unavailable; dnsmasq startup will perform the effective port check"; fi
No matching listener should be displayed. If a listener is shown, do not start the lab service until the conflict has been investigated.
4
Write the local DNS configuration
printf '%s\n' 'port=1053' 'listen-address=127.0.0.1' 'bind-interfaces' 'no-resolv' 'no-hosts' 'domain-needed' 'bogus-priv' 'local=/home.arpa/' 'host-record=dashboard.home.arpa,10.20.30.40' 'host-record=nas.home.arpa,10.20.30.50' 'cache-size=100' 'log-queries' 'log-facility=/opt/lab-classroom/class65/dnsmasq.log' 'pid-file=/opt/lab-classroom/class65/dnsmasq.pid' > /opt/lab-classroom/class65/dnsmasq.conf
cat /opt/lab-classroom/class65/dnsmasq.conf
The configuration provides two private A records, declares home.arpa local, disables inherited host and upstream resolver data, and keeps runtime files inside the workspace.
5
Validate the configuration before starting
dnsmasq --test --conf-file=/opt/lab-classroom/class65/dnsmasq.conf
Proceed only when dnsmasq reports that the syntax check is successful.
6
Start the isolated DNS process
dnsmasq --no-daemon --conf-file=/opt/lab-classroom/class65/dnsmasq.conf >> /opt/lab-classroom/class65/service-output.log 2>&1 & printf '%s\n' "$!" > /opt/lab-classroom/class65/launcher.pid
sleep 1
test -s /opt/lab-classroom/class65/launcher.pid && kill -0 "$(cat /opt/lab-classroom/class65/launcher.pid)"
cat /opt/lab-classroom/class65/service-output.log
The process runs in the background but remains bound to the loopback address and selected lab port. The process check succeeds silently when it is alive.
7
Resolve the dashboard name
dig @127.0.0.1 -p 1053 dashboard.home.arpa A +noall +answer
The answer section should associate dashboard.home.arpa with 10.20.30.40.
8
Resolve the NAS name and inspect the full response
dig @127.0.0.1 -p 1053 nas.home.arpa A
Inspect the header status, question section, answer section, responding server, and query time. The status should be NOERROR.
9
Test a missing local name
dig @127.0.0.1 -p 1053 missing.home.arpa A
The response should report NXDOMAIN because the requested name is not among the local records.
10
Test a record-type mismatch
dig @127.0.0.1 -p 1053 dashboard.home.arpa AAAA
The lab defines an A record but no AAAA record. A successful server response can therefore contain no IPv6 answer; reachability of the DNS server and existence of a requested record type are separate questions.
11
Review query evidence
cat /opt/lab-classroom/class65/dnsmasq.log
The log should show the names and record types queried during the exercise.
| Symptom | Likely cause | Fix |
|---|---|---|
| dnsmasq is not found. | The prerequisite package is not installed or its executable directory is absent from PATH. | Stop the lab and arrange for dnsmasq to be installed through the normal host-management process. Do not improvise package or system changes inside this exercise. |
| dig is not found. | The system's DNS client utilities are not installed. | Stop the lab and obtain the appropriate DNS utility package through the normal host-management process before continuing. |
| The configuration test reports an error. | A directive was copied incorrectly or the installed dnsmasq release does not support the supplied syntax. | Compare /opt/lab-classroom/class65/dnsmasq.conf with the lesson, inspect the exact error line, and consult the manual for the installed release before changing anything. |
| dnsmasq reports that the address is already in use. | Another process is listening on 127.0.0.1:1053. | Do not stop an unidentified service. Inspect the existing listener, terminate only a previous instance of this class if ownership is confirmed, or select another unprivileged port consistently in both the configuration and every dig command. |
| dig times out. | The lab process exited, failed to bind, or is being queried on the wrong address or port. | Check service-output.log, confirm the recorded process with kill -0, and verify that the query explicitly uses @127.0.0.1 and -p 1053. |
| The expected A record is missing. | The queried spelling or record type does not match the configured host-record. | Use the complete name, verify that the query type is A, inspect the configuration, and rerun the syntax test before restarting the lab service. |
| A normal application cannot resolve dashboard.home.arpa even though the direct dig query works. | The lab intentionally does not configure the operating system to use 127.0.0.1:1053 as its resolver. | Use explicit dig queries for this exercise. Production resolver distribution is a separate administrative change and is intentionally outside the lab scope. |
| A changed record still appears to return an old address in another environment. | A resolver or application retained a cached answer until its TTL expired. | Query the intended resolver directly, inspect the remaining TTL, wait for expiration where practical, and confirm that all clients are using the expected resolver. |
| The query returns NOERROR but the answer section is empty. | The name can be recognized while the requested record type is not defined, such as requesting AAAA when only an A record exists. | Request the correct record type or deliberately define the missing record after confirming that the corresponding address is valid. |
Bind experimental DNS services to 127.0.0.1 unless LAN access is an explicit design requirement.
Do not expose an unrestricted resolver to untrusted networks; open recursive resolvers can be abused and can contribute to amplification traffic.
Restrict configuration-file write access because anyone able to alter DNS records can redirect clients to unintended systems.
Use names from home.arpa for a residential private namespace, or use a properly controlled subdomain when operating a registered domain.
Avoid placing credentials, tokens, owner names, or other sensitive information in host names because DNS names commonly appear in logs.
DNS resolution does not authenticate an application. Use appropriate transport encryption and certificate validation for sensitive services.
Account for clients that use encrypted external resolvers or manually configured resolvers, because they may bypass local DNS policy.
Back up DNS configuration and document address ownership so stale records do not redirect users after an address is reassigned.
Where supported by the production design, operate more than one resolver so a single maintenance event does not remove naming from the entire LAN.
Stop only the process launched by this lab and remove only the class workspace.
Read the process identifier from /opt/lab-classroom/class65/launcher.pid.
Confirm that the identifier still belongs to a dnsmasq command using the class65 configuration.
Stop that verified process.
Delete the contents of /opt/lab-classroom/class65/ and then remove the empty class65 directory.
pid="$(cat /opt/lab-classroom/class65/launcher.pid 2>/dev/null || true)"; if [ -n "$pid" ] && kill -0 "$pid" 2>/dev/null; then args="$(ps -p "$pid" -o args=)"; case "$args" in dnsmasq'/opt/lab-classroom/class65/dnsmasq.conf') kill "$pid"; wait "$pid" 2>/dev/null || true ;; ) printf '%s\n' "Refusing to stop PID $pid because its command does not match this lab." >&2; exit 1 ;; esac; fi
find /opt/lab-classroom/class65 -mindepth 1 -maxdepth 1 -type f -delete
rmdir /opt/lab-classroom/class65
Confirm that /opt/lab-classroom/class65 no longer exists and that dig @127.0.0.1 -p 1053 dashboard.home.arpa A now times out or reports that no server is reachable on that port. The host's ordinary resolver settings should be exactly as they were before the lab.
Welcome to Class 65, Local DNS and Friendly Service Names. In this lesson, we replace difficult-to-remember private addresses with names such as dashboard.home.arpa. We begin by separating DNS from the applications it supports. DNS can tell a client that a name maps to an address, but it cannot guarantee that the service at that address is running, secure, or correctly configured.
The client normally uses a stub resolver, which forwards questions to a configured DNS resolver. That resolver may answer from its cache, consult another server, or use locally maintained data. The time-to-live attached to an answer controls how long it may normally remain cached. This is why a record change can be correct on the server while some clients continue to see an older address.
For a residential network, home.arpa is the standards-based private namespace. Avoid inventing a top-level suffix, and avoid using the local suffix for ordinary unicast DNS because many systems associate it with multicast DNS. A clear naming plan should identify services rather than temporary hardware details. A stable name such as nas.home.arpa can remain useful even when the underlying address changes.
Our lab is intentionally isolated. dnsmasq listens only on the loopback address and uses port 1053. We do not replace the operating system resolver, advertise the service to the LAN, or read the host's normal resolver and hosts data. Two host records are defined: dashboard.home.arpa maps to 10.20.30.40, and nas.home.arpa maps to 10.20.30.50.
After validating the configuration, we start the process and use dig to choose both the server and port explicitly. The dashboard and NAS A queries should return their configured IPv4 addresses. A query for missing.home.arpa should return NXDOMAIN. We also ask for an AAAA record that was never defined. That test demonstrates that a reachable DNS server can return no answer for a specific record type without inventing data.
Finally, we inspect the query log and perform a controlled rollback. In production, local DNS requires stable resolver addresses, configuration backups, access controls, monitoring, and a client-distribution plan. It may also need redundancy and deliberate IPv6 support. Remember the central lesson: DNS gives services durable, understandable identities, but it is only one layer of a reliable and secure homelab.
Return to this class whenever a later service fails for identity, process, log, remote access, update, or routing reasons covered here.