mgrotke/linuxrouter
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Development

Browse source
This commit is contained in:
Matthew Grotke 2026-06-11 01:31:57 -04:00
parent 4be98fd794
commit ef4bdef838
14 changed files with 780 additions and 1419 deletions
Download patch file Download diff file Expand all files Collapse all files

135
README.md
View file

@ -1,113 +1,94 @@
# Routlin
A collection of Python scripts that transform an existing Linux server (with at least two Ethernet NICs) into a fully-featured enterprise-grade router, eliminating the need for a separate router appliance.
Turn any Linux machine with two NICs into an enterprise-grade router and firewall. Ditch vendor-gated appliances and opaque firmware while keeping your machine fully multipurpose and under your control. Manage VLANs, NAT, DNS, DHCP, VPN, RADIUS, mDNS, and content filtering through a modern web dashboard - all built on battle-tested Linux tools you already trust.
Designed to integrate seamlessly with existing enterprise and prosumer networking hardware.
---
## Why Replace Your Router?
Consumer and prosumer router appliances are constrained by OEM firmware. Security patches depend entirely on the vendor's release schedule, features and functionality are often limited, and devices that reach end of life receive no vendor support at all, leaving gaping security vulnerabilities exposed on your network indefinitely. Running your router on a general-purpose Linux machine gives you:
Consumer and prosumer router appliances are constrained by OEM firmware. Security patches depend entirely on the vendor's release schedule, features are limited by design, and devices that reach end of life get abandoned with no further updates - leaving permanent security holes on your network.
- **Faster speeds** - Utilize full fledged computer hardware (typically exceeds that of consumer appliances)
- **Full flexibility** - Any configuration that Linux and its tooling support
- **Better security** - Patch your own kernel and packages on your own schedule, with no dependency on a vendor who may have abandoned your hardware
Running your router on a general-purpose Linux machine gives you:
- **Faster speeds** - Use real computer hardware that outperforms consumer appliances
- **Full flexibility** - Any configuration that Linux supports
- **Better security** - Patch your kernel and packages on your schedule, not the vendor's
---
## Summary
## What Routlin Does
These scripts do not run continuously in the background. They install and facilitate the configuration of battle-hardened software (`dnsmasq` for DHCP and DNS, `nftables` for firewall and NAT, `chrony` for NTP, `freeradius` for RADIUS, `avahi` for mDNS discovery, and `wireguard` for VPN) using JSON files that you edit. A fully-featured, easy-to-use web management dashboard is included for users who prefer not to edit JSON directly.
Routlin installs and manages battle-hardened Linux networking software - `dnsmasq`, `nftables`, `freeradius`, `wireguard`, `avahi`, and `chrony` - using a configuration file and a web dashboard. The scripts are not daemons; they configure the real software and get out of the way.
**VLANs and Network Segmentation** - Slice your network into isolated segments: a trusted LAN, a guest Wi-Fi, an IoT VLAN, a camera network. Each VLAN gets its own DHCP pool, DNS resolver, and firewall rules. Devices on different VLANs cannot reach each other unless you explicitly allow it.
**DNS Filtering and Content Blocking** - Block ads, malware, and trackers at the DNS level across your whole network. Apply different blocklists to different VLANs - strict filtering on the kids' network, none on the server VLAN. Blocklists update automatically on a daily schedule.
**WireGuard VPN** - Connect remotely to your home network from anywhere. Routlin configures the WireGuard server, generates keypairs, and produces ready-to-import client config files. Per-peer split-tunnel and full-tunnel routing supported.
**RADIUS and 802.1X** - Assign devices to VLANs dynamically based on their MAC address using your managed switch or access point. No more manually configuring per-port VLANs on your switch - plug in a device and it lands in the right network automatically.
**DDNS** - Keep a hostname pointed at your home IP even when your ISP changes it. Supports Cloudflare, No-IP, and DuckDNS with automatic rotation across multiple IP-check services.
**Web Dashboard** - A clean, modern interface for managing everything without editing JSON by hand. Changes are validated, queued, and applied to the live system automatically.
---
## Capabilities
## Two Editions
The suite is organized into independent but complementary scripts, each managing one layer of the stack:
### Routlin CE - Free for Individual Use
### Core: DHCP, DNS, Firewall, RADIUS, mDNS, and WireGuard VPN (`core.py`)
Routlin CE is the core product and is free for personal, non-commercial use. It includes everything described above: VLANs, DHCP, DNS filtering, WireGuard VPN, RADIUS/802.1X, DDNS, mDNS reflection, port forwarding, the web dashboard, and more.
- Configures VLAN sub-interfaces via `systemd-networkd`
- Assigns static or dynamic DHCP reservations by MAC address and hostname
- Defines dynamic IP pools per VLAN
- Manages per-VLAN gateway, DNS, and NTP settings derived from `server_identities`
- Runs one `dnsmasq` instance per VLAN, each bound exclusively to its gateway IP, giving true per-VLAN DNS filtering
- Applies per-VLAN content filtering - VLANs with different blocklist sets each get their own merged blocklist (blocklists are downloaded and merged by `dns-blocklists.py`)
- Supports local hostname overrides (split DNS for DDNS hostnames)
- Installs a daily `systemd` timer that runs `dns-blocklists.py` to refresh blocklists
- Tracks lifetime DNS metrics (queries forwarded, cache hits, authoritative, TCP peaks, pool usage)
- Builds `nftables` tables atomically - safe to re-apply without service disruption
- Handles port forwarding (DNAT/SNAT) for externally accessible services
- Handles port wrangling - redirects DNS and NTP requests to the local resolver regardless of what the client device may have hardcoded
- Blocks traffic from specific IPs or subnets via `banned_ips` - supports single IPs, CIDR notation, wildcards, and ranges for both IPv4 and IPv6
- Enforces inter-VLAN isolation by default (forward chain policy drop); specific cross-VLAN traffic is permitted via `inter_vlan_exceptions`
- Masquerades outbound traffic for all non-WireGuard VLANs automatically
- Auto-detects active container bridge interfaces (Docker, Podman, libvirt, etc.) and adds forward rules so VLAN clients can reach containerized services
- Auto-detects active container bridge interfaces and adds DNS listening on each bridge IP, so containers can reach the local DNS resolver during builds and at runtime
- Installs a `systemd` boot service (`routlin-nat.service`) to re-apply firewall rules on every boot
- Co-exists with Docker (does not touch Docker-managed `nat`/`filter` tables)
- Generates FreeRADIUS `clients.conf` and `users` files from `core.json` reservations, enabling dynamic VLAN assignment via MAC Authentication Bypass (MAB) for both wired (802.1X) and wireless clients
- Manages a `.radius-secret` shared secret file (generated automatically on first `--apply` if RADIUS is enabled)
- Configures `avahi-daemon` as an mDNS reflector to forward service discovery announcements (AirPrint, AirPlay, Chromecast, etc.) across VLANs
- Supports any number of WireGuard VPN interfaces (`is_vpn: true` VLANs); generates the server keypair on first apply, writes the server conf to `/etc/wireguard/`, and brings the interface up with `wg-quick`; subsequent applies sync peer changes live without restarting the interface
- Supports per-peer split-tunnel (VPN subnet only) or full-tunnel (all traffic) routing; peer data is stored directly in `core.json`
### Routlin Pro - Paid License
### Optional: DNS Blocklists (`dns-blocklists.py`)
Routlin Pro is a paid license tier with advanced security and monitoring features suited for businesses, managed networks, and power users who need deeper visibility and control.
- Downloads blocklists from upstream providers you choose (e.g. OISD, Hagezi)
- Merges them per unique VLAN combination into conf files loaded by `dnsmasq`
- Runs `core.py --apply` after a successful download to reload all instances
- Invoked by the daily `systemd` timer installed by `core.py --apply`
**Deep Packet Inspection and Device Identification** - See exactly what every device on your network is doing. Routlin Pro automatically classifies devices and identifies traffic types in real time - streaming, gaming, P2P, VoIP, and more - feeding into a Security Insights dashboard and per-device traffic rules.
### Optional: DDNS (`ddns.py`)
**Intrusion Detection and Prevention (IDS/IPS)** - Monitor your network for known threat signatures across all traffic, not just DNS. Choose alert-only mode or automatic blocking. Signature database updated regularly, with an optional extended commercial threat feed.
- Detects the current public IP by rotating through multiple IP-check services
- Updates the specified DNS providers (currently supporting Cloudflare, No-IP and DuckDNS), supporting multiple hostnames and subdomains per provider
- Caches the last known IP per provider to avoid unnecessary API calls
- Installs a `systemd` timer that runs every 5 minutes by default
- Logs all updates and errors to `ddns.log`
**SSL/TLS Traffic Inspection** - See inside encrypted HTTPS traffic for security monitoring and content filtering. Routlin Pro decrypts, inspects, and re-encrypts on the fly, enabling IDS/IPS and anomaly detection to work on traffic that would otherwise be completely opaque.
### Optional: Routlin Dashboard
**Traffic Flows (Session Logging)** - A full log of every TCP and UDP connection through the router: source, destination, port, bytes, and timing. Filter, sort, and save presets. Invaluable for diagnosing bandwidth problems or investigating unexpected activity.
- Web UI for managing all aspects of the router (VLANs, reservations, blocklists, VPN, DDNS, firewall, and more) without editing JSON by hand
- Runs as a Docker container alongside the existing scripts
- Changes made in the dashboard are queued and applied to the live system automatically via a 1-minute systemd timer
**Anomaly and Pattern Detection** - Routlin Pro watches for unusual behavior automatically: unexpected large transfers, SYN flood indicators, overnight activity on idle devices, new device types appearing, and more. Anomalies surface as dashboard alerts and can trigger automated responses like device isolation or rate limiting.
**Restricted VLANs** - Prevent devices on a VLAN from ever contacting the internet. Perfect for IoT devices, security cameras, NAS, printers, or anything that should never phone home. Works alongside inter-VLAN exception rules so you can still reach quarantined devices from inside the LAN.
**Supplicant-Based 802.1X Authentication** - Go beyond MAC-based authorization. Routlin Pro adds full EAP-PEAP, EAP-TTLS, and EAP-TLS support, letting devices authenticate with credentials or certificates. Revoke individual device access without changing network passwords - and block anyone spoofing a known MAC.
**Captive Portal** - Turn any VLAN into a captive portal with a splash page, time-limited vouchers, or full RADIUS login using your existing user accounts. Ideal for guest networks, venues, or any situation where you need to control and track who gets access.
---
## Software Dependencies
These packages are required. `install.py` checks that they are installed and will prompt to install any that are missing.
`install.py` checks for these and will prompt to install any that are missing.
| Dependency | Purpose | Required By |
|---|---|---|
| `python3` | Runs all scripts | All |
| `systemd` | Service, timer, networkd, and timesyncd management | All |
| `dnsmasq` | DHCP server and DNS resolver/forwarder | `core.py` |
| `nftables` | Firewall, NAT, port forwarding, and port wrangling | `core.py` |
| `chrony` | NTP server - synchronizes system clock and serves time to VLAN clients | `core.py` |
| `freeradius` | RADIUS server for dynamic VLAN assignment via MAC auth | `core.py` |
| `avahi-daemon` | mDNS reflector for cross-VLAN service discovery | `core.py` |
| `wireguard-tools` | WireGuard VPN (`wg`, `wg-quick`) | `core.py` (when WireGuard VLANs are configured) |
| `docker` | Runs the Routlin Dashboard container | `install.py` (dashboard only) |
| `caddy` | Reverse proxy for external HTTPS access to the dashboard | `install.py` (external access only) |
---
## Conflicting Software
The following services conflict with this suite. No manual action is required: `core.py` disables them automatically on `--apply`. `core.py` re-enables them on `--disable`.
- **systemd-resolved** - DNS stub resolver that conflicts with `dnsmasq` on port 53. Disabled on `--apply`; re-enabled on `--disable`.
- **systemd-timesyncd** - Basic SNTP client that cannot serve time to LAN clients; replaced by `chrony`. Disabled on `--apply`; re-enabled on `--disable`.
- **ufw** - Firewall manager that conflicts with the `nftables` ruleset. Disabled on `--apply` without removal.
| Dependency | Purpose |
|---|---|
| `python3` | Runs all scripts |
| `systemd` | Service, timer, networkd, and timesyncd management |
| `dnsmasq` | DHCP and DNS |
| `nftables` | Firewall, NAT, and port forwarding |
| `chrony` | NTP server for the router and VLAN clients |
| `freeradius` | RADIUS server for dynamic VLAN assignment |
| `avahi-daemon` | mDNS reflection across VLANs |
| `wireguard-tools` | WireGuard VPN (when VPN VLANs are configured) |
| `docker` | Runs the Routlin Dashboard container (dashboard only) |
| `caddy` | Reverse proxy for external HTTPS access to the dashboard (optional) |
---
## Hardware Requirements
- A Linux server with **at least two Ethernet NICs**:
- One NIC facing your ISP modem/ONT (WAN)
- One NIC facing your internal switch (LAN)
- A Linux server with **at least two Ethernet NICs**
- One NIC connected to your ISP modem or ONT (WAN)
- One NIC connected to your internal switch (LAN)
---
For manual configuration and command-line usage without the dashboard, see [USAGE.md](routlin/USAGE.md).
For command-line usage without the dashboard, see [ADMINISTRATORS_GUIDE.md](ADMINISTRATORS_GUIDE.md).