DNS & Networking

intent

debug DNS resolution, network connectivity, and HTTP issues when DNS names won't resolve, ports are unreachable, firewall rules are unclear, HTTP requests fail silently, or certificates are invalid. covers dig, nslookup, port testing with netcat, curl diagnostics, /etc/hosts configuration, proxy setup, and TLS troubleshooting. use this when you need to isolate whether a problem is DNS, network routing, firewall rules, or the application itself.

inputs

required binaries (at least one from each group):

• DNS query tools: dig, nslookup, or host
• port testing: nc (netcat) or bash's /dev/tcp (built-in)
• HTTP diagnostics: curl
• system info: ping, ip/ifconfig, ss/netstat/lsof, traceroute/mtr
• certificate inspection: openssl

system access:

• read access to /etc/resolv.conf, /etc/hosts
• root/sudo access to flush DNS caches, configure firewall rules, check listening ports with ss -tlnp
• network connectivity to target hosts (some tests may be blocked by firewall or egress rules)

environment (optional but recommended):

• HTTP_PROXY, HTTPS_PROXY, NO_PROXY env vars if behind corporate proxy
• CURL_CA_BUNDLE if using custom CA certificate bundle

external connections:

• target hostname or IP address
• optional: specific DNS server (defaults to system resolver in /etc/resolv.conf)
• optional: firewall/security group access if testing cloud infrastructure (AWS, GCP, etc.)

edge cases to know:

• DNS caches can hide propagation issues. flush before testing (systemd-resolve --flush-caches on Linux, dscacheutil -flushcache on macOS).
• TTL (time to live) varies per record. old cached results may linger even after flush if you're testing multiple resolvers.
• some tools (node.js fetch, undici, git, npm, pip) do not auto-read HTTP_PROXY env vars. each needs explicit config.
• TLS handshake can fail if system clock is wrong. verify date on target and client match.
• rate limiting: repeated dig or curl requests to the same target may hit rate limits. add delays between attempts.
• network timeouts: default timeouts vary. curl defaults to 0 (no timeout). netcat defaults to system TCP timeout (often 30+ seconds). use explicit -w or -timeout flags.
• some cloud providers (AWS security groups, GCP firewall) block ICMP (ping) even if TCP port is open.

procedure

step 1: resolve hostname to IP

input: hostname (e.g., example.com)

do one of:

• dig +short example.com (fastest, shows A record only)
• dig example.com (shows full record with TTL)
• nslookup example.com (simpler syntax, more portable)
• host example.com (minimal output)

output: IPv4 address (or blank if resolution fails)

note: if blank, DNS is broken. check step 2 before continuing.

step 2: verify DNS configuration on local system

input: access to /etc/resolv.conf and system DNS tools

run:

cat /etc/resolv.conf
resolvectl status        # Linux only; shows systemd-resolved status

output: list of nameservers (usually 1.1.1.1, 8.8.8.8, or ISP DNS)

decision: if no nameservers listed or all listed servers are unreachable, DNS is misconfigured. try dig @8.8.8.8 example.com to test with public DNS.

step 3: query specific DNS server to check propagation

input: hostname, list of DNS servers to query

run:

dig @8.8.8.8 example.com
dig @1.1.1.1 example.com
dig @9.9.9.9 example.com

or loop:

for dns in 8.8.8.8 1.1.1.1 9.9.9.9 208.67.222.222; do
    echo -n "$dns: "
    dig +short @"$dns" example.com
done

output: IP address from each resolver (may differ if propagation is incomplete)

decision: if results differ between resolvers, DNS is still propagating. check TTL and wait.

step 4: inspect TTL and record details

input: hostname

run:

dig example.com | grep -E '^\S+\s+\d+\s+IN\s+A'

output: line like example.com. 300 IN A 93.184.216.34 (300 = TTL in seconds)

note: if TTL is low (< 300 seconds), changes propagate faster. if TTL is high (3600+), old DNS data will cache longer.

step 5: check local overrides in /etc/hosts

input: access to /etc/hosts

run:

cat /etc/hosts | grep -E "example\.com|api\.example\.com"

output: lines like 127.0.0.1 example.com (if override exists) or blank (if none)

decision: if /etc/hosts entry exists, it overrides DNS globally on that system. edit /etc/hosts to test migrations locally before changing DNS.

step 6: test port connectivity

input: hostname, port number

do one of:

• nc -zv -w 5 example.com 443 (netcat, most reliable, 5 second timeout)
• timeout 3 bash -c 'echo > /dev/tcp/example.com/443' && echo "Open" || echo "Closed" (bash built-in, no extra tools)
• curl -sI -o /dev/null -w "%{http_code}\n" https://example.com (HTTP only, also tests cert)

output: "succeeded" (netcat) or "Open" (bash) or HTTP status code (curl)

note: if port is closed, check firewall rules next (step 9).

step 7: test multiple ports at once

input: hostname, list of ports to test

run:

for port in 22 80 443 5432 6379; do
    nc -zv -w 2 example.com $port 2>&1
done

output: "succeeded" or "failed" for each port

decision: if some ports open and others closed, firewall is likely filtering. check step 9.

step 8: trace network path and diagnose packet loss

input: hostname

do one of:

• traceroute example.com (shows each hop, slow)
• mtr -r -c 20 example.com (continuous, shows packet loss percentage per hop, better)

output: list of hops with IP, latency, and packet loss %

note: if one hop shows high loss, network is congested or routing is suboptimal at that point.

step 9: check firewall rules and listening ports

input: port number, system access (may need sudo)

on Linux (netstat or ss):

ss -tlnp | grep :8080          # Check if port is listening
ss -tlnp                        # Show all listening ports
netstat -tlnp | grep :8080     # Older Linux

on macOS:

lsof -i :8080                  # Show process listening on port 8080
lsof -i -P -n | grep LISTEN    # Show all listening

output: process name and PID listening on that port (or blank if nothing listening)

decision: if port is not in the output, the service isn't listening. start the service. if port is listening but curl/nc can't connect, firewall is blocking.

step 10: view firewall rules

input: system access (usually requires sudo)

on Linux (iptables):

sudo iptables -L -n -v

on Linux (ufw, simpler):

sudo ufw status verbose

on macOS:

sudo /usr/libexec/ApplicationFirewall/socketfilterfw --getglobalstate

output: list of allowed/denied rules

decision: if no ACCEPT rule for your port and source IP, add one or disable firewall for testing.

step 11: add firewall rule to allow traffic

input: port, protocol, optional source IP, system (Linux or macOS)

on Linux (ufw, simplest):

sudo ufw allow 443/tcp
sudo ufw allow from 203.0.113.0/24 to any port 22

on Linux (iptables, lower level):

sudo iptables -A INPUT -p tcp --dport 443 -j ACCEPT
sudo iptables-save > /etc/iptables/rules.v4

output: rule added (ufw prints confirmation, iptables is silent)

note: iptables changes don't persist by default. save with iptables-save to survive reboot.

step 12: test HTTP request with full diagnostics

input: URL, optional custom headers or proxy

run full verbose output:

curl -v https://api.example.com/endpoint

run timing breakdown:

curl -o /dev/null -s -w "
    DNS:        %{time_namelookup}s
    Connect:    %{time_connect}s
    TLS:        %{time_appconnect}s
    TTFB:       %{time_starttransfer}s
    Total:      %{time_total}s
    Status:     %{http_code}
    Size:       %{size_download} bytes
" https://api.example.com/endpoint

output: curl verbose log or timing breakdown

decision: if TLS time is high, cert verification is slow. if TTFB is high, backend is slow. if DNS is high, resolver is slow.

step 13: test with specific HTTP version or TLS version

input: URL, desired HTTP version (1.1, 2, 3) or TLS version (1.2, 1.3)

run:

curl --http2 https://example.com
curl --tlsv1.3 https://example.com

output: HTTP status and response

decision: if request fails with one version but works with another, server may not support the protocol version your client is using.

step 14: test through proxy

input: proxy URL (http://proxy:8080 or socks5://localhost:1080), target URL

run:

curl -x http://proxy.example.com:8080 https://httpbin.org/ip
curl --socks5 localhost:1080 https://httpbin.org/ip

output: HTTP response or proxy error

decision: if proxy test fails but direct test works, proxy is misconfigured or not running. if both fail, check firewall rules.

step 15: set proxy environment variables

input: proxy URL, optional auth credentials

run:

export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
export NO_PROXY=localhost,127.0.0.1,.internal.example.com

with auth:

export HTTPS_PROXY=http://user:password@proxy.example.com:8080

output: env vars set (verify with echo $HTTP_PROXY)

note: curl and most standard tools read these vars. node.js fetch, git, npm, pip do not. configure each tool separately.

step 16: inspect SSL/TLS certificate

input: hostname, port (usually 443)

run:

echo | openssl s_client -connect example.com:443 -servername example.com 2>/dev/null | \
  openssl x509 -noout -subject -issuer -dates

output: subject (CN), issuer, notBefore, notAfter

decision: if notAfter is in the past, cert has expired. if issuer is self-signed and not in your CA bundle, cert verification will fail.

step 17: check certificate expiry

input: hostname, port

run:

echo | openssl s_client -connect example.com:443 2>/dev/null | \
  openssl x509 -noout -enddate

output: line like notAfter=Dec 25 10:30:00 2025 GMT

decision: if date is within 30 days, renew certificate soon. if date is in past, cert is expired and will be rejected.

step 18: download certificate chain

input: hostname, port

run:

openssl s_client -showcerts -connect example.com:443 < /dev/null 2>/dev/null | \
  awk '/BEGIN CERT/,/END CERT/' > chain.pem

output: file chain.pem containing full cert chain (intermediate + root)

note: use this chain for verification or debugging certificate path issues.

step 19: verify certificate against CA bundle

input: server certificate file (server.pem), CA bundle (usually /etc/ssl/certs/ca-certificates.crt)

run:

openssl verify -CAfile /etc/ssl/certs/ca-certificates.crt server.pem

output: server.pem: OK or error message (e.g., "self signed certificate")

decision: if fails, cert is not trusted by system CA bundle. either add cert to bundle or ignore verification (insecure, for testing only).

step 20: test hostname verification (SNI)

input: hostname, port

run:

openssl s_client -connect example.com:443 -servername example.com

output: full TLS handshake output

note: -servername is required for SNI (Server Name Indication). without it, some servers (multi-tenant, CDN) will return wrong certificate.

step 21: quick full diagnostic (all steps at once)

input: hostname, optional port (defaults to 443)

run the quick diagnostics script:

#!/bin/bash
TARGET="${1:?Usage: net-check.sh <hostname> [port]}"
PORT="${2:-443}"

echo "=== Network Check: $TARGET:$PORT ==="

echo -n "DNS resolution: "
IP=$(dig +short "$TARGET" | head -1)
[[ -n "$IP" ]] && echo "$IP" || echo "FAILED"

echo -n "Ping: "
ping -c 1 -W 3 "$TARGET" > /dev/null 2>&1 && echo "OK" || echo "FAILED (may be blocked)"

echo -n "Port $PORT: "
nc -zv -w 5 "$TARGET" "$PORT" 2>&1 | grep -q "succeeded\|open" && echo "OPEN" || echo "CLOSED/FILTERED"

if [[ "$PORT" == "443" || "$PORT" == "8443" ]]; then
    echo -n "TLS: "
    echo | openssl s_client -connect "$TARGET:$PORT" -servername "$TARGET" 2>/dev/null | \
      grep -q "Verify return code: 0" && echo "VALID" || echo "INVALID/ERROR"

    echo -n "Certificate expiry: "
    echo | openssl s_client -connect "$TARGET:$PORT" 2>/dev/null | \
      openssl x509 -noout -enddate 2>/dev/null | sed 's/notAfter=//'
fi

echo "=== Done ==="

output: single report showing DNS, ping, port, TLS, and cert expiry

execution: ./net-check.sh example.com 443

decision points

if DNS resolves locally but fails via public DNS:

• DNS is cached locally in /etc/hosts or systemd-resolved.
• flush cache: systemd-resolve --flush-caches (Linux) or dscacheutil -flushcache (macOS).
• check TTL with dig to see how long cached data will persist.
• if testing a migration, edit /etc/hosts to override DNS locally instead of waiting for propagation.

if DNS doesn't resolve at all:

• check /etc/resolv.conf to verify nameservers are configured.
• test with public DNS: dig @8.8.8.8 example.com.
• if public DNS works, your ISP or network DNS is broken. set nameserver 8.8.8.8 in /etc/resolv.conf or use systemd-resolved config.
• if public DNS also fails, hostname doesn't exist. verify spelling.

if port is unreachable (connection refused or timeout):

• first, verify port is actually open: nc -zv -w 5 example.com 443.
• if netcat reports closed, firewall is blocking. check firewall rules with ufw status or iptables -L.
• if netcat reports open but curl hangs, service is listening but not responding (likely hung or misconfigured). check service logs.

if curl hangs indefinitely:

• add explicit timeout: curl --max-time 10 https://example.com.
• check if service is listening: ss -tlnp | grep :443.
• if service isn't listening, start it. if it is listening but curl hangs, service process may be hung or in a bad state. restart it.

**