pic/docs/NETWORK_CONFIGURATION.md

Personal Internet Cell - Network Configuration Guide

This guide explains how to configure networking for the Personal Internet Cell to provide internet access to WireGuard VPN clients.

Table of Contents

1. Overview
2. Network Architecture
3. Quick Setup
4. Detailed Configuration
5. Troubleshooting
6. Advanced Configuration
7. Security Considerations

Overview

The Personal Internet Cell provides a complete VPN solution with internet access. This requires proper configuration of:

• IP Forwarding: Allow traffic to pass through the server
• NAT (Network Address Translation): Translate private IPs to public IPs
• Routing: Direct traffic from VPN clients to the internet
• Firewall Rules: Control traffic flow and security

Network Architecture

Internet
    │
    ▼
[Host Server] (195.178.106.244)
    │
    ├── [Docker Network] (172.20.0.0/16)
    │   └── [WireGuard Container] (cell-wireguard)
    │       └── [WireGuard Interface] (wg0: 10.0.0.1/24)
    │
    └── [VPN Clients] (10.0.0.2-10.0.0.254/24)
        └── [Internet Access via NAT]

Key Components

• Host Interface: eth0 (or main network interface)
• WireGuard Interface: wg0 (10.0.0.1/24)
• Client Network: 10.0.0.0/24
• NAT Translation: Client IPs → Host IP

Quick Setup

1. Run the Network Configuration Script

# Make the script executable (if not already done)
chmod +x /opt/pic/scripts/setup-network.sh

# Run the configuration
sudo /opt/pic/scripts/setup-network.sh setup

2. Verify Configuration

# Check status
sudo /opt/pic/scripts/setup-network.sh status

# Test configuration
sudo /opt/pic/scripts/setup-network.sh test

3. Connect a VPN Client

Use the generated WireGuard configuration to connect a client. The client should now have internet access.

Detailed Configuration

IP Forwarding

IP forwarding allows the server to route packets between different network interfaces.

Enable on Host:

echo 'net.ipv4.ip_forward = 1' >> /etc/sysctl.conf
sysctl -p

Enable in Container:

docker exec cell-wireguard sh -c "echo 1 > /proc/sys/net/ipv4/ip_forward"

NAT Configuration

NAT (Network Address Translation) allows VPN clients to access the internet using the server's public IP.

Container NAT Rules:

# Allow forwarding for WireGuard traffic
iptables -A FORWARD -i wg0 -j ACCEPT
iptables -A FORWARD -o wg0 -j ACCEPT

# NAT rule for internet access
iptables -t nat -A POSTROUTING -s 10.0.0.0/24 -o eth0 -j MASQUERADE

Host NAT Rules:

# Allow traffic from WireGuard network
iptables -t nat -A POSTROUTING -s 10.0.0.0/24 -o eth0 -j MASQUERADE
iptables -A FORWARD -i wg0 -j ACCEPT
iptables -A FORWARD -o wg0 -j ACCEPT

Routing Configuration

WireGuard Interface Setup:

# Create WireGuard interface
ip link add dev wg0 type wireguard

# Set private key
wg set wg0 private-key /path/to/private-key

# Set listen port
wg set wg0 listen-port 51820

# Add IP address
ip addr add 10.0.0.1/24 dev wg0

# Bring interface up
ip link set wg0 up

# Add peers
wg set wg0 peer <public-key> allowed-ips 10.0.0.2/32

Troubleshooting

Common Issues

1. VPN Connected but No Internet

Symptoms:

• WireGuard shows connected
• Can ping server (10.0.0.1)
• Cannot access internet

Solutions:

# Check IP forwarding
cat /proc/sys/net/ipv4/ip_forward
# Should return 1

# Check NAT rules
iptables -t nat -L POSTROUTING -n
# Should show MASQUERADE rule for 10.0.0.0/24

# Check forwarding rules
iptables -L FORWARD -n
# Should show ACCEPT rules for wg0

# Restart network configuration
sudo /opt/pic/scripts/setup-network.sh reset
sudo /opt/pic/scripts/setup-network.sh setup

2. Cannot Connect to VPN

Symptoms:

• WireGuard client cannot connect
• No handshake in server logs

Solutions:

# Check WireGuard interface
docker exec cell-wireguard wg show

# Check if port 51820 is open
netstat -ulnp | grep 51820

# Check firewall rules
ufw status
iptables -L INPUT -n

# Check Docker port mapping
docker port cell-wireguard

3. DNS Issues

Symptoms:

• Can ping IP addresses
• Cannot resolve domain names

Solutions:

# Check DNS configuration in client config
# Should include: DNS = 8.8.8.8, 1.1.1.1

# Test DNS from container
docker exec cell-wireguard nslookup google.com

# Check if DNS is being blocked
docker exec cell-wireguard iptables -L -n | grep 53

Diagnostic Commands

# Check network status
sudo /opt/pic/scripts/setup-network.sh status

# Test connectivity from container
docker exec cell-wireguard ping -c 3 8.8.8.8

# Check routing table
docker exec cell-wireguard ip route show

# Check interface status
docker exec cell-wireguard ip addr show wg0

# Check NAT rules
docker exec cell-wireguard iptables -t nat -L -n

# Check forwarding rules
docker exec cell-wireguard iptables -L FORWARD -n

Advanced Configuration

Custom DNS Servers

To use custom DNS servers, modify the WireGuard client configuration:

[Interface]
PrivateKey = <private-key>
Address = 10.0.0.2/32
DNS = 1.1.1.1, 1.0.0.1, 8.8.8.8, 8.8.4.4

[Peer]
PublicKey = <server-public-key>
Endpoint = 195.178.106.244:51820
AllowedIPs = 0.0.0.0/0
PersistentKeepalive = 25

Split Tunneling

To allow only specific traffic through the VPN:

[Peer]
AllowedIPs = 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16
# Only route private networks through VPN

Port Forwarding

To forward specific ports to VPN clients:

# Forward port 8080 to client 10.0.0.2
iptables -t nat -A PREROUTING -p tcp --dport 8080 -j DNAT --to-destination 10.0.0.2:8080
iptables -A FORWARD -p tcp -d 10.0.0.2 --dport 8080 -j ACCEPT

Bandwidth Limiting

To limit bandwidth for VPN clients:

# Install tc (traffic control)
apt-get install iproute2

# Limit client 10.0.0.2 to 1Mbps
tc qdisc add dev wg0 root handle 1: htb default 30
tc class add dev wg0 parent 1: classid 1:1 htb rate 1mbit
tc class add dev wg0 parent 1:1 classid 1:10 htb rate 1mbit ceil 1mbit
tc filter add dev wg0 protocol ip parent 1:0 prio 1 u32 match ip dst 10.0.0.2 flowid 1:10

Security Considerations

Firewall Rules

Basic Security Rules:

# Drop invalid packets
iptables -A INPUT -m conntrack --ctstate INVALID -j DROP

# Allow established connections
iptables -A INPUT -m conntrack --ctstate ESTABLISHED,RELATED -j ACCEPT

# Allow WireGuard traffic
iptables -A INPUT -p udp --dport 51820 -j ACCEPT

# Allow SSH (if needed)
iptables -A INPUT -p tcp --dport 22 -j ACCEPT

# Drop everything else
iptables -A INPUT -j DROP

Client Isolation

To prevent clients from communicating with each other:

# Block inter-client communication
iptables -A FORWARD -i wg0 -o wg0 -j DROP

Logging

To log VPN traffic:

# Log all WireGuard traffic
iptables -A FORWARD -i wg0 -j LOG --log-prefix "WG-FORWARD: "
iptables -A FORWARD -o wg0 -j LOG --log-prefix "WG-FORWARD: "

# Log NAT traffic
iptables -t nat -A POSTROUTING -s 10.0.0.0/24 -j LOG --log-prefix "WG-NAT: "

Monitoring

Real-time Monitoring

# Monitor WireGuard connections
watch -n 1 "docker exec cell-wireguard wg show"

# Monitor traffic
watch -n 1 "docker exec cell-wireguard wg show wg0 transfer"

# Monitor NAT rules
watch -n 1 "iptables -t nat -L POSTROUTING -n -v"

Log Analysis

# Check system logs
journalctl -u pic-network.service -f

# Check iptables logs
tail -f /var/log/kern.log | grep WG-

# Check Docker logs
docker logs cell-wireguard -f

Backup and Recovery

Backup Configuration

# Backup iptables rules
iptables-save > /opt/pic/backups/iptables-backup-$(date +%Y%m%d).rules

# Backup WireGuard configuration
cp /opt/pic/config/wireguard/wg_confs/wg0.conf /opt/pic/backups/wg0-backup-$(date +%Y%m%d).conf

# Backup network script
cp /opt/pic/scripts/setup-network.sh /opt/pic/backups/setup-network-backup-$(date +%Y%m%d).sh

Restore Configuration

# Restore iptables rules
iptables-restore < /opt/pic/backups/iptables-backup-YYYYMMDD.rules

# Restore WireGuard configuration
cp /opt/pic/backups/wg0-backup-YYYYMMDD.conf /opt/pic/config/wireguard/wg_confs/wg0.conf
docker restart cell-wireguard

Support

If you encounter issues:

1. Check the troubleshooting section above
2. Run the diagnostic commands
3. Check the logs for error messages
4. Verify your network configuration
5. Test with a simple client configuration

For additional help, check the main Personal Internet Cell documentation or create an issue in the project repository.