Fresh Installation Guide

Step-by-step guide to install Pimeleon router from pre-built image

Fresh Installation Guide

"The first 90% of the code accounts for the first 90% of the development time. The remaining 10% of the code accounts for the other 90% of the development time." — Tom Cargill (Variation of Murphy's Law)
Fortunately, with a pre-built image, you skip straight to the finish line.

This guide provides detailed, step-by-step instructions for installing Pimeleon router on a Raspberry Pi 3B+ or 4 using the official pre-built system image.

What You'll Need

Hardware

Raspberry Pi 3B+ or Pi 4 (Pi 4 recommended for best performance)
32GB microSD card (64GB recommended)
- Class 10 or UHS-I speed rating
- High-endurance cards preferred (SanDisk High Endurance, Samsung PRO Endurance)
Official power supply:
- Pi 3B+: 5V 2.5A micro-USB
- Pi 4: 5V 3A USB-C
Ethernet cable for WAN connection
Computer (Windows, macOS, or Linux) for flashing the image

Software

Image flashing tool:
- Raspberry Pi Imager (recommended, simplest)
- balenaEtcher (alternative, works on all platforms)
SD card reader (built-in or USB adapter)
Web browser for accessing the setup interface

Skills Required

Basic computer skills (downloading files, using applications)
No command-line experience necessary
No Linux knowledge required

Step 1: Download Pimeleon router image

Get the Latest Release

Visit the official release page:
- releases.pimeleon.com (recommended)
- Or GitHub releases: github.com/pimeleon/router/releases
Download the latest stable image:
- File name format: pimeleon-router-vX.Y.Z-rpiX.img.xz
- Example: pimeleon-router-v2.1.0-rpi4.img.xz
- Choose image matching your Raspberry Pi model (rpi3 or rpi4)
Verify download integrity (optional):
- Download the .sha256 checksum file
- Most browsers will verify integrity automatically
- Raspberry Pi Imager and balenaEtcher also verify checksums during flashing

Image Variants

Choose the appropriate image for your hardware:

Image	Hardware	Features
`rpi3.img.xz`	Raspberry Pi 3B+	Standard features, 100Mbps Ethernet
`rpi4.img.xz`	Raspberry Pi 4 (all models)	Full features, Gigabit Ethernet, best performance

Step 2: Flash Image to microSD Card

Using Raspberry Pi Imager (Recommended)

Raspberry Pi Imager provides the simplest and most reliable flashing experience.

Install Raspberry Pi Imager:
- Download from raspberrypi.com/software
- Install following standard procedure for your OS
Launch Raspberry Pi Imager
Select Device:
- Click "CHOOSE DEVICE"
- Select your Raspberry Pi model (Raspberry Pi 3 or Raspberry Pi 4)
Select Image:
- Click "CHOOSE OS"
- Scroll down and select "Use custom"
- Browse to downloaded .img.xz file
- Select the Pimeleon router image
Select Storage:
- Click "CHOOSE STORAGE"
- Select your microSD card
- WARNING: All data on this card will be erased!
Write Image:
- Click "NEXT"
- When prompted "Would you like to apply OS customisation settings?", select "NO"
- Confirm you want to erase the card
- Wait for writing and verification (10-20 minutes depending on card speed)
Eject Card:
- Once complete, safely eject the microSD card
- Remove from card reader

Using balenaEtcher (Alternative)

If you prefer balenaEtcher or Raspberry Pi Imager doesn't work:

Install balenaEtcher:
- Download from etcher.balena.io
- Install following standard procedure for your OS
Launch balenaEtcher
Select Image:
- Click "Flash from file"
- Browse to downloaded .img.xz file
- Select the Pimeleon router image
Select Target:
- Click "Select target"
- Choose your microSD card
- WARNING: Double-check you selected the correct drive!
Flash:
- Click "Flash!"
- Enter administrator password if prompted
- Wait for flashing and verification (10-20 minutes)
- Safely eject when complete

Troubleshooting Flash Issues

"Insufficient storage space" error:

Ensure microSD card is 32GB or larger
Try reformatting the card first (FAT32)

Flash fails or verification errors:

Try a different microSD card (some cards are defective)
Try a different USB card reader
Download the image again (may have been corrupted)

Image won't decompress:

Ensure you downloaded the complete file (check file size)
Most modern flash tools handle .xz files automatically
If needed, manually decompress first using 7-Zip (Windows) or xz command (Linux/macOS)

Step 3: First Boot

Physical Setup

Power Off: Ensure Raspberry Pi is completely powered off
Insert microSD Card:
- Insert flashed card into Pi with contacts facing up (toward board)
- Push firmly until it clicks into place
Connect Network:
- Connect Ethernet cable from your modem/router to Pi's Ethernet port
- This becomes the WAN (upstream) connection
Connect Power:
- Connect official power supply
- Red power LED should illuminate immediately
- Green activity LED should start blinking within 5-10 seconds

Boot Process

What to expect during first boot:

0-30 seconds: Red LED solid, green LED starts blinking
30-90 seconds: Green LED blinks rapidly (filesystem expansion and initial setup)
90-180 seconds: Green LED blinks intermittently (services starting)
After 2-3 minutes: System fully booted and ready

First boot takes longer than subsequent boots because the system:

Expands filesystem to use full SD card capacity
Generates unique SSH keys and security credentials
Initializes databases and configurations
Starts all network services

LED Diagnostic Guide

Red LED	Green LED	Status	Action
On	Blinking regularly	Normal boot in progress	Wait 2-3 minutes
On	Solid or blinking slowly	System booted	Proceed to setup
On	Off (no activity)	SD card issue	Check card insertion
Off	Off	No power	Check power supply

Step 4: Initial Access

Connecting to Pimeleon router

After the system boots (2-3 minutes), you can access it via WiFi or Ethernet.

Option A: Connect via WiFi (Easiest)

Find WiFi Network:
- On your computer or phone, scan for WiFi networks
- Look for SSID: pimeleon (or pimeleon-5G for 5GHz on Pi 4)
Connect:
- Select the pimeleon network
- Enter default password: pirouter
- Wait for connection (may take 10-20 seconds)
Open Web Interface:
- Open web browser
- Navigate to: http://pimeleon.local or http://192.168.76.1
- You should see the Pimeleon router setup wizard

Option B: Connect via Ethernet

Connect Cable:
- If you have a USB Ethernet adapter, connect it to a free USB port
- Connect Ethernet cable from adapter to your computer
- Or temporarily connect your computer to the WAN port
Obtain IP Address:
- Your computer should receive IP via DHCP: 192.168.76.x
- Check network settings to confirm
Open Web Interface:
- Open web browser
- Navigate to: http://192.168.76.1
- You should see the Pimeleon router setup wizard

Troubleshooting Access Issues

Can't find pimeleon WiFi network:

Wait full 3-4 minutes after power-on
Check green LED is blinking (system active)
Try rescanning WiFi networks
Check if 2.4GHz WiFi is enabled on your device (Pi 3B+ only has 2.4GHz)

WiFi network found but won't connect:

Verify password: pimeleonrouter (case-sensitive, no spaces)
Try forgetting network and reconnecting
Check that your WiFi adapter supports 2.4GHz

Can't access http://pimeleon.local:

Try direct IP: http://192.168.76.1
Check you're connected to pimeleon network (not your regular WiFi)
Try different browser or incognito mode
Clear browser cache
Check firewall isn't blocking connection

No response from web interface:

Verify device received IP address in 192.168.76.x range (check on your device's network settings)
Try accessing via IP address instead of hostname
Wait another minute (services may still be starting)
Check LED indicators (system should be fully booted - green LED blinking occasionally)

Step 5: Setup Wizard

Complete Initial Configuration

When you first access the web interface, the setup wizard guides you through essential configuration.

1. Welcome Screen

Review system information
Verify correct image version and hardware detected
Click "Begin Setup"

2. Create Admin Password

Username: admin (fixed, cannot be changed during setup)
Password: Create a strong password
- Minimum 8 characters
- Mix of uppercase, lowercase, numbers, symbols recommended
- Avoid common passwords
Confirm Password: Re-enter to verify
Click "Next"

Important: Store this password securely. You'll need it for all future administrative access.

3. Network Configuration

Choose your deployment mode:

Gateway Router Mode (Recommended):

Pimeleon router becomes your primary router
Handles DHCP, DNS, firewall, routing
Best for: Full control and all features

Transparent Proxy Mode:

Works alongside existing router
Provides filtering without changing your network
Best for: Adding features to existing setup

DNS/DHCP Only Mode:

Provides only DNS and DHCP services
Existing router handles everything else
Best for: Minimal integration, filtering only

Configure network settings:

WAN Interface: Auto-detected (usually eth0)
LAN Network: Default 192.168.76.0/24 (can customize)
Router IP: Default 192.168.76.1 (can customize)
DHCP Range: Default 192.168.76.100-192.168.76.250

Click "Next"

4. WiFi Configuration

Configure wireless access point:

SSID: Default pimeleon (customize to your preference)
Password: Default pimeleonrouter (change to secure password)
Channel: Auto (or select specific channel if interference present)
5GHz: Enable if supported (Pi 4 only)

Security Note: Change the default WiFi password to something unique and strong.

Click "Next"

5. Upstream DNS

Select DNS resolver(s):

Recommended Options:

Cloudflare: 1.1.1.1 - Privacy-focused, fast
Quad9: 9.9.9.9 - Security-focused, blocks malicious domains
Google: 8.8.8.8 - Reliable, fast
Custom: Enter your preferred DNS servers

Best Practice: Select two different providers for redundancy.

Click "Next"

6. Ad Blocking & Filtering

Configure DNS filtering:

Enable DNS filtering: Recommended (checked by default)
Blocklist Presets:
- Light: Basic ad blocking (~100K domains)
- Standard: Balanced blocking (~300K domains) - Recommended
- Aggressive: Maximum blocking (~1M domains)
- Custom: Choose specific blocklists

Note: You can modify blocklists later via admin interface.

Click "Next"

7. Time Zone & Locale

Configure regional settings:

Time Zone: Select your geographic time zone
NTP Servers: Auto-configured (usually no changes needed)
Locale: Select language/region (default: en_US)

Click "Next"

8. Review & Apply

Review all settings
Confirm configuration is correct
Click "Apply Configuration"

Wait 30-60 seconds while system applies settings and restarts services.

9. Setup Complete

You'll see confirmation screen
System may reboot (wait 1-2 minutes if it does)
You'll be redirected to login page

Login with:

Username: admin
Password: (the password you created in Step 2)

Step 6: Verification & Testing

Verify Installation Success

After logging in, confirm everything is working:

1. Dashboard Check

System Status: Should show "Operational" with green indicator
Services: All services should show "Running" status
Network: WAN should show "Connected" with valid IP

2. Internet Connectivity Test

From a device connected to Pimeleon router:

Basic connectivity:
- Open browser and visit several different websites
- Sites should load normally
- HTTPS sites should show secure padlock icon
DNS resolution:
- Check web dashboard Query Log
- Should see DNS queries appearing in real-time
- Queries should show successful resolution (not blocked)
Web browsing:
- Test various sites (news, social media, video streaming)
- All should load properly
- Page load times should be fast

3. Ad Blocking Test

Test that DNS filtering is working:

Visit: http://pi.hole/admin (alternative access method)
Navigate to Dashboard
Check "Queries blocked" percentage
Visit a known ad-heavy website (news sites, etc.)
Verify ads are blocked

4. Performance Check

Speed test: Visit speedtest.net or fast.com from client device
- Should be close to your ISP's advertised speed
- Raspberry Pi 3B+ maxes at ~100Mbps
- Raspberry Pi 4 can handle Gigabit speeds
System health: Check web dashboard System section
- Temperature should be reasonable (< 70°C / 158°F)
- Load average should be low (< 1.0)
- Memory should have free space available

Troubleshooting Common Issues

Internet not working after setup:

Check WAN cable is connected to correct port
Verify upstream router/modem is providing DHCP
Check DNS servers are reachable
Try rebooting both Pimeleon router and upstream device

Slow performance:

Use Gigabit Ethernet cables (Cat5e or Cat6)
Ensure adequate power supply (check red LED stays solid)
Verify Raspberry Pi isn't overheating (add heatsinks/cooling)
Check network cable quality

Some devices can't connect:

Verify DHCP pool has enough addresses
Check for IP conflicts
Review firewall rules if you customized them
Try forgetting WiFi network and reconnecting

DNS filtering not blocking ads:

Verify devices are using Pimeleon router as DNS server
Check blocklists are enabled and updated
Allow 5-10 minutes for DNS cache to clear on client devices
Try clearing browser cache

Step 7: Post-Installation Tasks

Essential Next Steps

After successful installation and verification:

1. Create Configuration Backup

Via Web Interface:

Navigate to: Settings → Backup & Restore
Click "Create Backup"
Download backup file to safe location
Store securely (contains sensitive configuration)

Why: Allows quick recovery if configuration becomes corrupted or you need to restore settings.

2. Update System (if available)

Check for updates:

Navigate to: System → Updates
If updates available, review changelog
Click "Install Updates"
Wait for completion (may take 5-10 minutes)
System will reboot automatically

3. Configure Additional Features

Explore optional features based on your needs:

DHCP Static Leases: Assign fixed IPs to specific devices
Port Forwarding: Expose services to internet (if needed)
VPN Server: Set up remote access (OpenVPN recommended for RPi 3B+, WireGuard recommended for RPi 4)
Advanced DNS: Custom DNS records, conditional forwarding
QoS: Quality of Service for bandwidth management

4. Secure Your Installation

Security checklist:

Changed default admin password to strong password
Changed WiFi password from default
Disabled SSH if not needed (Settings → SSH Access)
Enabled automatic security updates (Settings → Updates → Auto-update)
Reviewed and understood firewall rules
Configured fail2ban for brute-force protection (enabled by default)

5. Monitor System Health

Set up monitoring:

Review Dashboard regularly for anomalies
Check System Logs for errors or warnings
Monitor resource usage (CPU, memory, temperature)
Set up email alerts for critical events (optional)

Recommended Configurations

For Home Users

DHCP: Enable with reasonable lease time (24 hours)
DNS: Use Cloudflare (1.1.1.1) or Quad9 (9.9.9.9)
Firewall: Default settings (restrictive inbound, permissive outbound)
Standard blocklist preset
WiFi: Separate 2.4GHz and 5GHz SSIDs (Pi 4 only)

For Power Users

Custom DNS: Set up local domain (e.g., .home)
VPN Server: Enable VPN for secure remote access (OpenVPN for RPi 3B+ for better compatibility, WireGuard for RPi 4 for optimal performance)
Advanced Filtering: Add custom blocklists or whitelist specific domains
QoS: Prioritize video calls, gaming, or streaming
Monitoring: Enable Grafana dashboards for detailed metrics