Course outline · 0% complete

0/25 lessons0%

Course overview →

The connectivity checklist

lesson 9-1 · ~12 min · 24/25

The whole course in one ordering: DNS lookup, TCP handshake, TLS handshake, HTTP request.

That is B, D, A, C against the list above.

Name to address is DNS from unit 2, then connect is TCP from unit 3, then encrypt is TLS from unit 7, then ask is HTTP from units 4 and 5.

This order is also your debugging checklist, because each step can only fail if every step before it succeeded. That property is what makes bottom-up testing worth the discipline: the first failure you find is the real one, and everything above it is a consequence rather than a cause.

"It does not connect"

Every connectivity problem, from "the site is down" to "my API call hangs", yields to the same method: test each layer in the order it happens, bottom up. The first layer that fails is your culprit, and everything after it is noise.

StepQuestionToolFailure looks like
1. DNSDoes the name resolve?dig +short hostno output, or curl: (6) Could not resolve host
2. ReachabilityDoes the machine answer at all?ping host100% packet loss
3. TCPIs the port open?curl -v, or nc -z host portConnection refused or a hang then timeout
4. TLSDoes the handshake complete?curl -vI https://hostcertificate has expired, (60) SSL...
5. HTTPWhat status code?curl -s -o /dev/null -w '%{http_code}\n'4xx (your request) or 5xx (their server)

Two refinements from experience. Connection refused is actually a fast, useful failure: the machine is up and actively said "nothing listens on that port", so check the port number and whether the service is running. A silent timeout instead suggests a firewall is eating your packets. And if DNS fails, test a known-good name like example.com next, to learn whether it is that one domain or your whole resolver.

5HTTPwhat status code came back?4TLSdoes the handshake complete?3TCPis the port open?2reachdoes the machine answer at all?1DNSdoes the name resolve?testfirst
The checklist as a ladder. Each rung can only be tested once the one below it passes, so the lowest failure is the real one.

A recorded session

A real debugging session. A teammate reports "api.shop.test is down!", and the checklist below finds the true failing layer.

Each step below shows the command and the output it printed.

Step 1. Step 1, DNS. It resolves fine, so the name is not the problem.

$ dig +short api.shop.test
203.0.113.40

Step 2. Step 2, reachability. The machine answers pings, it is alive.

$ ping -c 2 203.0.113.40
64 bytes from 203.0.113.40: icmp_seq=0 ttl=54 time=23.1 ms
64 bytes from 203.0.113.40: icmp_seq=1 ttl=54 time=22.8 ms

2 packets transmitted, 2 packets received, 0.0% packet loss

Step 3. Steps 3 and 4, TCP and TLS, in one shot with curl -v. Connection and handshake both succeed, and we even get an HTTP response... but look at the status.

$ curl -sv https://api.shop.test/health -o /dev/null 2>&1 | grep -E 'Connected|SSL connection|HTTP'
* Connected to api.shop.test (203.0.113.40) port 443
* SSL connection using TLSv1.3
< HTTP/1.1 503 Service Unavailable

Step 4. Diagnosis: layers 1 through 4 are healthy, the failure is layer 5, and 503 is a 5xx, so it is server-side (lesson 4-3). "Down" actually means the app behind the port is failing. The fix is in the server's logs, not in your network. Report exactly that.

$ curl -s -o /dev/null -w '%{http_code}\n' https://api.shop.test/health
503

Reading a hang that ends in a timeout

The most likely culprit is that a firewall is silently dropping packets to that port, or nothing answers on it.

DNS works, since dig answered, and the machine is reachable, since ping works, so the failure is at the TCP step. Two layers of the checklist are already cleared.

A silent hang, rather than an instant Connection refused, is the signature of a firewall dropping packets without replying. The client keeps waiting for a SYN-ACK from lesson 3-2 that is never coming, and gives up when its timer expires.

The rule worth memorizing: refused means the machine said no, and timeout means something ate the packets. One points at the service configuration and the other at the network path, which are different teams and different fixes.

Worth checking whether the same port works from another network. A timeout that disappears on a different path confirms the firewall theory without needing any access to the firewall.