Network Troubleshooting

Volume 2 — Networking Foundations

This chapter ties together TCP/IP, DNS, and SSL/TLS into one methodology: when something's broken, work through the layers in order rather than guessing. Each layer has one or two tools that answer "is this layer the problem?" definitively before you move to the next.

1. The Methodology

The discipline that matters here: answer each question with a specific command before moving to the next one. It's tempting to jump straight to "is the API broken" when the real issue is DNS — working top-down through this chain rules layers out definitively instead of guessing.

2. The Core Toolkit

Tool	Answers
ping	Is the host reachable at all, at a basic ICMP level?
traceroute	Where along the path does connectivity break down or slow down?
dig / nslookup	Does the hostname resolve, and to what?
nc -zv	Is a specific port open and accepting connections?
curl -v	What's actually happening at the HTTP/HTTPS layer — status code, headers, redirects, TLS?
openssl s_client	Is the TLS handshake succeeding, and what certificate is being presented?
netstat / lsof -i	What's listening or connected on this machine right now?

ping

ping api.roundtrips.app

Confirms basic reachability. Caveat: many servers and firewalls (including much of Azure's edge infrastructure) deliberately block ICMP — a failed ping does not necessarily mean the host is down or unreachable for actual application traffic. Don't over-index on this tool alone; treat it as one signal, not a verdict.

traceroute

traceroute api.roundtrips.app

Shows each hop the packet passes through. Useful for spotting where a connection is failing or slowing down — a clean path that suddenly stops responding at a specific hop points at that hop (or the one just after it) as the problem.

dig / nslookup

dig api.roundtrips.app A
dig @1.1.1.1 api.roundtrips.app A     # bypass local cache, ask a specific resolver directly

Covered in depth in the DNS Deep Dive chapter — the first thing to check whenever "can't reach X by name" is the symptom, since it rules an entire category of causes in or out immediately.

nc (netcat) — port reachability

nc -zv api.roundtrips.app 443

-z scans without sending data, -v is verbose. This answers "is anything even listening here" independent of what protocol is supposed to be running on that port — the cleanest way to separate "network/firewall problem" from "the application itself is broken."

curl -v — the HTTP layer

curl -v https://api.roundtrips.app/health

Shows the full request/response cycle: DNS resolution, TCP connection, TLS handshake, request headers sent, response headers and status code received. This single command usually tells you which of the four methodology layers actually failed, since curl reports distinctly different errors for a DNS failure vs. a connection refusal vs. a TLS failure vs. an HTTP-level error.

openssl s_client — TLS layer

openssl s_client -connect api.roundtrips.app:443 -servername api.roundtrips.app

Covered in depth in the SSL/TLS Explained chapter — isolates whether a failure is specifically in certificate validation, independent of whether the underlying TCP connection and the application's HTTP response are fine.

netstat / lsof — what's happening locally

netstat -an | grep LISTEN     # what's listening on this machine (Linux)
lsof -i :5000                  # what's using a specific port (macOS)

The right tool when the question is about your own machine — is something already bound to the port you're trying to use locally, is your local API actually running and listening where you expect.

3. Scenario Walkthroughs

"The site is down"

dig roundtrips.app A                                   # does it resolve?
nc -zv roundtrips.app 443                               # is the port open?
curl -v https://roundtrips.app                          # what does the full request actually return?

A dig failure means DNS; a nc failure with successful dig means a firewall/NSG or the service itself is down; a curl failure with both prior steps succeeding means either a TLS problem (check the curl -v output for handshake details) or an application-layer error (check the actual HTTP status code returned).

"API works in Postman/browser but fails from the Azure App Service backend"

This is almost always a difference in which network the request originates from, not a difference in the API itself.

# From the App Service's own console/SSH (Azure Portal → App Service → SSH):
curl -v https://the-target-service/health
nc -zv the-target-service 443

Compare directly against the same commands run from your laptop. A difference here points at a firewall/NSG rule that allows your IP but not the App Service's outbound IP — see the TCP/IP Fundamentals chapter's note on outbound IPs changing after scale events.

"Database connection times out from Azure, works fine locally"

nc -zv db-hostname 1433

If this hangs rather than failing immediately, it's very likely an NSG or Azure SQL firewall rule silently dropping the connection rather than actively rejecting it (see the TCP three-way handshake note in TCP/IP Fundamentals) — check the database's allowed-IP list against the App Service's actual current outbound IPs, not an assumption of what they still are.

"Intermittent failures, can't reproduce reliably"

for i in {1..10}; do curl -o /dev/null -s -w "%{http_code} %{time_total}s\n" https://api.roundtrips.app/health; sleep 1; done

Running the same request repeatedly and logging status code and timing surfaces patterns (a specific backend instance behind a load balancer misbehaving, a periodic timeout every N requests) that a single manual test can miss entirely.

4. Troubleshooting Playbook

Symptom	Where to start	Command
"Can't reach it at all"	DNS	dig hostname A
Hostname resolves, connection still fails	Port/firewall	nc -zv hostname port
Port is open, HTTPS still fails	TLS	openssl s_client -connect hostname:443
TLS succeeds, wrong/unexpected response	Application layer	curl -v and inspect the actual response body/headers
Works locally, fails from Azure	Different source IP/network context	Compare curl -v/nc output run from the Azure resource itself, not just locally
Slow but not failing	Path/latency	traceroute, and repeated curl -w "%{time_total}" timing
Works sometimes, not others	Load balancer inconsistency, or intermittent network issue	Repeated automated requests (see Section 3) to surface a pattern

5. Quick Reference

Layer	Tool	Command
DNS	dig	dig hostname A
DNS (bypass cache)	dig	dig @1.1.1.1 hostname A
Reachability	ping	ping hostname (unreliable if ICMP is blocked)
Path	traceroute	traceroute hostname
Port	nc	nc -zv hostname port
TLS	openssl	openssl s_client -connect hostname:443 -servername hostname
HTTP	curl	curl -v https://hostname/path
Local	lsof	lsof -i :port
Local	netstat	netstat -an | grep LISTEN

---

Part of the Traxs Engineering Handbook — Volume 2: Networking Foundations. Companion chapters in this volume: TCP/IP Fundamentals, DNS Deep Dive, SSL/TLS Explained, VPN Fundamentals, Load Balancers & Reverse Proxies.