wip: wireguard

2025-09-14 03:31:14 -05:00
parent 5bd7443681
commit bb6ccfe023
8 changed files with 1468 additions and 91 deletions
@@ -0,0 +1,389 @@
+# 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](#overview)
+2. [Network Architecture](#network-architecture)
+3. [Quick Setup](#quick-setup)
+4. [Detailed Configuration](#detailed-configuration)
+5. [Troubleshooting](#troubleshooting)
+6. [Advanced Configuration](#advanced-configuration)
+7. [Security Considerations](#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
+
+```bash
+# 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
+
+```bash
+# 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:**
+```bash
+echo 'net.ipv4.ip_forward = 1' >> /etc/sysctl.conf
+sysctl -p
+```
+
+**Enable in Container:**
+```bash
+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:**
+```bash
+# 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:**
+```bash
+# 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:**
+```bash
+# 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:**
+```bash
+# 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:**
+```bash
+# 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:**
+```bash
+# 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
+
+```bash
+# 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:
+
+```ini
+[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:
+
+```ini
+[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:
+
+```bash
+# 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:
+
+```bash
+# 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:**
+```bash
+# 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:
+
+```bash
+# Block inter-client communication
+iptables -A FORWARD -i wg0 -o wg0 -j DROP
+```
+
+### Logging
+
+To log VPN traffic:
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+# 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.