Lesson 6 of 10Diagnostics

12 min · theory and practice · Basics

DNS: why a name will not resolve

Separate a DNS failure from an unavailable application.

You will be able to compare a DNS-server response with system name resolution.

Before connecting by name, a client usually needs an IP address. If that step fails, the application itself may still be healthy. Check the name, record type and DNS server being queried.

Inspect the system view

getent hosts uses the system name-resolution mechanisms, including /etc/hosts and NSS settings. dig sends a DNS query. Their answers can differ because they exercise different paths.

Commands
getent hosts api.example.test
cat /etc/resolv.conf
dig api.example.test A

example.test is a placeholder. When troubleshooting, use the name from the application error.

Read the response status

NXDOMAIN reports a non-existent queried name. SERVFAIL reports a failure while processing the query. A timeout is different: no response arrived in time. Inspect the full output rather than only +short.

Commands
dig @10.0.0.53 api.example.test A +time=2 +tries=1
Example output
;; ->>HEADER<<- opcode: QUERY, status: SERVFAIL, id: 4102

An explicit @server tests the intended resolver. Replace 10.0.0.53 with your training DNS address.

Compare resolution and connectivity

If a trusted source provides the IP, curl --resolve tests that server while retaining the original URL hostname. This temporarily bypasses DNS for diagnosis; it does not repair resolver settings. HTTPS keeps the hostname for TLS.

Commands
curl -sS -i --max-time 5 --resolve api.example.test:80:10.0.0.20 http://api.example.test/health

If this works, return to DNS and inspect configuration, resolver reachability and records. After the fix, repeat the request without --resolve.

Inspect the path to the resolver

The payment case’s DNS move and network hardening suggest different hypotheses. If the intended resolver never answers, inspect addresses, routes and access rules rather than substituting a hosts entry. ICMP may work while DNS traffic is blocked.

DNS uses both UDP and TCP. Comparing ordinary dig with dig +tcp can narrow the failing boundary. Different results do not justify removing the whole firewall; identify the specific resolver rule and direction.

Commands
ip route
dig @10.0.0.53 gateway.pay.internal A +time=2 +tries=1
dig @10.0.0.53 gateway.pay.internal A +tcp +time=2 +tries=1

Replace the example resolver address with the one in your environment, then verify the normal named payment request.

From symptom to check

ObservationNext checkHow to interpret it
NXDOMAINFull name and selected DNS serverThe response describes the name in this DNS context; inspect the query and zone.
UDP dig times out; +tcp answersUDP reachability to the resolverSeparate transport filtering from the DNS answer itself.
dig answers, getent cannot resolveNSS, hosts and the system resolverThe application’s system path differs from a direct DNS query.

Common mistakes

  • Treating a successful ping as a DNS transport test.
  • Removing all firewall rules instead of isolating the relevant one.
  • Keeping a hosts workaround instead of repairing resolution.

How to prove recovery

  1. Check getent for the name payments uses.
  2. Check the configured DNS path without a diagnostic bypass.
  3. Call the normal named payment business route.
  4. Preserve required network policy while fixing the specific failure.

MINI INCIDENT

The gateway is alive, but payments fail

HTTP works to a known IP, getent cannot resolve the name, and UDP dig to corporate DNS hangs. dig +tcp answers. Where should you investigate, and why not edit the application first?

Evidence to investigate
HTTP to known IP: 200
DNS UDP: timeout
DNS TCP: answer received
Explore the diagnosis

Compare the UDP path and resolver rules, then repeat system resolution. The observations isolate a DNS transport difference without identifying a specific rule. The application may simply be receiving a resolution failure.

WORKSHOP

Workshop: explain the evidence and choose an action

The same name was tested using system lookup, DNS and a direct bypass. Explain what each observation covers.

Sample evidence
getent api.example.test → 10.0.0.19
dig api.example.test A   → 10.0.0.20
--resolve ...:10.0.0.20  → application 200
  1. Which hypothesis explains the different addresses?

    Compare your reasoning

    System lookup can use /etc/hosts and other sources besides DNS. Compare lookup order and configuration rather than declaring DNS broken from getent alone.

  2. What does the --resolve bypass establish?

    Compare your reasoning

    The application is reachable at that address while preserving the request name. This narrows the investigation but does not repair ordinary client name resolution.

  3. How can verification finish without a permanent bypass?

    Compare your reasoning

    Repair the verified source of disagreement, then repeat getent and a normal named request from the original context. A diagnostic address must not remain the only working access path.

CHECK YOUR UNDERSTANDING

dig +short printed nothing. Does that prove the name does not exist?

Show explanation

No. Short output hides the status. Inspect the full response: NXDOMAIN, SERVFAIL, a missing record type and a timeout require different actions.

Documentation

Guest progress is stored separately in this browser.

TAKE IT TO THE TERMINAL

Practice on an incident

Restore name resolution in a case where an application depends on another service.

DID IT MAKE SENSE?

Was this article helpful?

Rate the article or tell us what needed more explanation. Your feedback helps improve the lessons.

Helpful 0 Not helpful 0

Sign in to rate this article and leave a comment.

Discussion

0

Join the discussion →

No comments yet. Share your first impression or ask a question about this topic.