Frequently Asked Questions (FAQ)

Common questions and answers about Pimeleon installation, configuration, and troubleshooting

Frequently Asked Questions (FAQ)

"When you don't know what you're doing, it's best to do it quickly." — Arthur Bloch, Murphy's Law

This FAQ covers the most common questions about Pimeleon installation, configuration, and operation. Find answers to setup challenges, network configuration, and getting help.

Installation & Hardware

Which Raspberry Pi models are supported?

Pimeleon is officially supported on:

  • Recommended: Raspberry Pi 4B (2GB RAM minimum, 4GB+ recommended)
  • Supported: Raspberry Pi 3B+ (1GB RAM)
  • Limited: Raspberry Pi Zero 2 W (512MB RAM) - WiFi bridge mode only
  • Future: Raspberry Pi 5 (under development)

Why these models?

  • Gigabit Ethernet (Pi 4/5) or fast USB Ethernet (Pi 3B+)
  • Adequate RAM for DHCP server, DNS filtering, and firewall
  • Sufficient CPU for ~300+ Mbps routing performance
  • Modern components with active community support

Pi models older than 3B+ lack the network performance and RAM capacity needed for modern internet speeds and concurrent device management.

Can I install Pimeleon on an existing Raspberry Pi OS installation?

Not recommended. Pimeleon requires a clean installation to:

  1. Configure network interfaces for router mode (WAN/LAN separation)
  2. Disable automatic updates that may conflict with Pimeleon services
  3. Pre-optimize kernel parameters for network throughput
  4. Set up firewall and routing rules correctly

Best practice: Use the pre-built Pimeleon image, which includes all optimizations. If you must add Pimeleon to existing Raspbian, expect compatibility issues and potential performance degradation.

What microSD card do I need?

Minimum: 16GB Class 10 SD card Recommended: 32-64GB high-endurance card (Samsung PRO Endurance or SanDisk High Endurance)

Why high-endurance?

Pimeleon logs DNS queries and network events continuously. Standard SD cards wear out quickly under this write-heavy workload. High-endurance cards are optimized for 24/7 operation and logging scenarios.

What power supply do I need?

For Raspberry Pi 3B+:

  • 5V, 2.5A minimum (official Pi supply recommended)
  • Router mode draws 5-7W continuous, spikes to 10W under load

For Raspberry Pi 4B:

  • 5V, 3A minimum for stable operation
  • Can use USB-C power adapter from laptops/phones if 3A capable
  • Avoid cheap power supplies — inadequate power causes random reboots

For Raspberry Pi 5:

  • 5V, 5A USB-C power supply (included in official kits)
  • Poor power quality causes CPU throttling and performance loss

Do I need additional network hardware?

Minimum setup:

  • 1 Ethernet port (WAN input from your ISP modem)
  • Built-in WiFi or Ethernet (for LAN output to clients)

Enhanced setup:

  • USB 3.0 Gigabit adapter (for separate LAN network with higher speed)
  • Passive or active heatsink (for 24/7 operation)
  • UPS HAT (for graceful shutdown during power loss)

First Boot & Initial Setup

Why can't I access the web interface after first boot?

Check these steps:

  1. Web interface access:
    • Power up the router, wait 2-3 minutes for boot
    • Open browser to http://pimeleon.local/admin or http://192.168.76.1/admin
    • Default password: Set during image configuration
    • If HTTPS: https://pimeleon.local/admin (self-signed certificate)
  2. If connection times out:
    • Ensure Ethernet cable is connected to LAN port (or your computer's Ethernet port)
    • Check green LED is blinking occasionally (system is running)
    • Verify your computer received an IP in 192.168.76.x range
    • Try accessing via IP address instead of hostname
    • Try different browser or clear browser cache

The setup wizard asks for passwords but seems broken

Known issue: On first boot, browser password cache may cause confusion with multiple password fields.

Solution:

  1. Open a private/incognito browser window
  2. Navigate to http://192.168.1.1 fresh
  3. Complete setup wizard from start
  4. Browser cache is cleared automatically after first setup completion

How do I set the router hostname/domain?

During initial setup, you'll be asked for your network name. This becomes your router's local domain:

  • Default: pimeleon.local
  • Custom: You can set to myrouter.local, gateway.local, etc.

Access the router by hostname:

Instead of IP address (http://192.168.76.1), you can use:

  • http://pimeleon.local/admin (hostname.local)

From inside your network, all devices can use the hostname:

  • Web interface: pimeleon.local/admin
  • DNS names: pimeleon.local or pi.hole
  • router.pimeleon.local (web interface)
  • 192.168.1.1 (IP address backup)

Network Configuration

How do I change the WiFi network name and password?

Through web interface:

  1. Log in to http://192.168.1.1
  2. Settings → WiFi Configuration
  3. Change SSID and password
  4. Apply changes (network will briefly disconnect)

WiFi settings can be managed through the web interface or system settings.

Can I use my Pimeleon router as a bridge instead of a router?

Not in version 1.0. Bridge mode is planned for v1.1 release (Q2 2025).

Currently, Pimeleon operates in router mode only:

  • Acts as WAN-to-LAN gateway
  • Provides DHCP to devices
  • Applies firewall and filtering rules
  • Separates networks by role (untrusted WAN vs trusted LAN)

Workaround: Use a dedicated managed switch between your modem and Pimeleon if you need bridging functionality.

How do I set a static IP address on my device?

Recommended: Use MAC address reservation in DHCP settings instead of static IPs.

Static IPs bypass the router's DHCP system and can cause conflicts. To reserve a static-like IP:

  1. Log in to web interface
  2. Go to DHCP → Client Reservations
  3. Add your device's MAC address with preferred IP
  4. Your device will always receive that IP via DHCP

To find your MAC address:

  • Windows: ipconfig /all (Physical Address)
  • macOS/Linux: ip link show or ifconfig
  • iPhone/Android: Settings → Wi-Fi → Your Network → (i) → MAC Address

What's the difference between WAN and LAN ports?

  • WAN (Internet): Connection from your ISP modem — typically eth0
  • LAN (Network): Connection to your devices — typically wlan0 (WiFi) or eth1 (wired second NIC)

Pimeleon bridges these networks with firewall rules, DNS filtering, and DHCP. The WAN port receives your internet connection; devices on LAN get filtered access through Pimeleon's services.

DNS & Filtering

Why are some sites still loading that should be blocked?

Common reasons:

  1. DNS cache: Site was visited before rule was added
    • Clear browser cache (Ctrl+Shift+Del)
    • Flush router DNS cache: sudo systemctl restart unbound
  2. HTTPS blocking limitations: Encrypted HTTPS connections hide the domain
    • Pimeleon can't selectively block HTTPS connections per domain
    • Blocks only at IP layer when entire site is blocklisted
  3. Allowlist override: Check if site is whitelisted
    • Go to web interface → Filtering → Allowlist
    • Remove site if it appears there
  4. Blocklist update lag: Custom blocklists update periodically
    • Check: Filtering → Blocklists → Last Updated
    • Force update: Filtering → Update Now

Can I whitelist a site that's blocked?

Yes, easily:

  1. Log in to web interface
  2. Go to Filtering → Allowlist
  3. Add domain: example.com (allows all subdomains)
  4. Click Save (applies immediately, no restart needed)

Tip: Use exact domain names. facebook.com is different from *.facebook.com.

Why is my DNS lookup slow?

Check upstream DNS:

Use the built-in DNS diagnostics:

  1. Log into admin interface
  2. Go to Tools → Network
  3. Test DNS queries to various servers
  4. Check response times

If upstream is slow:

  1. Go to Settings → DNS
  2. Change upstream servers (try Cloudflare 1.1.1.1 or Quad9 9.9.9.9)
  3. Apply changes (service restarts automatically)

If system is slow:

  1. Check System section in dashboard for:
    • High CPU load
    • Low memory
    • High temperature
  2. Consider restarting system if resources are constrained

How do I set custom DNS records for local devices?

Create a local DNS zone in the web interface:

  1. DNS → Custom Zones
  2. Add zone: mynetwork.local
  3. Add records:
    • server.mynetwork.local → 192.168.1.10
    • printer.mynetwork.local → 192.168.1.20

Devices on your network can now access these by hostname.

Troubleshooting & Support

The router boots but has no internet connection

Diagnostic checklist:

  1. Physical connections:
    • Verify Ethernet cable connected to WAN/Internet port (eth0)
    • Check ISP modem lights show active connection
    • Verify modem is powered on
  2. Check network status in web dashboard:
    • Go to Settings → System
    • Check Network Information section
    • WAN interface should have IP address
    • Should show default gateway
  3. Test connectivity from the router:
    • Go to Tools → Network
    • Test ping to 8.8.8.8 (should succeed)
    • Test DNS query (should resolve)

Common fixes:

  • ISP modem requires specific MAC address registration (call ISP support)
  • WAN port configured for static IP instead of DHCP (check web interface)
  • Firewall rule blocks upstream DNS (very rare, contact support)

How do I reset the router to factory defaults?

Hardware reset:

  1. Locate small reset button on device (recessed hole)
  2. Power on the router
  3. Hold reset button with paperclip for 15+ seconds until LEDs flash
  4. Release and wait for reboot
  5. Set up again with initial setup wizard

After reset:

  • Default IP: 192.168.1.1
  • Default credentials: admin / pirouter
  • All configuration deleted

Where do I get help?

Documentation:

  • [Pimeleon Docs//)
  • Specific guides for each feature
  • Troubleshooting sections in operation guides

Community Support:

When requesting help:

  1. Include your Pimeleon version (check web dashboard footer)
  2. Describe what you've tried already
  3. Provide network topology (how your devices connect)
  4. Include screenshots of web dashboard showing the issue

Commercial & Licensing

Is Pimeleon free software?

Yes. Pimeleon is licensed under AGPLv3 — free and open source forever.

  • No license fees
  • No proprietary restrictions
  • No data collection or telemetry
  • Community can audit and modify the code

You can use it for personal use or commercial deployments at no cost.

Can I use Pimeleon in a commercial environment?

Yes, subject to AGPLv3 requirements:

  1. If you distribute modified Pimeleon software, source code must be available
  2. Users must have access to the same freedoms (source code access)
  3. License notice must be included in your product

Commercial deployment (unmodified Pimeleon):

  • No restrictions — use freely in businesses, ISP networks, etc.
  • No license fees or commercial licensing required
  • Support is community-based (not commercial support)

Commercial modifications:

  • Custom features require source code disclosure
  • Consider reaching out about dual-licensing arrangements for proprietary modifications

Can I remove the Pimeleon branding?

For unmodified installations: Pimeleon branding appears in web interface and initial setup. You cannot remove it.

For commercial deployments: Contact the Pimeleon maintainers about white-label licensing or dual-licensing options for removing branding.

Still have questions? Open an issue on GitHub or ask in our Discord community.

ON THIS PAGE
Installation & Hardware
First Boot & Initial Setup
Network Configuration
DNS & Filtering
Troubleshooting & Support
Commercial & Licensing