Quick Setup Guide

Get Pimeleon up and running in 30 minutes - from hardware to working network

Quick Setup Guide

Get from "I have a Raspberry Pi" to "My router works" in under 30 minutes. This streamlined guide focuses on the essentials to get you operational quickly.

Murphy's Law of Computer Programming: "The first place to look for information is in the section of the manual where you'd least expect to find it." - Arthur Bloch

That's why this guide puts everything in one place.

Overview

Total Time: 25-30 minutes

What You'll Do:

  1. Gather hardware (5 min)
  2. Flash Pimeleon to SD card (10 min)
  3. Connect and boot (5 min)
  4. Verify it works (5 min)
  5. Connect your network (5 min)

Prerequisites

Required Hardware

Before you start, make sure you have:

  • Raspberry Pi 3B+ or 4 - Pi 4 recommended for best performance
  • MicroSD card - 32GB minimum, Class 10 or better
  • Power supply - Official Raspberry Pi adapter recommended
    • Pi 4: 5V/3A USB-C
    • Pi 3B+: 5V/2.5A Micro USB
  • Ethernet cable - Cat5e or better
  • Computer - For flashing the SD card
  • USB Ethernet adapter - For dual WAN/LAN setup
  • Heatsink or fan - For thermal management
  • Case - For physical protection
  • HDMI cable - For troubleshooting (Micro HDMI for Pi 4)

Not sure what hardware to buy? See our Hardware Guide for detailed recommendations.

Step 1: Gather Your Hardware

Time: 5 minutes

Lay out all your hardware on a clean, static-free surface:

  1. Unbox your Raspberry Pi
  2. Have your SD card ready
  3. Locate your power supply
  4. Have Ethernet cable(s) within reach

Quality Check:

  • Inspect SD card for damage
  • Verify power supply voltage matches your Pi model
  • Check Ethernet cable ends for bent pins

Step 2: Flash Pimeleon Image

Time: 10 minutes

Download Required Software

  1. Download Raspberry Pi Imager
  2. Download Pimeleon Image (Coming Soon)
    • Visit [pimeleon.com/downloads/downloads/)
    • Select the correct image for your Pi model:
      • pirouter-rpi4-latest.img.xz (Raspberry Pi 4)
      • pirouter-rpi3-latest.img.xz (Raspberry Pi 3B+)

Flash the Image

  1. Insert SD Card
    • Put your SD card into your computer's card reader
    • Note: All data on the card will be erased
  2. Open Raspberry Pi Imager
    • Click "Choose OS"
    • Scroll down and select "Use custom"
    • Navigate to your downloaded Pimeleon image
  3. Configure Settings (Click the gear icon)
    ✓ Set hostname: pi-router
✓ Configure WiFi: (optional, but recommended as backup)
  4. Write the Image
    • Click "Choose Storage"
    • Select your SD card
    • Click "Write"
    • Wait for completion (typically 5-10 minutes)
    • Safely eject the SD card when done

Troubleshooting: If the write fails, try a different SD card. Some older or damaged cards may not work reliably.

Step 3: Initial Boot

Time: 5 minutes

Physical Setup

  1. Insert SD Card
    • Power off the Pi (if already powered)
    • Insert the flashed SD card into the Pi
    • Push until it clicks into place
  2. Connect Ethernet
    • Connect Ethernet cable from your existing router/modem to the Pi's built-in Ethernet port
    • This will be your WAN (internet) connection
  3. Add Cooling (Recommended)
    • Attach heatsinks to CPU and RAM chips
    • Or connect a 5V fan to GPIO pins 4 (+5V) and 6 (GND)
  4. Power On
    • Connect the power supply
    • The Pi will automatically boot
    • Look for:
      • Red LED: Steady (power indicator)
      • Green LED: Blinking (disk activity - normal)

Wait for First Boot

First boot takes 2-3 minutes as the system:

  • Expands the filesystem to use full SD card
  • Generates SSH keys
  • Starts network services
  • Configures initial settings

What to Expect:

  • Green LED blinks rapidly for ~2 minutes
  • Then settles to occasional blinks
  • No display output needed (headless operation)

Boot Problems? See Boot Issues Troubleshooting

Step 4: Verify It Works

Time: 5 minutes

Access the Web Interface

Once the Pi boots (2-3 minutes), access the Pimeleon web interface:

Option 1: Using Hostname (Recommended)

Open your browser to: http://pi-router.local/admin

Option 2: Find IP Address

If hostname doesn't work:

  1. Log into your existing router's admin page
  2. Look for connected devices/DHCP leases
  3. Find "pi-router" in the client list
  4. Note the IP address (e.g., 192.168.1.100)
  5. Open browser to: http://192.168.1.100/admin

Initial Login

  1. You should see the admin login screen
  2. Default credentials:
    • Password: Set during image configuration in Step 2
    • Or default: admin (change immediately if using default)
  3. After login, you'll see the web dashboard

Verify Services

Check the dashboard to confirm everything is working:

System Status (top right of dashboard):

  • DNS Filtering: Should show "Active" in green
  • DNS: Should show "Active" in green
  • DHCP: Shows status based on your configuration

Query Log:

  • Should start showing DNS queries from your network
  • Queries will appear in real-time

Blocked Domains:

  • Check that blocklists are loaded
  • Total blocked domains should show a number > 100,000

Something Not Working? Jump to Troubleshooting below.

Step 5: Connect Your Network

Time: 5 minutes

Now that Pimeleon is running, integrate it into your network. Choose your deployment mode:

Option A: DNS-Only Mode (Easiest)

Use Pimeleon just for DNS filtering, keeping your existing router for everything else.

On Your Computer (or each device):

Windows:

  1. Open Settings → Network & Internet
  2. Click your connection → Properties
  3. Edit DNS settings
  4. Set preferred DNS to Pimeleon's IP
  5. Save changes

macOS:

  1. System Preferences → Network
  2. Select your connection → Advanced
  3. DNS tab → Add Pimeleon's IP
  4. Move it to the top of the list
  5. Click OK → Apply

Linux:

  1. Network Settings → Your Connection → IPv4
  2. DNS: Manual → Add Pimeleon's IP
  3. Apply changes

iOS/Android:

  1. WiFi Settings → Your Network
  2. Configure DNS → Manual
  3. Add Pimeleon's IP as primary DNS

Test It:

Open a browser and visit some websites. You should notice:

  • Ads are blocked on most sites
  • Pages may load faster without tracking scripts
  • web dashboard shows increasing query count

Use Pimeleon as your primary gateway for full routing and filtering.

Requirements:

  • Second Ethernet adapter (USB Gigabit adapter recommended)
  • Existing router set to bridge mode (or disable DHCP)

Network Topology:

Internet → Modem → Pimeleon (eth0: WAN) → (eth1: LAN) → Your Devices

Setup Steps:

  1. Connect Second Ethernet Adapter
    • Plug USB Gigabit Ethernet adapter into Pi
    • Pimeleon will automatically detect and configure it
    • Wait 1-2 minutes for configuration
  2. Automatic Configuration
    Pimeleon automatically configures:
    • eth0 (built-in): WAN interface (DHCP client to your ISP/modem)
    • eth1 (USB adapter): LAN interface (static IP: 192.168.76.1)
    • DHCP server on LAN interface (range: 192.168.76.100-250)
  3. Connect Your Devices
    • Connect switch or access point to LAN interface (eth1)
    • Or connect devices directly to eth1
    • Devices will automatically receive IP addresses
  4. Verify in Web Interface
    • Go to Settings → System in admin interface
    • Check Network Information section
    • Verify two interfaces are shown:
      • WAN interface with public/ISP IP
      • LAN interface with 192.168.76.1
    • DHCP Status should show "Active"

Option C: Inline Filter Mode (Advanced)

Insert Pimeleon between existing router and your network as a transparent filter.

Network Topology:

Internet → Modem → Your Router → Pimeleon → Your Devices

Setup:

  1. Configure Pimeleon WAN to get DHCP from your router
  2. Configure Pimeleon LAN on different subnet
  3. Set up routing between subnets
  4. Configure your router's DHCP to assign Pimeleon as DNS

See Network Architecture for detailed setup.

Verify Full Functionality

Check these final items to confirm everything works:

DNS Filtering Test

  1. Visit a website known for ads (e.g., news sites)
  2. Notice ads are blocked
  3. Check web dashboard:
    • Queries Blocked number should be increasing
    • Recent queries show blocked domains in red

Internet Access Test

  1. Open several different websites
  2. Verify pages load normally
  3. Check that HTTPS sites work (look for padlock icon)
  4. Streaming services should work

Check the Web Dashboard

  1. Open http://pi-router.local/admin
  2. Verify statistics are updating:
    • Total Queries: Number increasing
    • Queries Blocked: Percentage shown
    • Blocklist: Shows total domains blocked
  3. Click Query Log to see real-time DNS requests

Check System Health

In the web dashboard:

  1. Look at System section (bottom of sidebar)
  2. Verify system status:
    • Load: Should be low (< 1.0)
    • Memory Usage: Should have free memory available
    • Temperature: Should be reasonable (< 70°C / 158°F)
  3. All status indicators should be green

All Green? Congratulations! Your Pimeleon is fully operational.

What's Next?

Now that Pimeleon is running, explore these features:

Essential Configuration

  1. Update Blocklists
    • Visit admin interface → Settings → Blocklists
    • Add additional blocklists for enhanced filtering
    • See DNS Filtering Guide
  2. Configure DHCP (if using Gateway Mode)
    • Settings → DHCP → Configure IP range
    • Set static leases for servers/devices
    • See DHCP Configuration

Advanced Features

  • VPN Access - Connect remotely via Wireguard or OpenVPN
  • Traffic Monitoring - View bandwidth usage and top talkers
  • Custom DNS - Add local DNS records for your network
  • Ad Blocking - Fine-tune blocklists and whitelist false positives
  • Proxy Chains - Route traffic through Tor, Privoxy, or Squid

Explore the Architecture Documentation to learn more.

Troubleshooting

Pi Won't Boot

Symptoms: No green LED activity, or only red LED

Solutions:

  1. Check power supply is adequate (3A for Pi 4, 2.5A for Pi 3B+)
  2. Try a different SD card
  3. Re-flash the image
  4. See Boot Issues Guide

Can't Access Web Interface

Symptoms: Browser shows "connection refused" or "can't reach this page"

Solutions:

  1. Verify Pi is powered on (check LED activity)
  2. Check Pi is on your network (look for "pi-router" in router's DHCP leases)
  3. Try IP address instead of hostname
  4. Wait 3-5 minutes after boot for services to start
  5. Try different browser or clear browser cache
  6. If using WiFi, verify WiFi settings were configured correctly

DNS Not Blocking Ads

Symptoms: Ads still appear on websites

Solutions:

  1. Verify DNS is configured correctly:
    • Check your device's DNS settings point to Pimeleon
    • Open web dashboard and verify queries are appearing
  2. Clear browser cache and cookies
  3. Some ads use CNAME cloaking (not blockable by DNS)
  4. Check Query Log shows your device's requests
  5. Add more blocklists in Settings → Blocklists

Slow Internet

Symptoms: Pages load slowly or timeout

Solutions:

  1. Check system temperature in web dashboard (System section)
    • If >80°C / 176°F, add cooling (heatsink or fan)
  2. Verify network cables are Cat5e or better and properly seated
  3. Check web dashboard for high CPU load
  4. Reduce blocklist size if using Pi 3B+ (Settings → Blocklists)
  5. Consider upgrading to Pi 4 for >300Mbps speeds

Web Interface Won't Load

Symptoms: Browser shows "connection refused" or times out

Solutions:

  1. Wait 3-5 minutes after boot - services need time to start
  2. Check Pi status LEDs - red (power) should be steady, green should blink occasionally
  3. Try accessing via IP address instead of hostname
  4. Try different browser or clear browser cache
  5. Verify Pi has network connectivity (check router's connected devices)

Common Issues and Quick Fixes

Under-voltage Detected

Symptoms: Yellow lightning bolt icon on Pi (if connected to monitor), or system instability

Fix:

  • Use official Raspberry Pi power supply
  • Check power cable and connections are secure
  • Verify outlet is working properly
  • Don't use cheap USB chargers

SD Card Issues

Symptoms: System becomes unresponsive, files won't save, boot failures

Fix:

  • Use quality SD card (Samsung EVO+, SanDisk Extreme)
  • Re-flash image to new SD card
  • Keep system updated to prevent filesystem corruption
  • Consider moving to USB boot (Pi 4 only)

DNS Resolution Fails

Symptoms: No websites load, all queries fail

Fix:

  1. Check web dashboard shows DNS service as "Active"
  2. If red/inactive, restart Pi (power cycle)
  3. Verify upstream DNS servers configured (Settings → DNS)
  4. Temporarily point devices to 8.8.8.8 to restore connectivity while troubleshooting

System Instability After Updates

Symptoms: Services don't start, features stop working

Fix:

  1. Restart system (Settings → System → Restart)
  2. Check web dashboard for service status
  3. If persists, may need to re-flash image
  4. Keep backup of system configuration (Settings → Teleporter)

Performance Tips

For Raspberry Pi 3B+ Users

  • Use 32-bit (armhf) build for better memory efficiency
  • Limit blocklists to < 1 million domains (adjust in Settings)
  • Use passive cooling (Pi 3B+ runs cooler than Pi 4)
  • Expect ~250-300 Mbps throughput
  • Monitor temperature in dashboard - keep < 70°C

For Raspberry Pi 4 Users

  • Active cooling recommended under sustained load
  • Can handle 2+ million blocked domains
  • Expect ~900+ Mbps throughput with proper cooling
  • Consider 4GB or 8GB model for heavy usage
  • Monitor temperature in dashboard - keep < 75°C

General Optimization

  • Use quality SD card (Samsung EVO+, SanDisk Extreme)
  • Check for updates regularly via web dashboard
  • Monitor system health in dashboard (System section)
  • Regular reboots (weekly) help maintain performance
  • Keep blocklists manageable for your Pi model

Getting Help

Documentation

Community

When Asking for Help

Include this information:

  1. Hardware: Raspberry Pi model (3B+ or 4, RAM size)
  2. Image Version: Check in web dashboard footer
  3. Network Mode: DNS-Only, Gateway, or Inline Filter
  4. System Info from web dashboard:
    • Load average
    • Memory usage
    • Temperature
  5. Problem Description:
    • What you expected to happen
    • What actually happened
    • Steps to reproduce
  6. Screenshots: web dashboard showing the issue

Summary

You've just completed the Pimeleon quick setup! Here's what you accomplished:

  • Flashed Pimeleon to SD card
  • Booted and verified the system
  • Connected to your network
  • Tested DNS filtering
  • Verified full functionality

Estimated time: 25-30 minutes

Your Pimeleon is now:

  • Blocking ads and trackers
  • Providing DNS resolution
  • Routing traffic (if Gateway Mode)
  • Ready for advanced configuration

What You Learned

  • How to flash and boot Pimeleon
  • How to verify services are running
  • How to integrate with your existing network
  • How to perform basic troubleshooting
  • Where to find additional help

Continue Your Journey

Ready to go deeper? Check out:

  1. Network Architecture - Understand how Pimeleon routes traffic
  2. DNS Filtering - Master ad blocking and privacy protection
  3. DHCP Configuration - Manage IP assignments
  4. Hardware Guide - Optimize your hardware setup
  5. Advanced Features - Explore VPN, proxies, and monitoring

Questions? Visit the Community Forum or check out our FAQ.

ON THIS PAGE
Overview
Prerequisites
Step 1: Gather Your Hardware
Step 2: Flash Pimeleon Image
Step 3: Initial Boot
Step 4: Verify It Works
Step 5: Connect Your Network
Verify Full Functionality
What's Next?
Troubleshooting
Common Issues and Quick Fixes
Performance Tips
Getting Help
Summary
What You Learned
Continue Your Journey