dotlinux guide

Troubleshooting Network Issues Using Linux Command Line

In the modern digital landscape, reliable network connectivity is critical for everything from server operations to user productivity. Linux, being the backbone of countless servers, cloud environments, and embedded systems, offers a robust suite of command-line tools for diagnosing and resolving network issues. Unlike graphical tools, Linux CLI utilities are lightweight, scriptable, and available on nearly all Linux distributions, making them indispensable for system administrators, developers, and DevOps engineers. This blog aims to provide a comprehensive guide to troubleshooting network issues using Linux CLI tools. We’ll cover fundamental concepts, essential utilities, common troubleshooting workflows, and best practices to help you efficiently identify and resolve connectivity, DNS, routing, and traffic-related problems.

Table of Contents

Fundamentals of Network Troubleshooting

Before diving into tools, it’s critical to understand the foundational concepts that govern network behavior. This knowledge will help you isolate issues to specific layers of the network stack.

The OSI Model: A Troubleshooting Framework

The Open Systems Interconnection (OSI) model divides network communication into 7 layers, from physical hardware to application-level protocols. Troubleshooting often involves isolating issues to one or more layers:

LayerNameFocusCommon Issues
1PhysicalCables, NICs, switches, signalLoose cables, faulty ports, no link
2Data LinkMAC addresses, Ethernet, VLANsARP issues, VLAN misconfiguration
3NetworkIP addresses, routing, subnetsNo IP, incorrect gateway, routing loops
4TransportTCP/UDP ports, flow controlBlocked ports, timeouts, packet loss
5-7Session/Presentation/ApplicationAPIs, HTTP, DNS, SSL/TLSDNS failures, application bugs, SSL errors

Key Network Components

  • Network Interfaces: Physical (e.g., eth0, enp0s3) or virtual (e.g., lo, docker0) network cards (NICs) that send/receive data.
  • IP Addressing: Unique identifiers (IPv4/IPv6) for devices on a network (e.g., 192.168.1.100, 2001:db8::1).
  • DNS (Domain Name System): Translates human-readable domain names (e.g., google.com) to IP addresses.
  • Routing: The process of forwarding traffic between networks via gateways (e.g., default gateway for internet access).
  • Ports & Protocols: TCP (reliable, connection-oriented) and UDP (unreliable, connectionless) ports (1-65535) enable communication between applications (e.g., port 80 for HTTP, 443 for HTTPS).

Essential Linux Network Troubleshooting Tools

Linux provides a rich ecosystem of CLI tools for diagnosing network issues. Below are the most critical utilities, organized by use case.

1. Checking Network Interfaces

Before troubleshooting connectivity, verify that your network interfaces are up, have valid IP addresses, and are physically connected.

ip (iproute2 suite)

The ip command (part of the iproute2 package) replaces legacy tools like ifconfig and route. It manages interfaces, IP addresses, and routing.

Common Use Cases:

  • List all interfaces with IP addresses:

    ip addr show  # Shorthand: ip a

    Output includes interface name (e.g., eth0), MAC address, IPv4/IPv6 addresses, and state (e.g., UP, DOWN).

  • Check interface link status (up/down):

    ip link show  # Shorthand: ip l

    Look for <UP,LOWER_UP> to confirm the interface is enabled and has a physical link.

  • Enable/disable an interface:

    sudo ip link set eth0 up   # Bring interface up  
sudo ip link set eth0 down # Bring interface down

ethtool

Check physical link details (speed, duplex, link status) for Ethernet interfaces:

ethtool eth0  # Replace "eth0" with your interface

Key output:

  • Link detected: yes (confirms physical connectivity).
  • Speed: 1000Mb/s (negotiated speed).
  • Duplex: Full (communication mode).

Legacy Tools (Deprecated but Still Used)

  • ifconfig (obsolete, replaced by ip addr): 
    ifconfig eth0  # Shows IP, netmask, MAC, and status

2. Testing Connectivity

Once interfaces are confirmed up, test end-to-end connectivity using these tools.

ping (ICMP Echo)

Tests Layer 3 (Network) connectivity using ICMP echo requests.

Examples:

  • Test IPv4 connectivity to a host:

    ping -c 4 google.com  # -c: Send 4 packets

    Output shows packet loss (0% packet loss = good), round-trip time (RTT), and TTL (time-to-live).

  • Test IPv6 connectivity:

    ping6 -c 4 2001:4860:4860::8888  # Google's IPv6 DNS

Notes: Some networks block ICMP (e.g., firewalls), so ping may fail even if the host is reachable.

mtr (Combines ping and traceroute)

mtr (My Traceroute) provides real-time insights into packet loss and latency across network hops.

Examples:

  • Interactive mode (run and press q to exit): 
    mtr google.com
  • Generate a report (non-interactive): 
    mtr --report --report-cycles 10 google.com  # 10 cycles per hop
    Look for Loss% to identify hops with packet loss (e.g., a router dropping traffic).

traceroute / tracepath

Maps the path traffic takes from your host to a target (Layer 3).

  • traceroute (requires root for raw sockets):

    sudo traceroute google.com

    Output shows hop number, router IPs, and round-trip times. Gaps (* * *) indicate unresponsive hops.

  • tracepath (no root required, uses UDP):

    tracepath google.com

telnet / nc (Netcat)

Test Layer 4 (Transport) connectivity by checking if a port is open.

  • telnet (simplest port check):

    telnet google.com 80  # Test port 80 (HTTP)

    Success: Connected to google.com (port open).
    Failure: Connection refused (port closed) or timeout (blocked by firewall).

  • nc (Netcat) (more versatile):

    nc -zv google.com 443  # -z: Zero I/O (scan mode), -v: Verbose

    Output: Connection to google.com 443 port [tcp/https] succeeded!

3. DNS Troubleshooting

If ping google.com fails but ping 8.8.8.8 works, DNS resolution is likely the issue.

dig (Domain Information Groper)

Powerful tool for querying DNS records.

Examples:

  • Basic A record lookup (IPv4 address):

    dig google.com A +short  # +short: Minimal output

    Output: 142.250.185.14 (IPv4 address).

  • Check MX (mail server) records:

    dig example.com MX

  • Trace DNS delegation path:

    dig google.com +trace  # Shows root → TLD → authoritative server steps

nslookup / host

Simpler DNS lookup tools:

nslookup google.com  # Basic DNS query  
host google.com      # Alternate, more concise output

Checking DNS Configuration

  • /etc/resolv.conf: Lists DNS servers (on non-systemd systems):

    cat /etc/resolv.conf

    Look for nameserver 8.8.8.8 (Google DNS) or nameserver 192.168.1.1 (local router).

  • systemd-resolve (systemd-based systems):

    systemd-resolve --status  # Shows DNS servers and search domains  
systemd-resolve google.com  # Resolve using systemd-resolved

4. Routing Information

Incorrect routing (Layer 3) can block access to remote networks. Use these tools to inspect and modify routes.

ip route (iproute2 suite)

Replaces route (deprecated) for managing routing tables.

Examples:

  • List all routes:

    ip route show  # Shorthand: ip r

    Key entry: default via 192.168.1.1 dev eth0 (default gateway for internet access).

  • Add a static route:

    sudo ip route add 10.0.0.0/24 via 192.168.1.1  # Route 10.0.0.0/24 via gateway 192.168.1.1

  • Delete a route:

    sudo ip route del 10.0.0.0/24

Legacy Tool: route

route -n  # -n: Numeric output (no DNS lookup)

5. Traffic Analysis & Socket Monitoring

To diagnose port conflicts, application-level issues, or abnormal traffic, use these tools.

tcpdump (Packet Capture)

Captures raw network packets (Layer 2-4) for deep analysis.

Examples:

  • Capture all traffic on interface eth0:

    sudo tcpdump -i eth0

  • Filter by port (e.g., HTTP/80):

    sudo tcpdump -i eth0 port 80

  • Save packets to a file for later analysis (e.g., with Wireshark):

    sudo tcpdump -i eth0 port 443 -w ssl_traffic.pcap

  • Read a saved capture:

    tcpdump -r ssl_traffic.pcap

ss (Socket Statistics)

Replaces netstat (deprecated) to list active network sockets (Layer 4).

Examples:

  • List all listening TCP/UDP ports:

    ss -tuln  # t: TCP, u: UDP, l: Listening, n: Numeric

    Output includes port numbers (e.g., *:80 = HTTP), protocol, and state (LISTEN).

  • Show processes using sockets (requires root):

    sudo ss -tulnp  # -p: Show PID/process name

lsof (List Open Files)

Identify processes using network ports (useful for debugging port conflicts).

Example: Find what’s using port 80:

sudo lsof -i :80  # -i: Network files, :80: Filter by port

Output shows PID, process name (e.g., nginx), and user.

Common Scenarios & Troubleshooting Workflow

Below is a step-by-step workflow for resolving a typical issue: “I can’t access example.com.”

Step 1: Check Local Interface Health

  • Verify the interface is up and has an IP: 
    ip addr show eth0  # Ensure state is UP and IP is assigned (not "NO-CARRIER")
  • Check physical link: 
    ethtool eth0 | grep "Link detected"  # Should return "yes"

Step 2: Test Default Gateway

  • Confirm the default gateway exists: 
    ip route show default  # Should return "default via <gateway-ip> dev eth0"
  • Ping the gateway: 
    ping -c 2 192.168.1.1  # Replace with your gateway IP
    If no response: Gateway is down, or local network issue (e.g., VLAN misconfiguration).

Step 3: Test External Connectivity (Bypass DNS)

  • Ping a public IP (e.g., Google DNS): 
    ping -c 2 8.8.8.8
    • Success: Internet is reachable (DNS may be the issue).
    • Failure: Check gateway, ISP, or firewall rules.

Step 4: Diagnose DNS Issues

  • Resolve example.com manually: 
    dig example.com +short  # Should return an IP (e.g., 93.184.216.34)
    • No output: DNS server is unresponsive or example.com has no A record.
    • Check /etc/resolv.conf or systemd-resolve --status for valid DNS servers.

Step 5: Check Application Port

  • Verify the target port (e.g., 443 for HTTPS) is open: 
    nc -zv example.com 443
    • Connection refused: Port closed on the server.
    • Timeout: Firewall blocking the port (local or remote).

Step 6: Analyze Path with mtr

  • Identify packet loss or latency in the network path: 
    mtr --report example.com
    Look for hops with Loss% > 0 (e.g., a faulty router).

Best Practices

  1. Start with the Basics: Always check physical connectivity (cables, ports) and interface status before diving into complex tools.
  2. Document Everything: Log commands, outputs, and timestamps (e.g., script troubleshooting.log to record the session).
  3. Use Non-Intrusive Tools First: ping, mtr, and ss are lightweight; reserve tcpdump for advanced cases.
  4. Check Logs: System logs often reveal clues: 
    journalctl -u NetworkManager  # NetworkManager logs  
dmesg | grep eth0  # Kernel logs for interface issues
  5. Test with Numeric IPs: Bypass DNS by using IPs (e.g., 8.8.8.8) to isolate DNS issues.
  6. Secure Packet Captures: tcpdump captures may contain sensitive data (e.g., passwords). Encrypt or delete them after analysis.
  7. Avoid Deprecated Tools: Use ip route instead of route, ss instead of netstat, and dig instead of nslookup.

Conclusion

Troubleshooting network issues in Linux requires a mix of foundational knowledge and hands-on familiarity with CLI tools. By methodically checking interfaces, routing, DNS, and connectivity, you can isolate issues to specific OSI layers and resolve them efficiently. The tools covered here—ip, ping, mtr, dig, tcpdump, and ss—are your Swiss Army knife for diagnosing everything from loose cables to complex routing loops.

Practice with these utilities in a lab environment to build confidence, and always follow the best practices outlined above to ensure safe and effective troubleshooting.

References