Pimeleon

Overview

Pimeleon router is an open-source router and network management system designed specifically for Raspberry Pi devices. It combines enterprise-grade networking features with the accessibility of consumer hardware, providing advanced DNS management, content filtering, and security hardening in a single, cohesive package.

Built by the community, for the community, Pimeleon router emphasizes privacy, security, and user control over your network infrastructure.

Why Pimeleon?

• Privacy First: Your network, your rules. No telemetry, no cloud dependencies, no third-party tracking
• Advanced Filtering: Beyond simple ad-blocking - granular control over content, protocols, and traffic patterns
• Enterprise DNS Features: Split-horizon DNS, DNSSEC validation, custom zones, and advanced caching
• Hardened Security: Built-in intrusion detection, automatic security updates, and defense-in-depth architecture
• Remote Management: Secure remote configuration without exposing your network
• Resource Efficient: Optimized for Raspberry Pi 3B+ and newer, running smoothly on limited hardware

Features

Core Networking

• Dual-Stack Support: Full IPv4 and IPv6 routing and firewall capabilities
• Multi-WAN: Load balancing and failover between multiple internet connections
• VLAN Support: Network segmentation for IoT devices, guests, and trusted devices
• QoS/Traffic Shaping: Prioritize critical traffic and prevent bandwidth hogging
• VPN Server: Built-in VPN server with hardware-optimized recommendations (OpenVPN for RPi 3B+, WireGuard for RPi 4)

DNS Management

• Local DNS Server: Fast, caching DNS resolver with DNSSEC validation
• Custom Domains: Define local domains if needed
• Split-Horizon DNS: Different responses for internal vs external queries
• DNS-over-HTTPS/TLS: Encrypted upstream DNS queries for privacy
• Dynamic DNS: Automatic updates for dynamic IP addresses

Advanced Filtering

• Multi-Layer Filtering: DNS, IP, port, and application-layer filtering
• Regex Support: Complex pattern matching for URLs and domains
• Time-Based Rules: Different filtering policies by time of day
• User/Device Groups: Customized filtering per device or user group
• Allowlist/Blocklist: Granular control with override capabilities
• Real-Time Threat Feeds: Automatic updates from community-maintained blocklists

Security Features

• Intrusion Detection: Snort/Suricata integration for threat detection
• Automatic Security Updates: Unattended security patches with rollback capability
• Port Knocking: Hidden service access for management interfaces
• Fail2ban Integration: Automatic blocking of brute-force attempts
• Certificate Management: Automatic Let's Encrypt certificates for services

Management Interface

• Modern Web UI: Responsive, real-time dashboard with dark mode
• RESTful API: Full programmatic control for automation
• CLI Tools: Complete command-line management interface
• Mobile Responsive: Manage your network from any device
• Real-Time Statistics: Live traffic monitoring and analytics

Quick Start

Prerequisites

• Raspberry Pi 3B+ (or newer)
• MicroSD card (16GB minimum, 32GB recommended)
• Ethernet cable for initial setup
• Power supply (official Raspberry Pi power supply recommended)

Installation

Method 1: Pre-built Image (Recommended for beginners)

1. Download the latest Pimeleon router image:

   wget https://github.com/pirouter/releases/latest/pimeleon-raspbian.img.xz
   

2. Flash to SD card using Raspberry Pi Imager or dd:

   xzcat pimeleon-raspbian.img.xz | sudo dd of=/dev/sdX bs=4M status=progress
   

3. Insert SD card and power on your Raspberry Pi
4. Connect to the initial setup wizard:
   • Wi-Fi SSID: Pimeleon-Setup
   • Password: pirouter-init
   • Navigate to: http://192.168.4.1

Method 2: Install on Existing Raspbian

# Download and run the installer
curl -sSL https://get.pimeleon.com | bash

# Or clone and install manually
git clone https://github.com/pimeleon/pimeleon.git
cd pimeleon
sudo ./install.sh

Post-Installation

1. Access the Web Interface:

   http://router.pimeleon.com
   # or
   http://192.168.1.1
   

   
   Default credentials:
   • Username: admin
   • Password: pirouter (change immediately)
2. Run Initial Security Hardening:

   sudo pirouter-cli security harden --level recommended
   

3. Configure Your Network:

   sudo pirouter-cli network setup --wizard
   

Documentation

Configuration Examples

Basic Home Network

# /etc/pirouter/config.yaml
network:
  mode: router
  wan:
    interface: eth0
    type: dhcp
  lan:
    interface: wlan0
    subnet: 192.168.1.0/24
    dhcp:
      enabled: true
      range: 192.168.1.100-192.168.1.200

dns:
  upstream:
    - 9.9.9.9
    - 1.1.1.1
  local_domain: pirouter.local
  cache_size: 10000

filtering:
  enabled: true
  blocklists:
    - https://someonewhocares.org/hosts/
    - https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts
  custom_rules:
    - block: '*.facebook.com'
    - allow: '*.github.com'

Advanced Multi-VLAN Setup

# /etc/pirouter/network.d/vlans.yaml
vlans:
  - id: 10
    name: trusted
    subnet: 192.168.10.0/24
    dhcp: true
  - id: 20
    name: iot
    subnet: 192.168.20.0/24
    dhcp: true
    isolation: true
  - id: 30
    name: guest
    subnet: 192.168.30.0/24
    dhcp: true
    isolation: true
    bandwidth_limit: 10mbps

Architecture

Pimeleon router follows a modular, microservices-inspired architecture:

┌─────────────────────────────────────────────────────────┐
│                     Web Interface                        │
│                  (React + TypeScript)                    │
└────────────────────┬────────────────────────────────────┘
                     │ REST API
┌────────────────────▼────────────────────────────────────┐
│                    API Gateway                           │
│                 (Node.js + Express)                      │
└──┬──────────┬──────────┬──────────┬──────────┬─────────┘
   │          │          │          │          │
┌──▼──┐  ┌───▼───┐  ┌───▼───┐  ┌───▼───┐  ┌───▼───┐
│ DNS │  │Filter │  │Router │  │Security│  │Update │
│Service│ │Service│  │Service│  │Service │  │Service│
└──────┘  └───────┘  └───────┘  └────────┘  └───────┘

Technology Stack

• Core Services: Python 3.9+ with asyncio
• Web UI: React 18 with TypeScript
• API: Node.js with Express and Socket.io
• DNS: Unbound with custom Python modules
• Filtering: nftables with Python control plane
• Database: SQLite for configuration, Redis for caching
• Message Queue: Redis Pub/Sub for inter-service communication

Community

Getting Help

• Documentation: Official Documentation
• Discord: Join our Discord server - Real-time chat and support
• Forum: https://community.pimeleon.com - Searchable discussions and guides
• GitLab Issues: Report bugs or request features

Contributing

We welcome contributions from everyone! Whether you're fixing bugs, adding features, improving documentation, or helping other users, your input is valuable.

• Contributing Guidelines - How to contribute to Pimeleon
• Development Chat: Join #development on Discord for contributor coordination
• Feature Discussions: Propose and discuss features in our community forum

Quick Contribution Guide

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Setup

# Clone the repository
git clone https://github.com/pimeleon/pimeleon.git
cd pimeleon

# Install development dependencies
./scripts/setup-dev.sh

# Run tests
./scripts/test.sh

# Start development environment
docker-compose up -d

Performance

Tested on Raspberry Pi 3B+:

• Throughput: 300+ Mbps routing performance
• DNS Queries: 10,000+ queries/second
• Concurrent Devices: 50+ devices without degradation
• Memory Usage: ~200MB base, ~500MB under load
• Boot Time: <30 seconds to fully operational

Roadmap

Version 1.0 (Current)

• ✅ Core routing functionality
• ✅ DNS management
• ✅ Basic filtering
• ✅ Web interface

Version 1.1 (Q2 2025)

• ⏳ WireGuard VPN integration
• ⏳ Advanced QoS policies
• ⏳ Mobile app for management
• ⏳ Backup/restore functionality

Version 2.0 (Q4 2025)

• 📋 Mesh networking support
• 📋 AI-powered threat detection
• 📋 Container-based service hosting
• 📋 GraphQL API
• 📋 Multi-language support

Support the Project

Pimeleon router is a community-driven project that depends on contributions and donations to continue development.

How to Support

• ⭐ Star this repository to increase visibility
• 🐛 Report bugs and help test new features
• 📝 Improve documentation and write tutorials
• 💻 Contribute code for new features or bug fixes
• 💬 Help others in Discord and forums
• ☕ Donate to support infrastructure and development

License

Pimeleon router is licensed under the GNU General Public License v3.0 - license details will be available in the Pimeleon build repository (coming soon).

Acknowledgments

• The Raspberry Pi Foundation for excellent hardware
• The open-source community for inspiration and components
• Our contributors and supporters who make this project possible
• Open-source networking projects that paved the way