Network Integration Guide

Add Pimeleon router to your existing network

Network Integration Guide

Integrating Pimeleon router into your existing network requires understanding your network topology and choosing the right deployment mode. This guide walks you through different integration strategies, from simple plug-and-play setups to advanced configurations.

"Any wire cut to length will be too short." - Murphy's Law of Cable Management (Arthur Bloch)

Quick Integration Summary

Deployment Mode	Complexity	Best For	Setup Time
DNS/DHCP Server	Easy	Quick start, minimal changes	10 minutes
Gateway Behind Router	Easy	Home networks, existing router	20 minutes
Primary Gateway	Medium	Full control, all features	30-60 minutes
Bridge Mode	Advanced	Transparent filtering	45-90 minutes

Understanding Network Modes

Mode 1: DNS Server Only

What it does: Pimeleon acts as DNS server and DHCP server for your network, while your existing router handles internet gateway functions.

Diagram:

Internet
    │
Existing router (192.168.1.1)
    │
    ├── Pimeleon router (192.168.1.10)
    │   └── DNS: 192.168.1.10
    │   └── DHCP: 192.168.1.100-200
    │

    └── Your Devices

Pros:

Easiest to set up
Keep existing router
DNS filtering and ad-blocking
DHCP management
Minimal network changes

Cons:

No gateway-level filtering
No traffic routing through Pimeleon
Limited network visibility
Can't use all features

When to use:

Testing Pimeleon before full deployment
Existing router has features you need
Want ad-blocking only
Temporary setup

Mode 2: Secondary Gateway

What it does: Pimeleon acts as a secondary router behind your main router, creating a filtered subnet.

Diagram:

Internet
    │
Main router (192.168.1.1)
    │
    └── Pimeleon router WAN (192.168.1.10)
        └── Pimeleon router LAN (192.168.76.1/24)
            └── Filtered devices

Pros:

Full Pimeleon features
Keep main router
Easy to revert
Separate filtered network
Good for mixed environments

Cons:

Double NAT (may affect some services)
Separate network segment
More complex troubleshooting
Potential performance impact

When to use:

Want full filtering for specific devices
Testing before replacing main router
Mixed environment (some devices need direct internet)
Apartment or shared network

Mode 3: Primary Gateway

What it does: Pimeleon replaces your existing router as the primary internet gateway.

Diagram:

Internet
    │
Modem (bridge mode)
    │
Pimeleon router (WAN + LAN)
    │
    ├── Wired LAN (192.168.76.0/24)
    └── WiFi AP (192.168.77.0/24)

Pros:

Full control over network
All features available
Single NAT layer
Best performance
Complete visibility

Cons:

Requires modem in bridge mode
More complex setup
Single point of failure
Need backup router

When to use:

Maximum control desired
Office or professional deployment
Full feature set needed
Dedicated routing hardware

Mode 4: Transparent Bridge

What it does: Pimeleon sits between your modem and router, filtering traffic transparently.

Diagram:

Internet
    │
Modem
    │
Pimeleon router (bridge mode)
    │
Your existing router
    │
Your devices

Pros:

Transparent to devices
No IP changes needed
Can use existing router
Advanced filtering

Cons:

Most complex setup
Advanced networking knowledge required
Harder to troubleshoot
Performance overhead

When to use:

Advanced users only
Need transparent filtering
Complex existing network
Can't change existing setup

Mode 1: DNS Server Setup

Prerequisites

Pimeleon router installed and booted
Connected to existing network
SSH access to Pimeleon

Step-by-Step Setup

1. Configure Pimeleon Static IP

# SSH into Pimeleon

ssh pi@pimeleon-router.local

# Edit network configuration
sudo nano /etc/dhcpcd.conf


# Add static IP configuration
interface eth0
static ip_address=192.168.1.10/24
static routers=192.168.1.1
static domain_name_servers=1.1.1.1 8.8.8.8

# Restart networking
sudo systemctl restart dhcpcd

2. Configure DHCP Server

# Edit DHCP configuration
sudo nano /etc/dhcp/dhcpd.conf


# Configure DHCP range
subnet 192.168.1.0 netmask 255.255.255.0 {
  range 192.168.1.100 192.168.1.200;
  option routers 192.168.1.1;
  option domain-name-servers 192.168.1.10;
}

# Restart DHCP
sudo systemctl restart isc-dhcp-server

3. Disable DHCP on Existing Router

Log into your existing router and disable its DHCP server. Configuration varies by router manufacturer.

4. Verify DNS Resolution

# From another device on network
nslookup google.com 192.168.1.10

# Should see Pimeleon responding

Troubleshooting DNS Mode

Devices not getting IPs:

Check DHCP server status: sudo systemctl status isc-dhcp-server
Verify DHCP range doesn't conflict
Check firewall allows DHCP (ports 67-68)

DNS not resolving:

Verify DNS filtering is running: check admin interface
Check DNS port 53 is open
Test with dig @192.168.1.10 google.com

Mode 2: Secondary Gateway Setup

Prerequisites

Pimeleon router with two network interfaces (built-in + USB adapter)
Existing router configured
Internet connection working

Step-by-Step Setup

1. Connect Hardware

Main router (192.168.1.1)
    │
    └── Pimeleon eth0 (WAN)
        └── Pimeleon eth1/wlan0 (LAN)
            └── Filtered devices

2. Configure WAN Interface

# SSH into Pimeleon
ssh pi@pimeleon-router.local


# Configure WAN to get IP from main router
sudo nano /etc/dhcpcd.conf

# WAN interface (eth0)

interface eth0
# DHCP from main router (or static)
static ip_address=192.168.1.10/24
static routers=192.168.1.1
static domain_name_servers=1.1.1.1

3. Configure LAN Interface

# LAN interface (eth1)
interface eth1
static ip_address=192.168.76.1/24

nohook wpa_supplicant

4. Enable IP Forwarding

# Enable forwarding
sudo nano /etc/sysctl.conf

# Uncomment or add
net.ipv4.ip_forward=1

# Apply changes
sudo sysctl -p

5. Configure NAT

# Setup NAT rules with nftables
sudo nft add rule ip nat postrouting oifname "eth0" masquerade
sudo nft add rule ip filter forward iifname "eth1" oifname "eth0" accept
sudo nft add rule ip filter forward iifname "eth0" oifname "eth1" ct state related,established accept

# Rules are automatically persistent in /etc/nftables.conf

6. Configure DHCP for LAN

sudo nano /etc/dhcp/dhcpd.conf

subnet 192.168.76.0 netmask 255.255.255.0 {
  range 192.168.76.100 192.168.76.200;
  option routers 192.168.76.1;

  option domain-name-servers 192.168.76.1;
}

sudo systemctl restart isc-dhcp-server

Testing Secondary Gateway

# From device on Pimeleon LAN (192.168.76.x)
ping 8.8.8.8          # Test internet
ping 192.168.1.1      # Test main router
traceroute google.com  # Should show Pimeleon as first hop

Troubleshooting Secondary Gateway

Double NAT issues:

Some games/services may not work
Enable UPnP on both routers
Or use port forwarding through both layers

Can't reach main network:

Add route to main network if needed
May need to configure firewall rules

Mode 3: Primary Gateway Setup

Prerequisites

Modem in bridge mode (or direct fiber connection)
Pimeleon router with network interfaces configured
Backup of existing router config (in case of rollback)

Internet
    │
Modem (bridge mode)
    │
Pimeleon eth0 (WAN)
    │
    ├── Pimeleon eth1 (Wired LAN)
    └── Pimeleon wlan0 (WiFi AP)

3. Configure WAN Interface

# For DHCP from ISP
sudo nano /etc/dhcpcd.conf

interface eth0
# Most ISPs use DHCP

# Configuration will be automatic

# For static IP from ISP
interface eth0
static ip_address=<ISP_PROVIDED_IP>/24
static routers=<ISP_GATEWAY>

static domain_name_servers=1.1.1.1 8.8.8.8

4. Configure LAN Interfaces

# Wired LAN
interface eth1
static ip_address=192.168.76.1/24

# WiFi AP
interface wlan0
static ip_address=192.168.77.1/24
nohook wpa_supplicant

5. Configure Firewall (Shorewall)

Shorewall should be pre-configured in Pimeleon router. Verify:

# Check Shorewall status
sudo shorewall status

# Verify zones

cat /etc/shorewall/zones
# Should show: wan, lan, wifi zones

6. Configure WiFi Access Point

# Configure hostapd for WiFi AP
sudo nano /etc/hostapd/hostapd.conf



interface=wlan0
driver=nl80211
ssid=Pimeleon-WiFi
hw_mode=g
channel=6

wpa=2
wpa_passphrase=<YOUR_SECURE_PASSWORD>
wpa_key_mgmt=WPA-PSK
wpa_pairwise=CCMP


# Enable and start
sudo systemctl enable hostapd
sudo systemctl start hostapd

7. Verify Internet Connection

# Test from Pimeleon


ping -I eth0 8.8.8.8

# Test DNS
nslookup google.com

# Check routing

ip route show

Testing Primary Gateway

Connect device to Pimeleon LAN or WiFi
Device should get IP via DHCP
Test internet connectivity
Verify DNS filtering is working
Check all services are accessible

Troubleshooting Primary Gateway

No internet on WAN:

Check modem is in bridge mode
Verify ISP credentials (if PPPoE)
Check cable connections
Reboot modem and Pimeleon

Devices can't connect:

Check DHCP server is running
Verify firewall allows LAN to WAN
Check DNS is resolving

WiFi not working:

Check hostapd status: sudo systemctl status hostapd
Verify wlan0 is up: ip addr show wlan0
Check country code in hostapd.conf

Network Topology Considerations

IP Addressing Schemes

Default Pimeleon Networks:

WAN: DHCP from ISP or upstream router
Wired LAN: 192.168.76.0/24 (gateway: 192.168.76.1)
WiFi: 192.168.77.0/24 (gateway: 192.168.77.1)

Customizing IP Ranges:

# Edit network configuration
sudo nano /etc/dhcpcd.conf

# Change LAN subnet
interface eth1
static ip_address=10.0.10.1/24

# Update DHCP configuration
sudo nano /etc/dhcp/dhcpd.conf

subnet 10.0.10.0 netmask 255.255.255.0 {
  range 10.0.10.100 10.0.10.200;
  option routers 10.0.10.1;
  option domain-name-servers 10.0.10.1;
}

DNS Configuration

Upstream DNS Servers:

Pimeleon uses DNS filtering with Bind9 for DNS resolution. Configure upstream servers:

# Edit DNS settings via admin interface
sudo nano /etc/pihole/setupVars.conf

# Set upstream DNS
PIHOLE_DNS_1=1.1.1.1
PIHOLE_DNS_2=8.8.8.8

# Or use DNS over HTTPS
PIHOLE_DNS_1=https://cloudflare-dns.com/dns-query

Local DNS Records:

# Add local DNS records
sudo nano /etc/hosts

192.168.76.10  server.local
192.168.76.20  nas.local
192.168.76.30  printer.local

# Or use local DNS
# Admin interface > Local DNS > DNS Records

DHCP Reservations

Reserve IPs for specific devices:

sudo nano /etc/dhcp/dhcpd.conf

# Add host reservations
host server {
  hardware ethernet aa:bb:cc:dd:ee:ff;
  fixed-address 192.168.76.10;
}

host printer {
  hardware ethernet 11:22:33:44:55:66;
  fixed-address 192.168.76.20;
}

sudo systemctl restart isc-dhcp-server

Advanced Integration Scenarios

VLAN Configuration

For advanced network segmentation:

# Install VLAN support
sudo apt install vlan

# Load 8021q module
sudo modprobe 8021q

# Create VLAN interface
sudo vconfig add eth1 10

# Configure VLAN
sudo ifconfig eth1.10 192.168.10.1 netmask 255.255.255.0 up

IPv6 Support

Enable IPv6 if your ISP supports it:

# Enable IPv6 forwarding

sudo nano /etc/sysctl.conf

net.ipv6.conf.all.forwarding=1

# Configure dhcpcd for IPv6
sudo nano /etc/dhcpcd.conf

interface eth0
iaid 1

# Enable IPv6 via SLAAC
ia_na 1
ia_pd 1/::/64 eth1/0/64

VPN Integration

Configure Pimeleon to route through VPN:

# Install OpenVPN
sudo apt install openvpn

# Copy VPN config
sudo cp your-vpn.ovpn /etc/openvpn/client.conf


# Enable and start
sudo systemctl enable openvpn@client

sudo systemctl start openvpn@client

# Route traffic through VPN
sudo nano /etc/shorewall/rules
# Add VPN routing rules

Migration from Existing Router

Pre-Migration Checklist

Document current network configuration
List all port forwards and firewall rules
Note all DHCP reservations
Backup router configuration
Test Pimeleon in secondary mode first
Plan migration window (evening/weekend)

Migration Steps

Parallel Testing (1-2 weeks)
- Run Pimeleon in secondary gateway mode
- Test all services and devices
- Verify performance meets needs
- Document any issues
Configuration Migration
- Recreate port forwards on Pimeleon
- Configure DHCP reservations
- Set up DNS records
- Configure firewall rules
Cutover Plan
- Schedule maintenance window
- Notify users of downtime
- Keep old router accessible
- Have rollback plan ready
Cutover Execution
- Put modem in bridge mode
- Connect Pimeleon as primary gateway
- Power on and verify WAN connection
- Test internal connectivity
- Verify all services working
Post-Cutover
- Monitor for 24-48 hours
- Address any issues
- Update documentation
- Keep old router as backup

Rollback Procedure

If issues arise:

Power off Pimeleon
Reconfigure modem to router mode (or connect old router)
Power on old router
Verify connectivity restored
Troubleshoot Pimeleon offline
Retry migration when ready

Common Integration Issues

Issue: Double NAT

Symptoms: Some services don't work, gaming issues, VPN problems

Solutions:

Put main router in bridge mode
Enable UPnP on both routers
Use Pimeleon as primary gateway instead

Issue: DNS Not Working

Symptoms: Can ping IPs but not domain names

Solutions:

# Verify DNS filtering is running
pihole status

# Check DNS port
sudo netstat -tulpn | grep :53

# Test DNS resolution
dig @127.0.0.1 google.com

# Restart DNS services
pihole restartdns

Issue: No Internet Access

Symptoms: Connected to network but no internet

Solutions:

# Check WAN interface
ip addr show eth0

# Verify routing
ip route show

# Test gateway
ping -I eth0 8.8.8.8

# Check NAT is working
sudo nft list table ip nat

Issue: WiFi Not Broadcasting

Symptoms: Can't see WiFi network

Solutions:

# Check hostapd status
sudo systemctl status hostapd

# Verify wlan0 configuration
ip addr show wlan0

# Check hostapd config
sudo hostapd -dd /etc/hostapd/hostapd.conf

# Restart WiFi
sudo systemctl restart hostapd

Performance Optimization

Network Tuning

# Optimize network stack
sudo nano /etc/sysctl.conf

# Increase network buffers
net.core.rmem_max = 16777216
net.core.wmem_max = 16777216
net.ipv4.tcp_rmem = 4096 87380 16777216
net.ipv4.tcp_wmem = 4096 65536 16777216

# Enable TCP fast open
net.ipv4.tcp_fastopen = 3

# Apply changes
sudo sysctl -p

DNS Caching

DNS filter handles caching, but you can optimize:

# Increase DNS cache size
sudo nano /etc/dnsmasq.d/01-pihole.conf

cache-size=10000

# Restart DNS
pihole restartdns

Next Steps

After successful network integration:

Configure DNS filtering - Set up ad-blocking
Secure your router - Harden configuration

Physical Setup - Hardware connection guide
Deployment Scenarios - Specific use cases
Network Architecture - Technical details
Troubleshooting - Fix common issues