Development Environment Setup

Set up Pimeleon router for testing

Development Environment Setup

Set up Pimeleon router for development, testing, and experimentation. This guide focuses on rapid iteration, easy reconfiguration, and testing new features without risking production deployments.

Development Environment Goals

Typical dev/test requirements:

  • Fast iteration and experimentation
  • Easy rollback to known states
  • Testing new configurations safely
  • Multiple test environments
  • Documentation and learning
  • Breaking things without consequences

What this setup provides:

  • Isolated test network
  • Snapshot/restore capabilities
  • Parallel testing with production
  • Safe experimentation environment
  • Performance benchmarking tools

Basic Dev Setup ($100-130)

For: Personal learning, feature testing

  • Raspberry Pi 4 (4GB) ($55) - Extra RAM for development
  • SanDisk Ultra 32GB SD card ($10) - Fast enough for dev
  • Official 3A power supply ($8)
  • Low-profile cooler ($12)
  • Basic case ($8)
  • USB Ethernet adapter ($18) - Test dual interfaces
  • Spare SD card ($10) - Quick config swaps

Total cost: $121 Performance: Excellent for development work

Advanced Dev/Lab Setup ($180-220)

For: Professional development, lab environment

  • Raspberry Pi 4 (8GB) ($75) - Maximum headroom
  • Samsung PRO+ 64GB ($20) - Fast I/O
  • USB SD card reader ($10) - Quick SD swaps
  • Multiple SD cards (3x) ($30) - Different test configs
  • USB Ethernet adapters (2x) ($36) - Test complex topologies
  • USB hub ($15) - Connect multiple devices
  • HDMI switch ($10) - Easy console access

Total cost: $196

Development Network Topology

Setup:

Production Network (192.168.1.x)
    │
    └── Dev Pimeleon router (192.168.1.100)
        └── Test network (192.168.99.0/24)
            └── Test devices

Benefits:

  • Can't break production
  • Test network isolated
  • Easy to reset
  • Safe for experiments

Parallel Testing Setup

Setup:

Internet
    │
Modem/Router
    ├── Production Pimeleon (192.168.76.x)
    │   └── Production devices
    │
    └── Dev Pimeleon (192.168.99.x)
        └── Test devices

Benefits:

  • Compare configurations side-by-side
  • A/B testing
  • Performance comparisons
  • Migration validation

Quick Setup Guide

Phase 1: Base Installation (15 minutes)

  1. Flash SD card with Pimeleon image
  2. Boot and login:
    Username: pi
Password: raspberry
  3. Set dev hostname:
    sudo hostnamectl set-hostname pimeleon-dev
  4. Configure static IP (on test network):
    sudo nano /etc/dhcpcd.conf

interface eth0
static ip_address=192.168.99.1/24
nohook wpa_supplicant
  5. Enable SSH (if not already):
    sudo systemctl enable ssh
sudo systemctl start ssh

Phase 2: Development Tools (20 minutes)

Essential dev tools:

# Install development packages
sudo apt update
sudo apt install -y \
    git \
    vim \
    tmux \
    htop \
    iotop \
    nethogs \
    tcpdump \
    wireshark-cli \
    nmap \
    iperf3 \
    mtr \
    speedtest-cli \
    jq \
    python3-pip

# Install network analysis tools
sudo apt install -y \
    iftop \
    vnstat \
    bmon \
    nload

DNS filtering development mode:

# Disable DNS filter caching for testing
pihole -a -c off

# Or set very short TTL
sudo nano /etc/dnsmasq.d/01-pihole.conf
max-cache-ttl=60

Phase 3: Version Control Integration

Track configuration changes:

# Initialize git repo for configs
cd /etc
sudo git init
sudo git add pihole/ dhcp/ shorewall/ ssh/
sudo git commit -m "Initial config snapshot"

# Create branches for experiments
sudo git checkout -b experiment-blocklists

Automated config backups:

#!/bin/bash
# /usr/local/bin/backup-config.sh

BACKUP_DIR="/home/pi/config-backups"
DATE=$(date +%Y%m%d-%H%M)

mkdir -p $BACKUP_DIR

# Backup critical configs
sudo tar -czf $BACKUP_DIR/pimeleon-$DATE.tar.gz \
    /etc/pihole \
    /etc/dhcp \
    /etc/shorewall \
    /etc/ssh \
    /etc/hostapd \
    /etc/dhcpcd.conf

# Keep only last 10 backups
cd $BACKUP_DIR
ls -t | tail -n +11 | xargs rm -f

Development Workflows

Testing New Configurations

Workflow:

  1. Create config snapshot
  2. Make changes
  3. Test thoroughly
  4. If good: commit and document
  5. If bad: revert to snapshot

Example - Testing new blocklists:

# Snapshot current state
sudo git checkout -b test-aggressive-blocking
cd /etc/pihole
sudo git add .
sudo git commit -m "Before aggressive blocklist test"

# Add test blocklists
pihole -a adlist add "https://example.com/test-blocklist.txt"
pihole -g

# Test for 24 hours, monitor query log

# If successful:
sudo git add .
sudo git commit -m "Add aggressive blocklists - improved blocking by 15%"
sudo git checkout master
sudo git merge test-aggressive-blocking

# If failed:
sudo git checkout master
pihole -g  # Restore original lists

Performance Benchmarking

DNS query performance:

#!/bin/bash
# benchmark-dns.sh

DOMAIN="google.com"
ITERATIONS=100

echo "Benchmarking DNS queries..."
time for i in $(seq 1 $ITERATIONS); do
    nslookup $DOMAIN localhost > /dev/null 2>&1
done

# Compare with upstream
echo "Comparing with upstream DNS..."
time for i in $(seq 1 $ITERATIONS); do
    nslookup $DOMAIN 1.1.1.1 > /dev/null 2>&1
done

Throughput testing:

# Server mode (on test client)
iperf3 -s

# Client mode (from Pimeleon)
iperf3 -c 192.168.99.100 -t 60 -i 5

# Bidirectional test
iperf3 -c 192.168.99.100 --bidir

Latency testing:

# Continuous ping test
mtr -r -c 100 8.8.8.8 > latency-report.txt

# Analyze results
cat latency-report.txt | grep "Avg"

Testing Different Scenarios

Simulate network conditions:

# Add latency (simulate remote connection)
sudo tc qdisc add dev eth0 root netem delay 100ms

# Add packet loss (simulate poor connection)
sudo tc qdisc change dev eth0 root netem loss 5%

# Limit bandwidth (simulate slow connection)
sudo tc qdisc change dev eth0 root netem rate 1mbit

# Remove all simulations
sudo tc qdisc del dev eth0 root

Load testing:

#!/bin/bash
# load-test-dns.sh

# Generate lots of DNS queries
for i in $(seq 1 10); do
    (
        while true; do
            nslookup "random$RANDOM.com" localhost > /dev/null 2>&1
        done
    ) &
done

# Monitor with htop and iftop
# Kill with: killall nslookup

Multi-Configuration Management

Using Multiple SD Cards

Strategy:

  • SD Card 1: Stable baseline configuration
  • SD Card 2: Current experiment
  • SD Card 3: Alternative configuration test

Quick swap procedure:

  1. Shutdown Pimeleon: sudo shutdown -h now
  2. Swap SD card (takes 10 seconds)
  3. Power on
  4. Test new configuration
  5. Document results
  6. Swap back if needed

Label SD cards clearly:

  • Use permanent marker on card
  • Document configuration on label
  • Include date of last update

Configuration Profiles

Create profile scripts:

# /usr/local/bin/profiles/production.sh
#!/bin/bash
echo "Applying production configuration..."

# Copy production configs
sudo cp /home/pi/profiles/production/pihole/* /etc/pihole/
sudo cp /home/pi/profiles/production/dhcp/* /etc/dhcp/

# Restart services
pihole restartdns
sudo systemctl restart isc-dhcp-server

echo "Production profile applied"

Quick profile switching:

sudo /usr/local/bin/profiles/production.sh
# or
sudo /usr/local/bin/profiles/development.sh
# or
sudo /usr/local/bin/profiles/testing.sh

Development Best Practices

Documentation

Document everything you test:

# Create lab notebook
mkdir -p ~/lab-notebook
vim ~/lab-notebook/$(date +%Y-%m-%d)-experiment.md

Template:

# Experiment: Testing Aggressive Blocklists

Date: 2025-11-06
Duration: 24 hours

## Hypothesis

Adding more aggressive blocklists will improve ad-blocking without breaking legitimate sites.

## Configuration Changes

- Added 5 new blocklists
- Total domains blocked: 150,000 → 500,000

## Results

- Blocked queries: +25%
- False positives: 3 sites broken
- Performance impact: Minimal (< 2% CPU increase)

## Conclusion

Partially successful. Keep 3 of 5 new lists, remove 2 that caused false positives.

## Next Steps

- Fine-tune whitelists for broken sites
- Monitor for 1 week before production deployment

Safety Practices

Never test on production:

  • Always use isolated test network
  • Keep production configs backed up
  • Document all changes
  • Test thoroughly before deploying

Rollback plan:

# Before making changes
sudo cp -r /etc/pihole /etc/pihole.backup

# If things go wrong
sudo rm -rf /etc/pihole
sudo mv /etc/pihole.backup /etc/pihole
pihole restartdns

Regular checkpoints:

# Automated daily snapshots
sudo crontab -e

# Daily config backup at 2 AM
0 2 * * * /usr/local/bin/backup-config.sh

Advanced Development Topics

Custom DNS Filter Extensions

Testing custom blocklists:

# Create custom list
echo "ads.example.com" | sudo tee -a /etc/pihole/custom.list
pihole -g

Testing regex filters:

# Add regex to DNS filter database
sqlite3 /etc/pihole/gravity.db \
  "INSERT INTO regex (domain, enabled) VALUES ('(^|\\.)doubleclick\\.net$', 1);"

pihole restartdns

Integration Testing

Automated testing script:

#!/bin/bash
# test-pimeleon.sh

echo "Running Pimeleon integration tests..."

# Test 1: DNS resolution
if nslookup google.com localhost > /dev/null 2>&1; then
    echo "✓ DNS resolution working"
else
    echo "✗ DNS resolution failed"
    exit 1
fi

# Test 2: DNS blocking
if nslookup ads.example.com localhost | grep -q "0.0.0.0"; then
    echo "✓ DNS blocking working"
else
    echo "✗ DNS filtering not blocking ads"
    exit 1
fi

# Test 3: Internet connectivity
if ping -c 3 8.8.8.8 > /dev/null 2>&1; then
    echo "✓ Internet connectivity working"
else
    echo "✗ No internet connection"
    exit 1
fi

# Test 4: DHCP server
if systemctl is-active --quiet isc-dhcp-server; then
    echo "✓ DHCP server running"
else
    echo "✗ DHCP server not running"
    exit 1
fi

echo "All tests passed!"

Troubleshooting Development Setup

Issue: Forgot which configuration is active

Solution:

# Create status script
#!/bin/bash
echo "Current Configuration:"
echo "Hostname: $(hostname)"
echo "IP Address: $(hostname -I)"
echo "Blocklist domains: $(pihole -c -e | grep domains)"
git -C /etc/pihole log --oneline | head -5

Issue: Made breaking change, need to revert fast

Solution:

# Emergency revert script
#!/bin/bash
# /usr/local/bin/emergency-revert.sh

echo "EMERGENCY REVERT - Restoring last known good config"

# Stop services
sudo systemctl stop pihole-FTL isc-dhcp-server

# Restore from last backup
cd /home/pi/config-backups
LATEST=$(ls -t | head -1)
sudo tar -xzf $LATEST -C /

# Restart services
sudo systemctl start pihole-FTL isc-dhcp-server

echo "Revert complete. Check status with: pihole status"

Next Steps

After setting up development environment:

  1. Contribute to Documentation - Share your findings
  2. Join Community - Connect with other developers
  3. Advanced Configuration - Deep dive into architecture

Break things safely. Learn freely. Deploy confidently. Development environments let you experiment without consequences.

ON THIS PAGE
Development Environment Goals
Recommended Hardware
Development Network Topology
Quick Setup Guide
Development Workflows
Multi-Configuration Management
Development Best Practices
Advanced Development Topics
Troubleshooting Development Setup
Next Steps
Related Documentation