Fast troubleshooting flow

1 — Check the local interface and IP address

Linux:

ip addr
ip link

2: eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> ...
    inet 10.20.1.15/24 brd 10.20.1.255 scope global eth0

What to check: find the interface you expect to carry the traffic. Verify it is UP and has the expected IP/prefix. An interface can be UP while having the wrong or missing address.

macOS workstation alternative:

ifconfig

Look for an active interface such as en0 and its inet address. If the address is unexpected, fix the local network/VPN configuration before moving up the stack.

2 — Check which route will be used

Linux:

ip route
ip route get <destination-ip>

10.20.2.25 via 10.20.1.1 dev eth0 src 10.20.1.15

What to check: via is the selected gateway, dev is the outgoing interface and src is the source address Linux plans to use. An unexpected gateway, interface or source address points toward routing, VPN or interface configuration.

macOS workstation alternative:

route -n get <destination-ip>

   gateway: 192.168.1.1
 interface: en0

Check that the gateway and interface match the path you expected.

3 — Use ping as a reachability clue

ping -c 4 <destination-ip>

4 packets transmitted, 4 received, 0% packet loss
round-trip min/avg/max = 11.8/13.2/15.0 ms

What to check: packet loss and latency. Replies prove ICMP can travel to the destination and back. No reply does not prove the host is down because ICMP may be filtered. Continue with the actual application port.

macOS note: ping -c 4 also works on macOS.

4 — Check DNS and read the answer

dig example.com

;; ->>HEADER<<- opcode: QUERY, status: NOERROR
;; ANSWER SECTION:
example.com.  300  IN  A  203.0.113.10
;; Query time: 18 msec
;; SERVER: 10.0.0.2#53(10.0.0.2)

Check four things: status, the ANSWER, the resolver shown by SERVER, and query time. NOERROR means the query was processed successfully; verify the returned IP is actually expected.

If appropriate for the name, compare another resolver:

dig @<dns-server-ip> example.com

If the configured resolver fails but a known appropriate resolver succeeds, investigate the configured resolver or path to it. Private/internal names may only exist on your organization's DNS.

5 — Test the actual TCP port

nc -vz example.com 443

Success:

Connection to example.com port 443 [tcp/https] succeeded!

TCP connectivity to that endpoint works. It does not prove TLS, HTTP or the application is healthy. For HTTPS, continue with curl -v.

Connection refused:

nc: connect to example.com port 443 (tcp) failed: Connection refused

The destination/path was reachable enough for the connection to be actively rejected. If you own the destination, check whether a process is listening on the expected port and address.

Timeout:

nc: connect to example.com port 443 (tcp) timed out

Routing, firewall/security policy, packet loss or an unresponsive path becomes more interesting. Check the route and, if necessary, the path/capture steps below.

6 — For HTTP/HTTPS, use curl to identify the failing layer

curl -v https://example.com/

* Host example.com:443 was resolved.
*   Trying 203.0.113.10:443...
* Connected to example.com (203.0.113.10) port 443
* SSL connection using TLS...
< HTTP/1.1 200 OK

Read verbose output as a progression: DNS → TCP → TLS → HTTP. The last successful stage tells you where to investigate next.

7 — If you own the server, check the listener

Linux:

ss -lntp

LISTEN 0 128 127.0.0.1:8080 0.0.0.0:* users:(("myapp",pid=1234,fd=8))

What to check: expected port, process and bind address. 127.0.0.1:8080 generally accepts only local IPv4 connections. If the service must be reachable through the host's network interfaces, compare with a listener bound to an appropriate interface or 0.0.0.0:8080. Do not change the bind address until you understand the intended exposure/security model.

macOS workstation alternative:

lsof -nP -iTCP -sTCP:LISTEN

COMMAND  PID USER  FD  TYPE ... NAME
myapp   1234 user  12u IPv4 ... TCP 127.0.0.1:8080 (LISTEN)

Interpret the listening address the same way: localhost-only versus an address intended for remote access.

8 — Trace the path when the evidence points between hosts

traceroute example.com

1  192.168.1.1   2.1 ms  1.8 ms  1.9 ms
2  10.10.0.1     8.4 ms  8.2 ms  8.5 ms
3  * * *
4  203.0.113.10  21.0 ms 20.7 ms 21.2 ms

What to check: where responses stop consistently or latency changes sharply. Do not treat one * * * as proof that hop is broken. Routers/firewalls may suppress traceroute responses while still forwarding traffic; the responding fourth hop above proves packets continued beyond hop 3.

9 — Packet capture for ambiguous failures

On Linux, -i any tells tcpdump to capture across available interfaces instead of choosing one interface yourself. any is an interface selection supported by tcpdump/libpcap on Linux—it is not a separate tool.

sudo tcpdump -i any host <destination-ip> and port <port>

If you already know the outgoing interface, a focused capture is easier to read:

ip route get <destination-ip>
sudo tcpdump -i eth0 host <destination-ip> and port <port>

Example: TCP handshake succeeds

client.52144 > server.443: Flags [S]
server.443 > client.52144: Flags [S.]
client.52144 > server.443: Flags [.]

[S] is SYN, [S.] is SYN-ACK and [.] is the ACK. Together they show the TCP three-way handshake completed.

Example: repeated SYN with no reply

client.52144 > server.443: Flags [S]
client.52144 > server.443: Flags [S]
client.52144 > server.443: Flags [S]

The client is sending connection attempts but this capture sees no SYN-ACK or reset returning. That narrows the investigation, but a capture on only one side does not tell you exactly where the packet was lost.

macOS workstation: choose the relevant interface rather than using Linux's any selection:

route -n get <destination-ip>
sudo tcpdump -i en0 host <destination-ip> and port <port>

What should I run first?

Related Runbookery resources

Use the CIDR Calculator for address ranges. For Kubernetes traffic continue with Kubernetes Service Unreachable.