Network diagnosis

The browser journey gave the whole path. Diagnosis now means choosing an observation that distinguishes two explanations, rather than changing several things and hoping the symptom disappears.

Begin where the failure happens

Write down the exact URL, client environment, time, and error. A request working from macOS does not prove it works from a Linux machine, container, or CI runner. Their routes, resolver configuration, proxy settings, and meaning of loopback can differ.

Use this decision table to choose the next question. The rows are related tests, not a guarantee that every incident follows one fixed order.

Do not start by disabling all firewall rules. A refusal can result from no listener or an active rejection; a timeout means no timely response, which has several possible causes. Neither message alone locates the faulty device.

Work a concrete example

Suppose the server-side listing contains 127.0.0.1:8765, but a client is trying the machine's external IP on port 8765. The hypothesis is “the process only listens on loopback.” Inspecting the local address in ss -lnt directly tests it. A successful request to loopback from the same machine supports that explanation; it does not justify widening the listener before deciding who should be able to reach it.

Now suppose loopback / returns the known page, while /missing returns 404. The listener and HTTP exchange worked in both cases; the requested resource differs. Restarting DNS would not create a missing file. After stopping the fixture, the same / URL should fail to connect. Those observations distinguish an application response from a transport failure.

Use the complete local server lab next to produce these three cases. It supplies every file and command, uses loopback, and needs no DNS or TLS. Record both curl's exit status and HTTP status rather than calling them both “the code.”

Keep each probe small and interpretable

For a known endpoint you control, preserve stderr and use a timeout. For example, after starting the lab fixture:

curl --connect-timeout 2 --max-time 3 -i http://127.0.0.1:8765/
printf 'curl exit status: %s\n' "$?"

-i includes response headers. A received HTTP error may still produce curl status 0 unless failure-on-HTTP-error behavior is requested. An HTTP code of 000 in formatted curl output means no HTTP response code was obtained, not an actual server status.

If DNS is suspected for an HTTPS service you administer, curl's --resolve HOST:PORT:IP can target a known IP while retaining the requested hostname for HTTP and TLS. It is a temporary diagnostic override, not a replacement for fixing DNS. Never insert a guessed backend IP or disable TLS validation to make that test pass.

Know when a deeper tool adds evidence

Traceroute/mtr probe hop responses, which can be filtered or rate-limited; one silent hop is not proof of data loss there. Packet capture may be useful for unresolved handshake or MTU questions, but use a narrow address/port filter and finite capture size in an environment you administer. Captures can include sensitive traffic, and you do not need one for this lab.

An escalation note should state the failing operation, exact contexts, recent relevant change, actual successful/failed checks, and the next hypothesis. “DNS returned an address, therefore the network works” skips several checks. A better conclusion is: “Resolution succeeded here; connection to this address and port still times out.” That leaves the uncertainty visible and the next test clear.

Sources

Primary references: curl network troubleshooting↗; Linux ss↗.