Network¶

Recipes for inspecting local network state, testing connectivity, and troubleshooting DNS.

Quick Start¶

Run just net check-all first. It tests four things in sequence — local IPs, listening ports, external ping, and DNS resolution — and prints OK/FAIL for each. The first failure tells you which layer is broken; the sections below explain what to do next.

Troubleshooting Layers¶

Network problems always live at a specific layer. Work top-to-bottom — there's no point debugging DNS if you don't have an IP address yet.

Router¶

router <port> <user> opens an SSH session to the local router (192.168.1.1) with a non-standard port and user. Both arguments are required — there are no defaults, since router configs vary.

Inspecting Local State¶

IPs¶

ips lists every network interface and its IP address. You're looking for your primary interface (typically eth0, enp*, or wlan0 on Linux; en0 on macOS) to have a valid IP — something like 192.168.x.x or 10.x.x.x for a home/office network. If it shows no IP or only 127.0.0.1, your machine isn't connected to the network.

Ports¶

ports shows which services are listening for connections on your machine. Each line shows a port number and (on Linux) the process name. Common things you'd expect to see: port 22 (SSH), 5432 (Postgres), 8080 (dev server), etc. If a service you started isn't listed here, it either crashed or is binding to a different port than you expect.

On Linux the output includes process names; on macOS it does not. If you need to find what owns a specific port on macOS, run lsof -i :<port> directly.

Stats¶

stats shows per-interface packet counters including errors and drops. On a healthy connection these should all be zero. Non-zero errors can indicate cable issues, driver problems, or hardware faults. Non-zero drops usually mean the system is under too much network load.

Testing Connectivity¶

Ping¶

ping sends 5 ICMP packets to a host (default 8.8.8.8). Look at three things in the output:

• Packet loss: 0% is good. Any loss means something is dropping traffic between you and the target — could be your WiFi, your ISP, or anything in between.
• Latency (time=): Under 50ms to 8.8.8.8 is typical. Over 200ms suggests congestion or a routing problem.
• Jitter: If the latency numbers vary wildly (e.g. 20ms, 300ms, 50ms), the connection is unstable — common on overloaded WiFi.

Check-port and Test-remote¶

check-port tests a port on your own machine (localhost). test-remote tests a port on another machine. Both use a 3-second timeout. The output tells you one of three things:

• "Connection succeeded" — the port is open and accepting connections.
• "Connection refused" — the port is definitively closed. Nothing is listening there. Check that the service is running and bound to the right port.
• Timeout (no response) — the port might be firewalled. A firewall silently drops the connection attempt rather than refusing it. Check firewall rules (iptables, ufw, security groups, etc.).

Trace¶

trace shows every network hop between you and a destination. Each line is a router your traffic passes through, with its latency. Useful for answering "where is the slowdown?" or "where does traffic stop?".

Reading the output:

• Hops with low, consistent latency — healthy, nothing to worry about.
• A sudden latency jump (e.g. 10ms to 150ms) — the link between those two hops is slow or congested. If it's early (hops 1-3), it's likely your ISP.
• * * * for a hop — that router doesn't respond to probes. This is normal and doesn't mean traffic is being dropped. Many ISP routers are configured this way. Only worry if all remaining hops after it are also * * *.
• Trace never completes — traffic is being blocked somewhere. The last responding hop is the clue.

DNS¶

dns runs a detailed lookup showing the full answer: IP addresses, TTL (how long the result is cached), which DNS server answered, and how long the query took. If you just need to know "does it resolve?", check-all covers that.

A healthy lookup shows status: NOERROR and one or more IP addresses in the ANSWER SECTION. Common problems:

• NXDOMAIN — the domain doesn't exist. Check for typos.
• SERVFAIL — your DNS server couldn't resolve it. The server itself might be down or misconfigured. Try just net dns <host> after switching to a public DNS (8.8.8.8 or 1.1.1.1) to confirm.
• Very high query time (>500ms) — your DNS server is slow. Consider switching to a faster one.

flush-dns clears the system DNS cache. Requires sudo and prompts for confirmation. Reach for this when:

• You just changed DNS servers and old results are sticking around.
• You edited /etc/hosts but changes aren't taking effect.
• A domain recently changed its IP and you're still hitting the old one.

Common Scenarios¶

"Nothing works" — Run check-all. If ips fails, you have no network connection at all (check cables, WiFi, VPN). If ping fails but ips is fine, check your default gateway/router.

"I can ping IPs but not domain names" — DNS is broken. Run just net dns google.com to confirm. If it fails, your DNS server is down or unreachable. Temporarily switch to 8.8.8.8 or 1.1.1.1 to get back online.

"My local dev server isn't reachable" — Run just net ports and check if your expected port is listed. If not, the server isn't running or is bound to a different port/interface. If it is listed, try just net check-port <port> to verify it's accepting connections.

"I can't reach an external API" — Run just net test-remote api.example.com 443. Connection refused means the remote service is down. Timeout means a firewall is blocking you — check VPN, corporate proxy, or cloud security groups.

"Everything is slow" — Run just net ping to check for packet loss and high latency. If those look fine, run just net trace <slow-host> to find where the slowdown is. Also check just net stats for interface errors.

Examples¶

just net check-all          # quick baseline — start here
just net ips                # what IPs do I have?
just net ports              # what's listening on my machine?
just net ping               # internet connectivity (default: 8.8.8.8)
just net ping 1.1.1.1       # ping a specific host
just net dns example.com    # full DNS lookup
just net test-remote api.example.com 8080  # can I reach this service?
just net check-port 3000    # is my dev server listening?
just net trace 10.0.0.5     # where does traffic go?
just net flush-dns          # clear DNS cache (requires sudo)

Why 8.8.8.8? It's Google's public DNS resolver — one of the most reliably available IPs on the internet. It always responds to ping, is easy to remember, and a failure to reach it strongly indicates a problem on your side. 1.1.1.1 (Cloudflare) is the other common choice.