Network

Chapter 48: Network Connectivity Issues

Overview

Network connectivity problems are among the most common issues affecting blockchain nodes. Without proper network connectivity, a node cannot discover peers, synchronize with the blockchain, or serve RPC requests. This chapter provides comprehensive troubleshooting guidance for diagnosing and resolving network-related issues in blockchain infrastructure.

---

48.1 Network Architecture

Blockchain P2P Network

┌─────────────────────────────────────────────────────────────┐
│              BLOCKCHAIN P2P NETWORK                             │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  ┌─────────┐    ┌─────────┐    ┌─────────┐    ┌─────────┐  │
│  │ Node A  │◄──►│ Node B  │◄──►│ Node C  │◄──►│ Node D  │  │
│  │         │    │         │    │         │    │         │  │
│  └────┬────┘    └────┬────┘    └────┬────┘    └────┬────┘  │
│       │              │              │              │        │
│       ▼              ▼              ▼              ▼        │
│  ┌─────────────────────────────────────────────────────┐   │
│  │                  Discovery Protocol                   │   │
│  │            (Discv5 for Ethereum, etc.)              │   │
│  └─────────────────────────────────────────────────────┘   │
│                           │                                  │
│                           ▼                                  │
│  ┌─────────────────────────────────────────────────────┐   │
│  │              Bootstrap Nodes                          │   │
│  │        (Well-known nodes for initial discovery)      │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                              │
└─────────────────────────────────────────────────────────────┘

Required Ports

Protocol	Port	Direction	Purpose
TCP	30303	Both	Ethereum P2P
UDP	30303	Both	Discovery
TCP	8545	Inbound	HTTP RPC
TCP	8546	Inbound	WebSocket RPC
TCP	6060	Local	Metrics

---

48.2 No Peers / Discovery Issues

Symptoms

┌─────────────────────────────────────────┐
│       NO PEERS SYMPTOMS                   │
├─────────────────────────────────────────┤
│                                          │
│  ✓ Peer count is 0                      │
│  ✓ Node shows "Looking for peers"       │
│  ✓ Cannot sync blocks                   │
│  ✓ RPC returns but no data              │
│                                          │
└─────────────────────────────────────────┘

Diagnosis

# 1. Check current peer count
curl -X POST http://localhost:8545 \
    -H "Content-Type: application/json" \
    -d '{"jsonrpc":"2.0","method":"net_peerCount","params":[],"id":1}'

# Response: {"jsonrpc":"2.0","id":1,"result":"0x0"}

# 2. Check listening status
curl -X POST http://localhost:8545 \
    -H "Content-Type: application/json" \
    -d '{"jsonrpc":"2.0","method":"net_listening","params":[],"id":1}'

# 3. Check node info
curl -X POST http://localhost:8545 \
    -H "Content-Type: application/json" \
    -d '{"jsonrpc":"2.0","method":"admin_nodeInfo","params":[],"id":1}'

# 4. Check logs for discovery issues
journalctl -u geth | grep -i "discovery"
journalctl -u geth | grep -i "dial"
journalctl -u geth | grep -i "peer"

Solutions

1. Check Firewall

# Check if ports are open
sudo ufw status

# Or check iptables
sudo iptables -L -n | grep 30303

# Test port connectivity
nc -zv discovery.ethdisco.net 30303

# Alternative: use telnet
telnet discovery.ethdisco.net 30303

2. Add Bootnodes

# Ethereum Mainnet bootnodes
geth --bootnodes \
    "enr:-KG4QOtcLhT1LioJW5XHmhLGr9jnoJ5XF8J8p TzW7yGrqDzoP3z6E1T5C9LwK3uK8Q6G7F9B2M1K3W8=-BMgBFYHr7tJ3z6E1T5C9LwK3uK8Q6G7F9B2M1K3W8@bootnode1.mainnet.ethdisco.net:30303,\
     enr:-Ly4QFn-6sJ8tJ3z6E1T5C9LwK3uK8Q6G7F9B2M1K3W8=-BMgBFYHr7tJ3z6E1T5C9LwK3uK8Q6G7F9B2M1K3W8@bootnode2.mainnet.ethdisco.net:30303,\
     enr:-Ku4QO7sJ8tJ3z6E1T5C9LwK3uK8Q6G7F9B2M1K3W8=-BMgBFYHr7tJ3z6E1T5C9LwK3uK8Q6G7F9B2M1K3W8@bootnode3.mainnet.ethdisco.net:30303"

# In config file:
# Add to config.toml:
# [Node]
# Bootnodes = ["enr:..."]

3. Enable Discovery

# Enable discovery (default is true)
geth --nodiscover=false

# Check if discovery is enabled
geth attach http://localhost:8545
> admin.admin.nodeInfo

---

48.3 Peers Dropping

Symptoms

┌─────────────────────────────────────────┐
│       PEERS DROPPING SYMPTOMS              │
├─────────────────────────────────────────┤
│                                          │
│  ✓ Peer count fluctuating               │
│  ✓ Peers connecting and disconnecting   │
│  ✓ Sync stalls frequently               │
│  ✓ High reorg rate                      │
│                                          │
└─────────────────────────────────────────┘

Diagnosis

# Check peer connections
geth attach http://localhost:8545
> admin.peers

# Check peer details
admin.peers.forEach(p => console.log(p.id, p.network.remoteAddress))

# Monitor peer events
geth attach http://localhost:8545
> admin.addPeer("enr:...")
> admin.removePeer("enr:...")

# Check logs
journalctl -u geth | grep -i "dropped"
journalctl -u geth | grep -i "disconnect"

Root Causes

Cause	Description	Probability
Firewall	Ports blocked, causing timeouts	High
NAT	Not properly forwarding ports	Medium
IP Ban	Your IP flagged by network	Medium
Bandwidth	Insufficient bandwidth	Low
Node Bug	Client software issue	Low

Solutions

1. Check Network Stability

# Test network latency
ping -c 10 discovery.ethdisco.net

# Test bandwidth
speedtest-cli

# Check for packet loss
ping -c 100 discovery.ethdisco.net | grep "packet loss"

2. Increase Dial Timeout

# Configure external IP
geth --nat extip:YOUR_PUBLIC_IP

# Increase dial timeout
geth --dial.timeout 30s

# Or in config:
# [Node]
# DialTimeout = 30s

3. Check IP Reputation

# Check if IP is flagged
# Visit https://www.bgcheck.co/ or similar
# Check with cloud provider if using AWS/GCP

# If banned, you may need to:
# - Contact network team
# - Use different IP range
# - Wait for ban to expire

---

48.4 DNS Issues

Symptoms

┌─────────────────────────────────────────┐
│       DNS ISSUES SYMPTOMS                  │
├─────────────────────────────────────────┤
│                                          │
│  ✓ Cannot resolve bootnode addresses     │
│  ✓ Hostnames not resolving              │
│  ✓ Intermittent connectivity            │
│                                          │
└─────────────────────────────────────────┘

Solutions

# Use alternative DNS servers
# In /etc/resolv.conf:
nameserver 8.8.8.8
nameserver 8.8.4.4
nameserver 1.1.1.1

# Or specify DNS in geth
geth --dns-nameserver 8.8.8.8

# Test DNS resolution
nslookup discovery.ethdisco.net
dig discovery.ethdisco.net
host discovery.ethdisco.net

# Use static IPs instead of hostnames
geth --bootnodes "192.168.1.100:30303"

---

48.5 Port Forwarding

For Home/Office Networks

┌─────────────────────────────────────────────────────────────┐
│              PORT FORWARDING SETUP                             │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  Router Configuration:                                        │
│  ┌─────────────────────────────────────────────────────┐   │
│  │  External Port: 30303                               │   │
│  │  Internal Port: 30303                               │   │
│  │  Protocol: TCP/UDP                                  │   │
│  │  Internal IP: 192.168.1.100                         │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                              │
│  Firewall (if applicable):                                   │
│  sudo ufw allow 30303/tcp                                  │
│  sudo ufw allow 30303/udp                                  │
│                                                              │
└─────────────────────────────────────────────────────────────┘

Verify Port Forwarding

# Check if port is listening
sudo netstat -tulpn | grep 30303

# Or use ss
sudo ss -tulpn | grep 30303

# Check external connectivity
# Visit https://canyouseeme.org/
# Enter port 30303 and check

---

48.6 NAT Traversal

Understanding NAT Issues

┌─────────────────────────────────────────────────────────────┐
│                    NAT SCENARIOS                               │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  ┌─────────────┐         ┌─────────────┐                  │
│  │  Node       │         │  External   │                  │
│  │  192.168.1 │────────►│  Internet   │                  │
│  │  .100:30303│         │  IP: x.x.x.x│                  │
│  └─────────────┘         └─────────────┘                  │
│                                                              │
│  Issues:                                                    │
│  • Router may not support NAT traversal                    │
│  • UPnP may be disabled                                    │
│  • Carrier-grade NAT (CGNAT) blocks connections            │
│                                                              │
└─────────────────────────────────────────────────────────────┘

Solutions

1. Enable UPnP

# In geth, enable UPnP
geth --upnp.enabled

# Or disable NAT entirely if on proper network
geth --nat none

2. Use NAT Hole Punching

# Geth handles this automatically with discovery
# But ensure ports are properly forwarded

3. Cloud Deployment (Avoids NAT)

# Deploy in cloud with public IP
# AWS, GCP, Azure all provide public IPs
# Just ensure security groups allow traffic

---

48.7 Network Troubleshooting Commands

Comprehensive Diagnostics

network_diagnostics.sh

#!/bin/bash
echo "=== Network Diagnostics ==="

echo ""
echo "--- Network Interfaces ---"
ip addr show

echo ""
echo "--- Routing Table ---"
ip route

echo ""
echo "--- DNS Servers ---"
cat /etc/resolv.conf

echo ""
echo "--- Listening Ports ---"
ss -tulpn | grep -E "30303|8545"

echo ""
echo "--- Peer Count ---"
curl -s -X POST http://localhost:8545 \
    -H "Content-Type: application/json" \
    -d '{"jsonrpc":"2.0","method":"net_peerCount","params":[],"id":1}'

echo ""
echo "--- External Connectivity ---"
ping -c 3 8.8.8.8
ping -c 3 discovery.ethdisco.net

echo ""
echo "--- Firewall Status ---"
sudo ufw status 2>/dev/null || echo "UFW not installed"
sudo iptables -L -n 2>/dev/null | head -20

echo ""
echo "=== Diagnostics Complete ==="

---

48.8 Advanced Network Config

Static Peers

# Add static peers for guaranteed connection
# In config.toml:
[Node]
StaticNodes = [
    "enr:AAA@1.2.3.4:30303",
    "enr:BBB@5.6.7.8:30303"
]

# Or via admin API
geth attach http://localhost:8545
> admin.addPeer("enr:AAA@1.2.3.4:30303")

Custom Network Configuration

# Create private network
# genesis.json with custom network ID
{
  "config": {
    "chainId": 99999
  },
  "networkId": 99999
}

# Start with custom network
geth --networkid 99999 --bootnodes "enr:...@custom:30303"

---

48.9 Load Balancer Configuration

RPC Load Balancing

# Nginx load balancer for RPC
upstream geth_nodes {
    server 10.0.0.1:8545;
    server 10.0.0.2:8545;
    server 10.0.0.3:8545;
}

server {
    listen 8545;

    location / {
        proxy_pass http://geth_nodes;

        # Health check
        proxy_connect_timeout 5s;
        proxy_next_upstream error timeout http_502;

        # Headers
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

---

48.10 Monitoring Network Health

Prometheus Network Metrics

- alert: NoPeers
  expr: p2p_peers == 0
  for: 5m
  labels:
    severity: critical

- alert: LowPeerCount
  expr: p2p_peers < 10
  for: 15m
  labels:
    severity: warning

Grafana Dashboard

# Peer count over time
p2p_peers

# Network traffic
rate(p2p_bytes_in_total[5m])
rate(p2p_bytes_out_total[5m])

# Connection errors
rate(p2p_dial_connections_failed_total[5m])

---

Summary

• Peer count 0 usually indicates firewall or discovery issues
• Port forwarding required for home networks
• Bootnodes provide initial peer discovery
• NAT traversal can be problematic - cloud deployment avoids this
• DNS issues can prevent peer discovery
• Monitor peer count to catch problems early
• Static peers provide guaranteed connections
• Load balance RPC for high availability

---

Next Chapter

In Chapter 49: Debugging Tools, we’ll explore debugging techniques.

---

Last Updated: 2026-02-22