Deployment Troubleshooting

Common problems and solutions when deploying Pimeleon router into your network.

Quick Diagnosis

Use this table to quickly identify your issue:

No Internet Access

Symptom

• Pimeleon router boots and works
• Web interface accessible
• Devices can connect to Pimeleon router
• But no internet access for any device

Diagnosis Steps

1. Test Pimeleon router's WAN connection

# SSH into Pimeleon router
ssh pi@192.168.76.1

# Check if WAN interface has IP address
ip addr show eth0

# Ping upstream gateway
ping -c 4 192.168.1.1  # Replace with your gateway IP

# Test DNS from Pimeleon router
nslookup google.com

# Test internet from Pimeleon router
ping -c 4 8.8.8.8

2. Check WAN cable and connection
   • Verify cable plugged into correct port
   • Check for link lights on both ends
   • Try different cable
   • Test cable with another device
3. Verify upstream router/modem
   • Is upstream device working?
   • Can other devices access internet through it?
   • Reboot upstream router/modem

Solutions

Solution 1: WAN Not Getting IP Address

If eth0 has no IP or shows 169.254.x.x:

# Restart networking
sudo systemctl restart networking

# Or manually request DHCP
sudo dhclient -v eth0

# Check if IP assigned
ip addr show eth0

If still no IP:

• Upstream DHCP server may have IP limit
• Try static IP configuration
• Check upstream router DHCP settings

Solution 2: Wrong Default Gateway

# Check current default route
ip route show

# Should show: default via X.X.X.X dev eth0
# If missing or wrong, fix with:
sudo ip route add default via 192.168.1.1 dev eth0  # Use your gateway IP

Solution 3: DNS Not Configured on WAN

# Check DNS servers
cat /etc/resolv.conf

# Should have upstream DNS servers
# If missing, add temporarily:
echo "nameserver 8.8.8.8" | sudo tee -a /etc/resolv.conf

Solution 4: Firewall Blocking WAN

# Check if forwarding enabled
cat /proc/sys/net/ipv4/ip_forward
# Should return: 1

# Enable if needed
sudo sysctl -w net.ipv4.ip_forward=1

# Check NAT rules
sudo nft list chain ip nat postrouting
# Should have MASQUERADE rule for WAN interface

DHCP Server Issues

Devices Can't Get IP Addresses

Symptom

• Devices connect but get 169.254.x.x addresses
• Or devices show "obtaining IP address" forever
• Or devices get wrong subnet

Diagnosis

# Check if DHCP server running
sudo systemctl status dnsmasq

# Check DHCP configuration
cat /etc/dnsmasq.d/pimeleon-dhcp.conf

# Watch DHCP requests in real-time
sudo tail -f /var/log/daemon.log | grep DHCP

Solutions

Solution 1: DHCP Server Not Running

# Start DHCP server
sudo systemctl start dnsmasq

# Enable on boot
sudo systemctl enable dnsmasq

# Check status
sudo systemctl status dnsmasq

Solution 2: DHCP Conflict with Upstream Router

Two DHCP servers on same network causes problems:

Option A: Disable upstream DHCP (recommended if replacing router)

1. Log into upstream router
2. Disable its DHCP server
3. Reboot all devices to get new IPs from Pimeleon router

Option B: Use different subnet (recommended for secondary router mode)

# Edit Pimeleon router subnet
sudo nano /etc/dnsmasq.d/pimeleon-dhcp.conf

# Change to different subnet:
dhcp-range=192.168.77.10,192.168.77.250,12h
# (Assuming upstream uses 192.168.1.x)

Solution 3: DHCP Pool Exhausted

# Check active leases
cat /var/lib/misc/dnsmasq.leases | wc -l

# If at limit, expand range
sudo nano /etc/dnsmasq.d/pimeleon-dhcp.conf
# Increase range: dhcp-range=192.168.76.10,192.168.76.250,12h

# Restart DHCP
sudo systemctl restart dnsmasq

Devices Get Wrong Gateway

Symptom

Devices get IP but Pimeleon router IP isn't set as gateway

Solution

# Check DHCP options
sudo cat /etc/dnsmasq.d/pimeleon-dhcp.conf

# Ensure these lines present:
# dhcp-option=3,192.168.76.1  # Gateway
# dhcp-option=6,192.168.76.1  # DNS server

# If missing, add them
sudo nano /etc/dnsmasq.d/pimeleon-dhcp.conf

# Restart
sudo systemctl restart dnsmasq

Can't Access Web Interface

Symptom

• Can't reach http://pimeleon.local
• Can't reach 192.168.76.1
• Browser shows "connection refused" or timeout

Diagnosis Steps

1. Verify you're on correct network

   # On client computer, check your IP
   # Windows:
   ipconfig
   # Linux/macOS:
   ifconfig
   # or
   ip addr
   
   # Should be in 192.168.76.x range
   

2. Ping Pimeleon router

   ping 192.168.76.1
   # Should get responses
   

3. Check if web server running (from Pimeleon router via SSH)

   sudo systemctl status lighttpd
   # or
   sudo systemctl status nginx
   

Solutions

Solution 1: Wrong Network

If your IP is not 192.168.76.x:

• Disconnect from other networks
• Connect directly to Pimeleon router LAN or WiFi
• Renew DHCP lease (disconnect/reconnect)

Solution 2: Hostname Not Resolving

Try IP address instead of hostname:

• Use http://192.168.76.1 directly
• If works, mDNS/Avahi may not be working

Fix mDNS:

# On Pimeleon router
sudo systemctl status avahi-daemon
sudo systemctl start avahi-daemon

Solution 3: Web Server Not Running

# Start web server
sudo systemctl start lighttpd

# Enable on boot
sudo systemctl enable lighttpd

# Check if listening
sudo netstat -tlnp | grep :80

Solution 4: Firewall Blocking

# Check firewall rules
sudo nft list chain ip filter input | grep 80

# Allow HTTP if blocked
sudo nft insert rule ip filter input tcp dport 80 accept

Slow Performance

Symptom

• Network slower than before deployment
• High latency
• Downloads/uploads crawling
• Buffering on streaming

Diagnosis

# Check CPU usage on Pimeleon router
top
# Press 1 to see all cores
# High CPU (>80%) indicates overload

# Check memory
free -h
# High swap usage indicates RAM pressure

# Check network throughput
iperf3 -s  # On Pimeleon router
iperf3 -c 192.168.76.1  # From client

Solutions

Solution 1: CPU Overload

Identify heavy processes:

top
# Look for processes using >20% CPU

Common culprits and fixes:

• DNS filter service using high CPU: Too many blocklist entries

  # Reduce blocklists in admin interface
  # Keep only essential lists (< 1 million domains)
  

• DNSCrypt using high CPU: Try different resolver

  sudo nano /etc/dnscrypt-proxy/dnscrypt-proxy.toml
  # Try cloudflare or quad9 instead
  

• Squid proxy using high CPU: Reduce cache size or disable

  sudo systemctl stop squid
  # Test if performance improves
  

Solution 2: Insufficient RAM (Pi 3B+ or Pi 4 2GB)

# Check swap usage
free -h

# If swap heavily used:
# - Upgrade to Pi 4 4GB or 8GB
# - Disable unused services
# - Reduce DNS query logging

Solution 3: Bad Network Cable

• Use Cat5e or Cat6 cables
• Replace cables longer than 100 meters
• Check for physical damage
• Test with known-good cable

Solution 4: Thermal Throttling

# Check temperature
vcgencmd measure_temp

# Above 80°C indicates thermal issues

Fix overheating:

• Add heatsinks
• Add active cooling (fan)
• Improve case ventilation
• Move away from heat sources

Solution 5: USB Ethernet Adapter Bottleneck

If using USB Ethernet adapter:

• Ensure USB 3.0 adapter (not USB 2.0)
• Use quality adapter (TP-Link, Plugable, Anker)
• Check adapter isn't overheating
• Try different USB port (use blue USB 3.0 ports)

WiFi Not Working

Symptom

• Pimeleon router WiFi network not visible
• Can't connect to WiFi
• WiFi constantly disconnecting

Diagnosis

# Check WiFi interface status
ip addr show wlan0

# Check if hostapd running
sudo systemctl status hostapd

# Check WiFi configuration
sudo cat /etc/hostapd/hostapd.conf

# Scan for interference
sudo iwlist wlan0 scan | grep -E 'ESSID|Channel|Quality'

Solutions

Solution 1: WiFi Service Not Running

# Start WiFi access point
sudo systemctl start hostapd

# Enable on boot
sudo systemctl enable hostapd

# Check status
sudo systemctl status hostapd

Solution 2: Wrong WiFi Region/Channel

# Edit configuration
sudo nano /etc/hostapd/hostapd.conf

# Set correct country code
country_code=US  # Or your country

# Try different channel (1, 6, or 11 for 2.4GHz)
channel=6

# Restart
sudo systemctl restart hostapd

Solution 3: WiFi Interference

If many WiFi networks nearby:

• Change to less crowded channel
• Use 5GHz if Pi 4 and supported clients
• Move router away from microwaves, cordless phones

Solution 4: Hardware Issue (Pi 3B+)

Pi 3B+ WiFi can be unreliable:

• Use Ethernet for critical connections
• Consider external USB WiFi adapter
• Upgrade to Pi 4 (better WiFi)

Network Conflicts

Symptom

• Some devices work, others don't
• Intermittent connectivity
• Existing network devices lost connection

Diagnosis

Check for IP conflicts:

# From Pimeleon router
sudo arp-scan --localnet

# Look for duplicate IPs

Solutions

Solution 1: Subnet Overlap

If Pimeleon router uses 192.168.1.x and upstream router also uses 192.168.1.x:

Change Pimeleon router subnet:

sudo nano /etc/dhcpcd.conf

# Change static IP:
interface eth1
static ip_address=192.168.76.1/24

# Update DHCP range
sudo nano /etc/dnsmasq.d/pimeleon-dhcp.conf
dhcp-range=192.168.76.10,192.168.76.250,12h

# Reboot
sudo reboot

Solution 2: Static IP Conflicts

If devices have static IPs in Pimeleon router DHCP range:

• Move static IPs outside DHCP range
• Or reserve IPs in Pimeleon router DHCP
• Example: DHCP range .10-.250, static IPs .2-.9

DNS Resolution Problems

Symptom

• Can ping IPs (8.8.8.8) but not hostnames (google.com)
• Some sites work, others don't
• Slow page loading

Diagnosis

# Test DNS from client
nslookup google.com
# Should return IP addresses quickly

# Test from Pimeleon router
ssh pi@192.168.76.1
nslookup google.com

# Check DNS service
sudo systemctl status dnsmasq

Solutions

Solution 1: DNS Service Not Running

sudo systemctl start dnsmasq
sudo systemctl enable dnsmasq

Solution 2: Upstream DNS Servers Unreachable

# Test upstream DNS
dig @8.8.8.8 google.com

# If fails, change upstream DNS servers
sudo nano /etc/dnsmasq.conf

# Add/update:
server=1.1.1.1  # Cloudflare
server=8.8.8.8  # Google

# Restart
sudo systemctl restart dnsmasq

Solution 3: DNS Filtering Blocking Too Much

• Access admin interface interface
• Check Query Log for blocked domains
• Whitelist incorrectly blocked domains
• Disable DNS filtering temporarily to test

Random Disconnections

Symptom

• Devices randomly lose connection
• Network drops every few hours/days
• Have to reboot Pimeleon router frequently

Diagnosis

# Check system logs for errors
sudo journalctl -xe | grep -i error

# Check kernel messages
sudo dmesg | tail -50

# Monitor system stability
uptime

Solutions

Solution 1: Power Supply Insufficient

Most common cause of instability!

• Use official Raspberry Pi power supply
• Pi 4: 5V 3A USB-C (15W)
• Pi 3B+: 5V 2.5A micro-USB (12.5W minimum)
• Avoid phone chargers or cheap adapters

Test with known-good power supply

Solution 2: SD Card Failing

# Check filesystem errors
sudo fsck -n /dev/mmcblk0p2

# Check SD card health (if supported)
sudo smartctl -a /dev/mmcblk0

Solutions:

• Replace SD card with high-endurance model
• Use quality brand (SanDisk, Samsung)
• Consider USB boot instead of SD

Solution 3: Overheating

# Monitor temperature
watch -n 2 vcgencmd measure_temp

# Above 80°C causes throttling
# Above 85°C system becomes unstable

Add cooling:

• Heatsinks on CPU/RAM chips
• Active cooling (fan)
• Better ventilated case

Solution 4: Memory Leak

# Monitor memory over time
free -h
# Watch if "available" memory decreases

# Identify memory-hungry process
ps aux --sort=-%mem | head

Fix:

• Restart offending service
• Reduce caching in Squid/DNS filter
• Add swap space if RAM limited
• Upgrade to more RAM

Solution 5: Network Driver Issues

# Check for interface errors
ip -s link show eth0
ip -s link show wlan0

# Look for errors, dropped packets

# Update firmware if available
sudo rpi-update

Common Error Messages

"Failed to start dnsmasq.service"

Cause: Port 53 already in use or configuration error

Fix:

# Check what's using port 53
sudo lsof -i :53

# Kill conflicting service or
# Fix configuration syntax
sudo nano /etc/dnsmasq.conf
# Check for typos

sudo systemctl restart dnsmasq

"DHCP packet received on eth0 which has no address"

Cause: DHCP client running on wrong interface

Fix:

sudo nano /etc/dhcpcd.conf

# Add:
denyinterfaces eth1  # Or wlan0, whatever is LAN

sudo systemctl restart dhcpcd

"Temperature above 80.0°C - throttling"

Cause: Overheating

Fix: Add cooling (see Random Disconnections)

Getting More Help

Collect Diagnostic Information

Before asking for help, collect:

# System info
cat /etc/os-release
uname -a

# Network config
ip addr
ip route
cat /etc/resolv.conf

# Service status
sudo systemctl status dnsmasq
sudo systemctl status hostapd

# Recent errors
sudo journalctl -xe --no-pager | tail -100

# Temperature and throttling
vcgencmd measure_temp
vcgencmd get_throttled

Where to Get Help

• Community Forum - Ask the community
• FAQ - Common questions
• Boot Issues - Won't boot?
• Network Troubleshooting - General network issues

Related Documentation

• Deployment Guide - Deployment overview
• Network Integration - Integration methods
• Physical Setup - Hardware setup
• Getting Started - Post-deployment configuration

← Previous: Physical Setup | [🏠 Documentation Home//)