Debian Network Troubleshooting
Introduction
Network troubleshooting is an essential skill for any Debian system administrator or enthusiast. When network connectivity issues arise, having a systematic approach to identify and resolve problems can save hours of frustration. This guide will walk you through the common network issues on Debian systems and provide practical tools and techniques to diagnose and fix them.
Whether you're dealing with a simple connection problem or a complex networking issue, this guide will equip you with the knowledge to efficiently troubleshoot and resolve network problems on your Debian system.
Basic Network Concepts
Before diving into troubleshooting, let's review some fundamental networking concepts that will help you understand the troubleshooting process better.
Network Layers
Networks operate on different layers, and problems can occur at any layer:
When troubleshooting, it's often best to start at the physical layer and work your way up, verifying each layer functions correctly.
Common Network Components in Debian
- Network Interface: Physical or virtual device that connects your computer to a network (e.g.,
eth0
,wlan0
) - IP Address: Unique identifier for your device on a network
- Gateway: Router that connects your local network to other networks
- DNS Servers: Servers that translate domain names to IP addresses
- Netmask: Defines the range of IP addresses in your subnet
Essential Network Troubleshooting Tools
Debian comes with powerful tools for diagnosing and fixing network issues. Let's explore the most important ones:
1. Network Status Tools
ip
Command
The ip
command is the modern replacement for ifconfig
and provides comprehensive information about your network interfaces.
# Show all network interfaces
ip link
# Show IP addresses assigned to interfaces
ip addr
# Show routing table
ip route
Example output of ip addr
:
1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1000
link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
inet 127.0.0.1/8 scope host lo
valid_lft forever preferred_lft forever
inet6 ::1/128 scope host
valid_lft forever preferred_lft forever
2: eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP group default qlen 1000
link/ether 00:1a:2b:3c:4d:5e brd ff:ff:ff:ff:ff:ff
inet 192.168.1.100/24 brd 192.168.1.255 scope global eth0
valid_lft forever preferred_lft forever
inet6 fe80::21a:2bff:fe3c:4d5e/64 scope link
valid_lft forever preferred_lft forever
netstat
or ss
These tools show network connections, routing tables, and interface statistics.
# Show all listening ports and established connections
ss -tuln
# Show network statistics
netstat -i
Example output of ss -tuln
:
Netid State Recv-Q Send-Q Local Address:Port Peer Address:Port
udp UNCONN 0 0 127.0.0.53%lo:53 0.0.0.0:*
udp UNCONN 0 0 0.0.0.0:68 0.0.0.0:*
tcp LISTEN 0 128 0.0.0.0:22 0.0.0.0:*
tcp LISTEN 0 128 127.0.0.1:631 0.0.0.0:*
tcp LISTEN 0 128 [::]:22 [::]:*
2. Connectivity Testing Tools
ping
The simplest tool to check if a host is reachable:
# Test connectivity to Google's DNS server
ping 8.8.8.8
# Test connectivity to a domain
ping debian.org
Example output:
PING 8.8.8.8 (8.8.8.8) 56(84) bytes of data.
64 bytes from 8.8.8.8: icmp_seq=1 ttl=118 time=12.3 ms
64 bytes from 8.8.8.8: icmp_seq=2 ttl=118 time=11.9 ms
64 bytes from 8.8.8.8: icmp_seq=3 ttl=118 time=12.1 ms
--- 8.8.8.8 ping statistics ---
3 packets transmitted, 3 received, 0% packet loss, time 2003ms
rtt min/avg/max/mdev = 11.902/12.106/12.316/0.169 ms
traceroute
Shows the path packets take to reach a destination:
# Trace route to Debian's website
traceroute debian.org
Example output:
traceroute to debian.org (149.20.4.15), 30 hops max, 60 byte packets
1 _gateway (192.168.1.1) 1.234 ms 1.456 ms 1.789 ms
2 isp-router.example.net (203.0.113.1) 15.643 ms 16.012 ms 16.345 ms
3 backbone-1.example.net (198.51.100.1) 20.123 ms 20.456 ms 20.789 ms
...
15 debian.org (149.20.4.15) 78.123 ms 78.456 ms 78.789 ms
mtr
Combines ping and traceroute in a continuously updating display:
# Run MTR to Debian's website
mtr debian.org
Example output:
My traceroute [v0.92]
host (192.168.1.100) Thu Mar 13 14:22:38 2025
Keys: Help Display mode Restart statistics Order of fields quit
Packets Pings
Host Loss% Snt Last Avg Best Wrst StDev
1. _gateway 0.0% 10 1.2 1.3 1.1 1.5 0.1
2. isp-router.example.net 0.0% 10 15.6 15.8 15.3 16.4 0.3
...
15. debian.org 0.0% 10 78.1 78.5 77.9 79.3 0.4
3. DNS Troubleshooting Tools
dig
or nslookup
These tools query DNS servers for information:
# Look up the IP address for debian.org
dig debian.org
# Query a specific DNS server
dig @8.8.8.8 debian.org
Example output of dig debian.org
:
; <<>> DiG 9.16.33-Debian <<>> debian.org
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 12345
;; flags: qr rd ra; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 1
;; QUESTION SECTION:
;debian.org. IN A
;; ANSWER SECTION:
debian.org. 3599 IN A 149.20.4.15
;; Query time: 28 msec
;; SERVER: 127.0.0.53#53(127.0.0.53)
;; WHEN: Thu Mar 13 14:25:30 UTC 2025
;; MSG SIZE rcvd: 56
host
A simpler DNS lookup tool:
# Look up hostname for an IP
host 8.8.8.8
# Look up IP for a hostname
host debian.org
Example output:
debian.org has address 149.20.4.15
debian.org has IPv6 address 2001:4f8:1:c::15
debian.org mail is handled by 10 mailly.debian.org.
4. Network Configuration Files
Understanding these files is crucial for effective troubleshooting:
- /etc/network/interfaces: Traditional network interface configuration
- /etc/netplan/: Configuration for newer versions of Debian using Netplan
- /etc/resolv.conf: DNS resolver configuration
- /etc/hosts: Static hostname to IP mappings
Common Network Issues and Solutions
Let's explore typical network problems and how to solve them systematically:
Issue 1: No Network Connectivity
Step-by-Step Troubleshooting:
-
Check physical connection
Verify cables are properly connected and network interface LEDs are active.
-
Verify interface status
baship link show
Look for
UP
orDOWN
status. If it's down, bring it up:bashsudo ip link set eth0 up
-
Check IP address assignment
baship addr show
If no IP address is assigned, try:
bash# For static IP
sudo ip addr add 192.168.1.100/24 dev eth0
# For DHCP
sudo dhclient eth0 -
Verify default gateway
baship route show
If no default route exists, add one:
bashsudo ip route add default via 192.168.1.1 dev eth0
Issue 2: DNS Problems
If you can ping an IP address but not a domain name, you have a DNS issue:
-
Check DNS configuration
bashcat /etc/resolv.conf
It should contain valid nameservers, e.g.:
nameserver 8.8.8.8
nameserver 8.8.4.4 -
Test DNS resolution
bashdig debian.org
If that fails, try with a specific DNS server:
bashdig @8.8.8.8 debian.org
-
Fix DNS configuration
bashsudo nano /etc/resolv.conf
Add reliable DNS servers:
nameserver 8.8.8.8
nameserver 1.1.1.1Make changes permanent by editing the appropriate configuration file, which might be:
/etc/network/interfaces
/etc/netplan/*.yaml
/etc/dhcp/dhclient.conf
Issue 3: Intermittent Connectivity
-
Check for packet loss
bashping -c 100 8.8.8.8
Look for packet loss percentage in the summary.
-
Monitor connection quality
bashmtr google.com
Watch for high packet loss or latency at specific hops.
-
Check interface errors
baship -s link show eth0
Look for increasing error counts which might indicate hardware issues.
Issue 4: Firewall Blocks
-
Check if iptables is blocking traffic
bashsudo iptables -L -v
-
Temporarily disable the firewall for testing
bashsudo iptables -F
If connectivity returns, you need to adjust your firewall rules.
-
Add appropriate rules
bashsudo iptables -A INPUT -p tcp --dport 80 -j ACCEPT
sudo iptables -A INPUT -p tcp --dport 443 -j ACCEPT
Practical Troubleshooting Scenarios
Scenario 1: Web Server Access Problem
Imagine you have a web server running on your Debian system, but users can't access it:
-
Verify the web server is running
bashsudo systemctl status apache2
-
Check if the web server is listening on the expected port
bashss -tuln | grep 80
-
Test local access
bashcurl http://localhost
-
Check firewall rules
bashsudo iptables -L | grep 80
-
Verify network interface configuration
baship addr show
Scenario 2: Diagnosing Slow Network Performance
-
Check current network usage
bashiftop -i eth0
Or if not installed:
bashsudo apt update && sudo apt install iftop
-
Identify processes using network bandwidth
bashnethogs eth0
-
Test network throughput
bash# Install iperf3 if needed
sudo apt install iperf3
# Run as server on one machine
iperf3 -s
# Run as client on another machine
iperf3 -c server_ip_address -
Check for duplex mismatches
bashethtool eth0 | grep -E 'Speed|Duplex'
Advanced Troubleshooting Techniques
Network Packet Capture with tcpdump
tcpdump
is a powerful tool for analyzing network traffic:
# Capture packets on interface eth0
sudo tcpdump -i eth0
# Capture packets for a specific host
sudo tcpdump -i eth0 host 192.168.1.10
# Capture specific port traffic
sudo tcpdump -i eth0 port 80
# Save capture to a file for later analysis
sudo tcpdump -i eth0 -w capture.pcap
Example output:
14:35:24.123456 IP 192.168.1.100.58642 > 93.184.216.34.80: Flags [S], seq 123456789, win 64240, options [mss 1460,sackOK,TS val 1234567 ecr 0,nop,wscale 7], length 0
14:35:24.234567 IP 93.184.216.34.80 > 192.168.1.100.58642: Flags [S.], seq 987654321, ack 123456790, win 65535, options [mss 1460,sackOK,TS val 9876543 ecr 1234567,nop,wscale 7], length 0
14:35:24.234678 IP 192.168.1.100.58642 > 93.184.216.34.80: Flags [.], ack 1, win 502, options [nop,nop,TS val 1234568 ecr 9876543], length 0
Network Boot Process Understanding
Understanding the boot process can help troubleshoot persistent issues:
- Interface initialization: Kernel loads network drivers
- Configuration application: System reads configs from
/etc/network/interfaces
or/etc/netplan/
- DHCP negotiation (if using DHCP)
- Interface activation: Network interfaces come online
- Routing table setup: Default routes and static routes established
- DNS configuration:
/etc/resolv.conf
populated
Making Network Changes Persistent
For Traditional Debian Systems
Edit the /etc/network/interfaces
file:
sudo nano /etc/network/interfaces
Example configuration:
# The loopback network interface
auto lo
iface lo inet loopback
# The primary network interface
auto eth0
iface eth0 inet static
address 192.168.1.100
netmask 255.255.255.0
gateway 192.168.1.1
dns-nameservers 8.8.8.8 8.8.4.4
For DHCP:
auto eth0
iface eth0 inet dhcp
For Newer Debian Systems (using Netplan)
Edit or create a file in /etc/netplan/
:
sudo nano /etc/netplan/01-netcfg.yaml
Example configuration:
network:
version: 2
renderer: networkd
ethernets:
eth0:
dhcp4: no
addresses:
- 192.168.1.100/24
gateway4: 192.168.1.1
nameservers:
addresses: [8.8.8.8, 8.8.4.4]
Apply the configuration:
sudo netplan apply
Troubleshooting Wireless Networks
Wireless networks add another layer of complexity:
-
Check wireless interface status
baship link show wlan0
-
Scan for available networks
bashsudo iwlist wlan0 scan | grep ESSID
-
Check connection quality
bashiwconfig wlan0
Look for "Link Quality" and "Signal level" in the output.
-
Restart wireless interface
bashsudo ip link set wlan0 down
sudo ip link set wlan0 up -
Connect to a network manually
bashsudo iwconfig wlan0 essid "NetworkName" key s:password
sudo dhclient wlan0
Summary
Network troubleshooting in Debian is a methodical process that involves:
- Identifying the problem: Determine which layer of the network stack is affected
- Gathering information: Use tools like
ip
,ping
,dig
, andtraceroute
- Testing hypotheses: Make controlled changes to isolate the issue
- Implementing solutions: Apply fixes systematically
- Verifying the fix: Ensure the problem is resolved and doesn't recur
By following a structured approach and understanding the tools at your disposal, you can efficiently diagnose and resolve most network issues on your Debian system.
Additional Resources
To deepen your understanding of Debian networking, consider exploring:
- The Debian Network Configuration wiki page
- The
man
pages for networking tools:man ip
,man netstat
,man tcpdump
- The book "TCP/IP Network Administration" by Craig Hunt
- The Linux Network Administrators Guide
Exercises
- Deliberately disconnect your network cable and practice bringing the interface back up
- Set up a static IP address, then change it back to DHCP
- Configure your system to use alternate DNS servers
- Use
tcpdump
to capture HTTP traffic while accessing a website - Create a script that performs basic network diagnostics and reports any issues found
If you spot any mistakes on this website, please let me know at [email protected]. I’d greatly appreciate your feedback! :)