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-05-25 01:04:47 -04:00
parent a4652866c3
commit 27eaea3d73
19 changed files with 602 additions and 427 deletions
Download patch file Download diff file Expand all files Collapse all files

19
routlin/USAGE.md
View file

@ -24,7 +24,7 @@ All configuration lives in two JSON files. Edit these to match your network befo
| `.dashboard-last-run` | Epoch timestamp of the last timer execution. |
| `.dashboard-lock` | PID lock file preventing concurrent timer runs. |
| `.dashboard-pending` | Changes held back when Apply on Save is disabled; flushed to `.dashboard-queue` when Apply Now is clicked. |
| `.status` | JSON health check results written by `core.py --apply`, `core.py --status`, and the `routlin-status-check` timer (every 5 minutes). Read by the dashboard to display problem alerts. |
| `.health` | JSON health check results written by `core.py --apply`, `core.py --status`, and the `routlin-health-check` timer (every 5 minutes). Read by the dashboard to display problem alerts. |
| `.dns-metrics` | Cumulative lifetime DNS metrics across all VLAN instances. Created and updated each time `--view-metrics` is run. |
| `.ddns-last-ip-*` | Cached public IP per DDNS provider. Managed by `ddns.py`. |
| `.ddns-last-service` | Tracks IP-check service rotation. Managed by `ddns.py`. |
@ -35,14 +35,14 @@ All configuration lives in two JSON files. Edit these to match your network befo
### 1. Edit Core Configuration (`core.json`)
Edit the top-level `general` block:
Edit the top-level `network_interfaces` block:
- Set `wan_interface` to the name of your WAN-facing NIC (e.g. `eno2`). Run `ip link` to find it.
Edit the top-level blocks:
- Set `upstream_dns.upstream_servers` to your preferred DNS resolvers (e.g. `1.1.1.1`, `8.8.8.8`)
- Add blocklist sources under `blocklists` with a name, URL, and format for each (e.g. OISD, Hagezi)
- Add blocklist sources under `dns_blocking.blocklists` with a name, URL, and format for each (e.g. OISD, Hagezi)
- Add entries to `host_overrides` for any local hostnames that should resolve to a specific IP (e.g. a DDNS hostname pointing to an internal server)
- Add entries to `port_forwarding` for any services that should be reachable from the internet (specify protocol, external port, destination IP, and destination port)
- Add entries to `banned_ips` to block traffic from specific IPs or networks (see below)
@ -179,7 +179,7 @@ Configure mDNS reflection with the top-level `mdns_reflection` block in `core.js
```bash
sudo python3 install.py # Install required packages; optionally set up dashboard and HTTPS
sudo python3 core.py --apply # Apply VLANs, DHCP, DNS, firewall, RADIUS, mDNS, timers
sudo python3 core.py --update-blocklists # Download and apply blocklists
sudo python3 dns-blocklists.py # Download and apply blocklists
```
Optional (if DDNS is desired):
@ -224,19 +224,26 @@ Commands that modify system state require `sudo`. Read-only commands do not.
```
sudo python3 core.py --apply # Apply full config: networkd, dnsmasq, nftables, RADIUS, mDNS, timers, boot service; runs health checks at end
sudo python3 core.py --apply --dry-run # Preview --apply actions without making changes
sudo python3 core.py --update-blocklists # Download and merge blocklists, then --apply
sudo python3 core.py --disable # Revert to network client (interactive wizard)
sudo python3 core.py --disable --dry-run # Preview --disable wizard without making changes
sudo python3 core.py --reset-leases # Stop dnsmasq, delete all lease files, restart (forces devices to re-acquire)
sudo python3 core.py --reset-leases VLAN # Reset leases for a specific VLAN only (e.g. trusted, iot, guest)
python3 core.py --status # Service status, config checks, and log alerts for all managed components; writes .status
python3 core.py --status # Service status, config checks, and log alerts for all managed components; writes .health
python3 core.py --view-configs # Active per-VLAN dnsmasq config files
python3 core.py --view-leases # Active DHCP leases across all VLANs with VLAN, type, and description
python3 core.py --view-rules # Active nftables ruleset
python3 core.py --view-metrics # Lifetime DNS metrics across all VLAN instances
```
### dns-blocklists.py
```
sudo python3 dns-blocklists.py
```
Downloads every blocklist referenced by at least one VLAN, merges them into per-combination conf files, then calls `core.py --apply` to reload dnsmasq instances. Run this after initial deployment and any time you add or change blocklist sources. The daily `systemd` timer installed by `core.py --apply` runs this automatically.
### create_vpn_peer.py
Does not require `sudo`. Requires `wireguard-tools` (`wg` must be on PATH) and a prior `core.py --apply` to generate the server keypair.

140
routlin/core.json
View file

@ -1,11 +1,8 @@
{
"general": {
"network_interfaces": {
"wan_interface": "eno2",
"lan_interface": "enp6s0",
"log_max_kb": 1024,
"log_errors_only": false,
"dnsmasq_log_queries": false,
"daily_execute_time_24hr_local": "02:30"
"dnsmasq_log_queries": false
},
"upstream_dns": {
"strict_order": false,
@ -72,29 +69,6 @@
"ip": "192.168.1.20"
}
],
"blocklists": [
{
"name": "oisd-big",
"description": "OISD Big (ads, phishing, malware, telemetry)",
"save_as": "oisd-big.conf",
"url": "https://big.oisd.nl/dnsmasq2",
"format": "dnsmasq"
},
{
"name": "hagezi-light",
"description": "Hagezi Light (ads, tracking, metrics, badware)",
"save_as": "hagezi-light.conf",
"url": "https://raw.githubusercontent.com/hagezi/dns-blocklists/main/dnsmasq/light.txt",
"format": "dnsmasq"
},
{
"name": "hagezi-pro-plus",
"description": "Hagezi Pro Plus (ads, tracking, porn, gambling)",
"save_as": "hagezi-pro-plus.conf",
"url": "https://raw.githubusercontent.com/hagezi/dns-blocklists/main/dnsmasq/pro.plus.txt",
"format": "dnsmasq"
}
],
"inter_vlan_exceptions": [
{
"description": "IoT TV -> Plex",
@ -724,22 +698,100 @@
}
],
"ip_check_services": [
{"type": "http", "url": "https://api.ipify.org"},
{"type": "http", "url": "https://ifconfig.me/ip"},
{"type": "http", "url": "https://icanhazip.com"},
{"type": "http", "url": "https://api4.my-ip.io/ip"},
{"type": "http", "url": "https://ipv4.icanhazip.com"},
{"type": "http", "url": "https://checkip.amazonaws.com"},
{"type": "http", "url": "https://1.1.1.1/cdn-cgi/trace"},
{"type": "http", "url": "https://ipinfo.io/ip"},
{"type": "http", "url": "https://ipecho.net/plain"},
{"type": "http", "url": "https://ident.me"},
{"type": "http", "url": "https://myip.dnsomatic.com"},
{"type": "http", "url": "https://wtfismyip.com/text"},
{"type": "dig", "url": "@1.1.1.1 ch txt whoami.cloudflare"},
{"type": "dig", "url": "whoami.akamai.net @ns1-1.akamaitech.net"},
{"type": "dig", "url": "-4 TXT o-o.myaddr.l.google.com @ns1.google.com"},
{"type": "dig", "url": "-4 @ns3.cloudflare.com whoami.cloudflare.com txt"}
{
"type": "http",
"url": "https://api.ipify.org"
},
{
"type": "http",
"url": "https://ifconfig.me/ip"
},
{
"type": "http",
"url": "https://icanhazip.com"
},
{
"type": "http",
"url": "https://api4.my-ip.io/ip"
},
{
"type": "http",
"url": "https://ipv4.icanhazip.com"
},
{
"type": "http",
"url": "https://checkip.amazonaws.com"
},
{
"type": "http",
"url": "https://1.1.1.1/cdn-cgi/trace"
},
{
"type": "http",
"url": "https://ipinfo.io/ip"
},
{
"type": "http",
"url": "https://ipecho.net/plain"
},
{
"type": "http",
"url": "https://ident.me"
},
{
"type": "http",
"url": "https://myip.dnsomatic.com"
},
{
"type": "http",
"url": "https://wtfismyip.com/text"
},
{
"type": "dig",
"url": "@1.1.1.1 ch txt whoami.cloudflare"
},
{
"type": "dig",
"url": "whoami.akamai.net @ns1-1.akamaitech.net"
},
{
"type": "dig",
"url": "-4 TXT o-o.myaddr.l.google.com @ns1.google.com"
},
{
"type": "dig",
"url": "-4 @ns3.cloudflare.com whoami.cloudflare.com txt"
}
]
},
"dns_blocking": {
"general": {
"log_max_kb": 1024,
"log_errors_only": false,
"daily_execute_time_24hr_local": "02:30"
},
"blocklists": [
{
"name": "oisd-big",
"description": "OISD Big (ads, phishing, malware, telemetry)",
"save_as": "oisd-big.conf",
"url": "https://big.oisd.nl/dnsmasq2",
"format": "dnsmasq"
},
{
"name": "hagezi-light",
"description": "Hagezi Light (ads, tracking, metrics, badware)",
"save_as": "hagezi-light.conf",
"url": "https://raw.githubusercontent.com/hagezi/dns-blocklists/main/dnsmasq/light.txt",
"format": "dnsmasq"
},
{
"name": "hagezi-pro-plus",
"description": "Hagezi Pro Plus (ads, tracking, porn, gambling)",
"save_as": "hagezi-pro-plus.conf",
"url": "https://raw.githubusercontent.com/hagezi/dns-blocklists/main/dnsmasq/pro.plus.txt",
"format": "dnsmasq"
}
]
}
}

217
routlin/core.py
View file

@ -74,7 +74,6 @@ Validation:
Usage:
sudo python3 core.py --apply Apply config fast: restart running services only
sudo python3 core.py --update-blocklists Refresh blocklists and apply (used by timer)
sudo python3 core.py --status Show service and timer status
sudo python3 core.py --view-configs Show active per-VLAN dnsmasq config files
sudo python3 core.py --view-leases Show active DHCP leases
@ -94,8 +93,6 @@ import re
import subprocess
import sys
import time
import urllib.request
import urllib.error
import argparse
from datetime import datetime
from pathlib import Path
@ -128,11 +125,11 @@ DASHB_TIMER_FILE = SYSTEMD_DIR / f"{DASHB_TIMER_NAME}.timer"
DASHB_TIMER_SVC_FILE = SYSTEMD_DIR / f"{DASHB_TIMER_NAME}.service"
DASHB_TIMER_INTERVAL_SEC = 60
DASHB_QUEUE_FILE = SCRIPT_DIR / ".dashboard-queue"
STATUS_TIMER_NAME = f"{PRODUCT_NAME}-status-check"
STATUS_TIMER_FILE = SYSTEMD_DIR / f"{STATUS_TIMER_NAME}.timer"
STATUS_TIMER_SVC_FILE = SYSTEMD_DIR / f"{STATUS_TIMER_NAME}.service"
STATUS_TIMER_INTERVAL_SEC = 300
STATUS_FILE = SCRIPT_DIR / ".status"
HEALTH_TIMER_NAME = f"{PRODUCT_NAME}-health-check"
HEALTH_TIMER_FILE = SYSTEMD_DIR / f"{HEALTH_TIMER_NAME}.timer"
HEALTH_TIMER_SVC_FILE = SYSTEMD_DIR / f"{HEALTH_TIMER_NAME}.service"
HEALTH_TIMER_INTERVAL_SEC = 300
HEALTH_FILE = SCRIPT_DIR / ".health"
DASHB_DONE_FILE = SCRIPT_DIR / ".dashboard-done"
DASHB_LAST_RUN_FILE = SCRIPT_DIR / ".dashboard-last-run"
DASHB_LOCK_FILE = SCRIPT_DIR / ".dashboard-lock"
@ -463,132 +460,6 @@ def blocklists_available(data):
combos.add(combo_hash(names))
return any(merged_path(h).exists() for h in combos)
def parse_dnsmasq_format(content):
domains = set()
for ln in content.splitlines():
ln = ln.strip()
if not ln or ln.startswith("#"):
continue
if ln.startswith("local=/"):
domain = ln.removeprefix("local=/").rstrip("/")
if domain:
domains.add(domain)
elif ln.startswith("address=/"):
parts = ln.removeprefix("address=/").split("/")
if parts:
domains.add(parts[0])
return domains
def parse_hosts_format(content):
domains = set()
for ln in content.splitlines():
ln = ln.strip()
if not ln or ln.startswith("#"):
continue
parts = ln.split()
if len(parts) >= 2:
domains.add(parts[1])
return domains
def parse_blocklist(content, fmt):
if fmt == "dnsmasq":
return parse_dnsmasq_format(content)
return parse_hosts_format(content)
def build_merged_conf(domains, bl_names):
"""Build a merged dnsmasq conf blocking all domains and their subdomains."""
lines = [
"# Generated by core.py -- do not edit manually.",
f"# Blocklist combination: {', '.join(sorted(bl_names))}",
f"# Merged: {len(domains):,} unique domains.",
"#",
"# Blocks domain and all subdomains via local=/domain/ syntax.",
"",
]
for domain in sorted(domains):
lines.append(f"local=/{domain}/")
return "\n".join(lines)
def download_all_blocklists(data):
"""
Download every blocklist referenced by at least one VLAN.
Returns dict: name -> (content_str, entry) or (None, entry) on failure.
"""
bl_library = {bl["name"]: bl for bl in data.get("blocklists", [])}
needed = set()
for vlan in data["vlans"]:
needed.update(vlan.get("use_blocklists", []))
results = {}
for name in needed:
entry = bl_library[name]
url = entry["url"]
try:
req = urllib.request.Request(url, headers={"User-Agent": "dns-dhcp.py/1.0"})
with urllib.request.urlopen(req, timeout=30) as r:
content = r.read().decode("utf-8", errors="ignore")
log.info(f"Downloaded: {entry['description']} ({len(content):,} bytes)")
results[name] = (content, entry)
except Exception as e:
log.error(f"Failed to download '{entry['description']}' from {url}: {e}")
results[name] = (None, entry)
return results
def update_blocklists(data):
"""
Download all referenced blocklists, build per-combo merged files,
and clean up stale merged files. Returns active hashes set.
"""
BLOCKLIST_DIR.mkdir(exist_ok=True)
log.info("Downloading blocklists...")
downloaded = download_all_blocklists(data)
# Parse domains per blocklist name; save raw files
domains_by_name = {}
for name, (content, entry) in downloaded.items():
if content is None:
log.error(f"Blocklist '{name}' failed to download -- it will be skipped.")
domains_by_name[name] = set()
else:
(BLOCKLIST_DIR / entry["save_as"]).write_text(content)
domains = parse_blocklist(content, entry.get("format", "dnsmasq"))
log.info(f"Parsed {len(domains):,} domains from '{name}'")
domains_by_name[name] = domains
# Build one merged file per unique combo
active_hashes = set()
combos = {}
for vlan in data["vlans"]:
names = frozenset(vlan.get("use_blocklists", []))
if names:
h = combo_hash(names)
combos[h] = names
for h, names in combos.items():
combo_domains = set()
for name in names:
combo_domains.update(domains_by_name.get(name, set()))
merged = build_merged_conf(combo_domains, names)
merged_path(h).write_text(merged)
active_hashes.add(h)
log.info(
f"Merged [{h}] ({', '.join(sorted(names))}): "
f"{len(combo_domains):,} unique domains."
)
# Remove stale merged files (hashes no longer in active combos)
for f in BLOCKLIST_DIR.glob("merged-*.conf"):
h = f.stem.removeprefix("merged-")
if h not in active_hashes:
f.unlink()
log.info(f"Removed stale merged file: {f.name}")
# Return True if all blocklists downloaded successfully
any_failed = any(content is None for content, _ in downloaded.values())
return not any_failed
# ===================================================================
# Build per-VLAN dnsmasq config
# ===================================================================
@ -608,7 +479,7 @@ def _wan_has_ipv6(iface):
def build_vlan_dnsmasq_conf(vlan, data, iface):
"""Generate the complete dnsmasq config for one VLAN instance."""
dns_cfg = data.get("upstream_dns", {})
general = data.get("general", {})
general = data.get("network_interfaces", {})
overrides = [o for o in data.get("host_overrides", []) if o.get("enabled") is True]
name = vlan["name"]
d = vlan.get("dhcp_information", {})
@ -714,7 +585,7 @@ def build_vlan_dnsmasq_conf(vlan, data, iface):
line("no-resolv")
if dns_cfg.get("strict_order"):
line("strict-order")
wan = data["general"]["wan_interface"]
wan = data["network_interfaces"]["wan_interface"]
wan_has_ipv6 = _wan_has_ipv6(wan)
for srv in dns_cfg.get("upstream_servers", []):
if ":" in srv and not wan_has_ipv6:
@ -737,7 +608,7 @@ def build_vlan_dnsmasq_conf(vlan, data, iface):
line(f"conf-file={bl_file}")
line()
elif bl_names:
line("# Blocklist not yet downloaded -- run --update-blocklists to fetch")
line("# Blocklist not yet downloaded -- run: sudo python3 dns-blocklists.py")
line()
return "\n".join(L)
@ -1201,10 +1072,9 @@ def parse_time_to_calendar(time_str):
return f"*-*-* {hh.zfill(2)}:{mm.zfill(2)}:00"
def install_timer(data):
general = data.get("general", {})
general = data.get("dns_blocking", {}).get("general", {})
execute_time = general.get("daily_execute_time_24hr_local", "02:30")
on_calendar = parse_time_to_calendar(execute_time)
script_path = Path(__file__).resolve()
timer_content = "\n".join([
"# Generated by core.py -- do not edit manually.",
@ -1221,17 +1091,18 @@ def install_timer(data):
"",
])
blocklist_script = SCRIPT_DIR / "dns-blocklists.py"
service_content = "\n".join([
"# Generated by core.py -- do not edit manually.",
"",
"[Unit]",
"Description=core.py daily blocklist refresh",
"Description=Daily blocklist refresh",
"After=network-online.target",
"Wants=network-online.target",
"",
"[Service]",
"Type=oneshot",
f"ExecStart=/usr/bin/python3 {script_path} --update-blocklists",
f"ExecStart=/usr/bin/python3 {blocklist_script}",
"",
])
@ -1534,7 +1405,7 @@ def banned_ip_sets(data):
# ===================================================================
def build_nft_config(data, dry_run=False):
wan = data["general"]["wan_interface"]
wan = data["network_interfaces"]["wan_interface"]
# Exclude WG VLANs whose interface is not up -- nft rejects rules that
# reference non-existent interfaces, which would leave no firewall at all.
vlans = [v for v in data["vlans"]
@ -2232,8 +2103,8 @@ def disable_avahi():
def show_status(data):
import status as _status
_status.print_table(_status.run_and_write(data))
import health as _health
_health.print_table(_health.run_and_write(data))
def show_configs(data):
for vlan in data["vlans"]:
@ -2550,9 +2421,9 @@ def show_metrics(data):
def stop_instances(data):
"""Remove timers and stop all per-VLAN instances (config files preserved)."""
_remove_timers(
names=[BLIST_TIMER_NAME, DASHB_TIMER_NAME, STATUS_TIMER_NAME, DDNS_TIMER_NAME],
timer_files=[BLIST_TIMER_FILE, DASHB_TIMER_FILE, STATUS_TIMER_FILE, DDNS_TIMER_FILE],
svc_files=[BLIST_TIMER_SVC_FILE, DASHB_TIMER_SVC_FILE, STATUS_TIMER_SVC_FILE, DDNS_TIMER_SVC_FILE],
names=[BLIST_TIMER_NAME, DASHB_TIMER_NAME, HEALTH_TIMER_NAME, DDNS_TIMER_NAME],
timer_files=[BLIST_TIMER_FILE, DASHB_TIMER_FILE, HEALTH_TIMER_FILE, DDNS_TIMER_FILE],
svc_files=[BLIST_TIMER_SVC_FILE, DASHB_TIMER_SVC_FILE, HEALTH_TIMER_SVC_FILE, DDNS_TIMER_SVC_FILE],
daemon_reload=True,
)
print()
@ -2746,7 +2617,7 @@ def _dry_run_conflicting_services(data):
def _dry_run_blocklists(data):
print("Blocklists (dry-run) ================================================")
for entry in data.get("blocklists", []):
for entry in data.get("dns_blocking", {}).get("blocklists", []):
print(f" Would download: {entry['description']}")
print(f" URL: {entry['url']}")
seen = {}
@ -2763,7 +2634,7 @@ def _dry_run_blocklists(data):
def _dry_run_timer(data):
print("Timer (dry-run) =====================================================")
general = data.get("general", {})
general = data.get("dns_blocking", {}).get("general", {})
execute_time = general.get("daily_execute_time_24hr_local", "02:30")
for path, label in [(BLIST_TIMER_FILE, "timer unit"), (BLIST_TIMER_SVC_FILE, "service unit")]:
action = "update" if path.exists() else "create and enable"
@ -3133,7 +3004,7 @@ def cmd_apply(data, dry_run=False):
print("dnsmasq instances ===================================================")
if not blocklists_available(data):
print(" NOTE: No merged blocklist files found -- blocklist rules will be absent.")
print(" Run --update-blocklists to download and merge blocklists.")
print(" Run: sudo python3 dns-blocklists.py")
apply_dnsmasq_instances(data, start_if_needed=True)
print()
@ -3147,12 +3018,12 @@ def cmd_apply(data, dry_run=False):
print("Interval timers =====================================================")
# build parallel lists; dashboard timer only installed when queue file exists
t_names = [STATUS_TIMER_NAME]
t_files = [STATUS_TIMER_FILE]
s_files = [STATUS_TIMER_SVC_FILE]
t_names = [HEALTH_TIMER_NAME]
t_files = [HEALTH_TIMER_FILE]
s_files = [HEALTH_TIMER_SVC_FILE]
t_descs = ["Router status health check"]
t_execs = [f"/usr/bin/python3 {SCRIPT_DIR / 'status.py'}"]
t_intervals = [STATUS_TIMER_INTERVAL_SEC]
t_execs = [f"/usr/bin/python3 {SCRIPT_DIR / 'health.py'}"]
t_intervals = [HEALTH_TIMER_INTERVAL_SEC]
if DASHB_QUEUE_FILE.exists():
t_names += [DASHB_TIMER_NAME]
t_files += [DASHB_TIMER_FILE]
@ -3204,24 +3075,8 @@ def cmd_apply(data, dry_run=False):
print("Done.")
import status as _status
_status.print_table(_status.run_and_write(data))
def cmd_update_blocklists(data):
"""--update-blocklists: download and merge blocklists. On success, call
cmd_apply to reload dnsmasq instances with the new blocklists.
"""
check_root()
print("Updating blocklists =================================================")
success = update_blocklists(data)
print()
if success:
print("Applying updated configs ============================================")
cmd_apply(data)
else:
print("WARNING: Blocklist update had errors -- skipping --apply.")
print(" Existing merged files (if any) are unchanged.")
import health as _health
_health.print_table(_health.run_and_write(data))
def main():
@ -3231,7 +3086,6 @@ def main():
epilog=(
"examples:\n"
" sudo python3 core.py --apply Apply full config (idempotent, safe to re-run)\n"
" sudo python3 core.py --update-blocklists Refresh blocklists and apply\n"
" sudo python3 core.py --status Show service and timer status\n"
" sudo python3 core.py --view-configs Show active per-VLAN dnsmasq config files\n"
" sudo python3 core.py --view-leases Show active DHCP leases\n"
@ -3245,9 +3099,8 @@ def main():
" sudo python3 core.py --disable --dry-run\n"
)
)
parser.add_argument("--apply", action="store_true", help="Apply full config: services, networkd, dnsmasq, nftables, timer, boot service")
parser.add_argument("--update-blocklists", action="store_true", help="Refresh blocklists and apply (used by timer)")
parser.add_argument("--dry-run", action="store_true", help="Preview all actions without making changes (combine with --apply or --disable)")
parser.add_argument("--apply", action="store_true", help="Apply full config: services, networkd, dnsmasq, nftables, timer, boot service")
parser.add_argument("--dry-run", action="store_true", help="Preview all actions without making changes (combine with --apply or --disable)")
parser.add_argument("--status", action="store_true", help="Show service and timer status")
parser.add_argument("--view-configs", action="store_true", help="Show active per-VLAN dnsmasq config files")
parser.add_argument("--view-leases", action="store_true", help="Show active DHCP leases")
@ -3260,9 +3113,7 @@ def main():
args = parser.parse_args()
update_blocklists_flag = getattr(args, "update_blocklists", False)
if not any([args.apply, update_blocklists_flag,
if not any([args.apply,
args.dry_run, args.status, args.view_configs, args.view_leases,
args.view_rules, args.disable, args.view_metrics,
args.reset_leases]):
@ -3281,7 +3132,7 @@ def main():
print(f" - {e}", file=sys.stderr)
sys.exit(1)
general = data.get("general", {})
general = data.get("dns_blocking", {}).get("general", {})
setup_logging(
general.get("log_max_kb", 1024),
general.get("log_errors_only", False)
@ -3318,10 +3169,6 @@ def main():
cmd_disable(data, dry_run=args.dry_run)
return
if update_blocklists_flag:
cmd_update_blocklists(data)
return
if args.apply:
cmd_apply(data, dry_run=args.dry_run)
return

258
routlin/dns-blocklists.py Normal file
View file

@ -0,0 +1,258 @@
#!/usr/bin/env python3
"""
dns-blocklists.py -- Download and merge DNS blocklists defined in core.json.
Reads the blocklists library from core.json, downloads every blocklist referenced
by at least one VLAN, merges them into per-combo conf files (one per unique
combination of blocklist names), then sends SIGHUP to each running dnsmasq
instance so it reloads its config without restarting.
Usage:
sudo python3 dns-blocklists.py
"""
import hashlib
import json
import logging
import os
import subprocess
import sys
import urllib.request
import urllib.error
from pathlib import Path
PRODUCT_NAME = "routlin"
SCRIPT_DIR = Path(__file__).parent
CONFIG_FILE = SCRIPT_DIR / "core.json"
BLOCKLIST_DIR = SCRIPT_DIR / "blocklists"
LOG_FILE = SCRIPT_DIR / "dns-blocklists.log"
log = None
def _chown_to_script_dir_owner(path):
try:
stat = SCRIPT_DIR.stat()
os.chown(path, stat.st_uid, stat.st_gid)
except Exception:
pass
def setup_logging(max_kb, errors_only):
global log
try:
if LOG_FILE.exists() and LOG_FILE.stat().st_size > max_kb * 1024:
LOG_FILE.write_text("")
if not LOG_FILE.exists():
LOG_FILE.touch()
_chown_to_script_dir_owner(LOG_FILE)
file_handler = logging.FileHandler(LOG_FILE)
except PermissionError:
print(f"WARNING: Cannot write to {LOG_FILE} (permission denied). "
f"Run with sudo or fix ownership: sudo chown $USER {LOG_FILE}")
file_handler = None
level = logging.ERROR if errors_only else logging.INFO
handlers = [logging.StreamHandler(sys.stdout)]
if file_handler:
handlers.insert(0, file_handler)
logging.basicConfig(
level=level,
format="%(asctime)s %(levelname)-8s %(message)s",
datefmt="%Y-%m-%d %H:%M:%S",
handlers=handlers,
)
log = logging.getLogger("dns-blocklists")
def die(msg):
print(f"ERROR: {msg}", file=sys.stderr)
sys.exit(1)
def check_root():
if os.geteuid() != 0:
die("This script must be run as root (sudo).")
def load_config():
if not CONFIG_FILE.exists():
die(f"Config file not found: {CONFIG_FILE}")
with open(CONFIG_FILE) as f:
data = json.load(f)
if not data.get("vlans"):
die("No vlans defined in core.json.")
return data
def combo_hash(names):
key = ",".join(sorted(names))
return hashlib.sha256(key.encode()).hexdigest()[:8]
def merged_path(h):
return BLOCKLIST_DIR / f"merged-{h}.conf"
def parse_dnsmasq_format(content):
domains = set()
for ln in content.splitlines():
ln = ln.strip()
if not ln or ln.startswith("#"):
continue
if ln.startswith("local=/"):
domain = ln.removeprefix("local=/").rstrip("/")
if domain:
domains.add(domain)
elif ln.startswith("address=/"):
parts = ln.removeprefix("address=/").split("/")
if parts:
domains.add(parts[0])
return domains
def parse_hosts_format(content):
domains = set()
for ln in content.splitlines():
ln = ln.strip()
if not ln or ln.startswith("#"):
continue
parts = ln.split()
if len(parts) >= 2:
domains.add(parts[1])
return domains
def parse_blocklist(content, fmt):
if fmt == "dnsmasq":
return parse_dnsmasq_format(content)
return parse_hosts_format(content)
def build_merged_conf(domains, bl_names):
lines = [
"# Generated by dns-blocklists.py -- do not edit manually.",
f"# Blocklist combination: {', '.join(sorted(bl_names))}",
f"# Merged: {len(domains):,} unique domains.",
"#",
"# Blocks domain and all subdomains via local=/domain/ syntax.",
"",
]
for domain in sorted(domains):
lines.append(f"local=/{domain}/")
return "\n".join(lines)
def download_all_blocklists(data):
bl_library = {bl["name"]: bl for bl in data.get("dns_blocking", {}).get("blocklists", [])}
needed = set()
for vlan in data["vlans"]:
needed.update(vlan.get("use_blocklists", []))
results = {}
for name in needed:
entry = bl_library[name]
url = entry["url"]
try:
req = urllib.request.Request(url, headers={"User-Agent": "dns-blocklists.py/1.0"})
with urllib.request.urlopen(req, timeout=30) as r:
content = r.read().decode("utf-8", errors="ignore")
log.info(f"Downloaded: {entry['description']} ({len(content):,} bytes)")
results[name] = (content, entry)
except Exception as e:
log.error(f"Failed to download '{entry['description']}' from {url}: {e}")
results[name] = (None, entry)
return results
def update_blocklists(data):
BLOCKLIST_DIR.mkdir(exist_ok=True)
log.info("Downloading blocklists...")
downloaded = download_all_blocklists(data)
domains_by_name = {}
for name, (content, entry) in downloaded.items():
if content is None:
log.error(f"Blocklist '{name}' failed to download -- it will be skipped.")
domains_by_name[name] = set()
else:
(BLOCKLIST_DIR / entry["save_as"]).write_text(content)
domains = parse_blocklist(content, entry.get("format", "dnsmasq"))
log.info(f"Parsed {len(domains):,} domains from '{name}'")
domains_by_name[name] = domains
active_hashes = set()
combos = {}
for vlan in data["vlans"]:
names = frozenset(vlan.get("use_blocklists", []))
if names:
h = combo_hash(names)
combos[h] = names
for h, names in combos.items():
combo_domains = set()
for name in names:
combo_domains.update(domains_by_name.get(name, set()))
merged = build_merged_conf(combo_domains, names)
merged_path(h).write_text(merged)
active_hashes.add(h)
log.info(
f"Merged [{h}] ({', '.join(sorted(names))}): "
f"{len(combo_domains):,} unique domains."
)
for f in BLOCKLIST_DIR.glob("merged-*.conf"):
h = f.stem.removeprefix("merged-")
if h not in active_hashes:
f.unlink()
log.info(f"Removed stale merged file: {f.name}")
any_failed = any(content is None for content, _ in downloaded.values())
return not any_failed
def reload_dnsmasq_instances():
"""Send SIGHUP to every active dnsmasq-routlin-* instance so it reloads
its conf-file inclusions without restarting. No DNS or DHCP interruption."""
result = subprocess.run(
["systemctl", "list-units", "--state=active", "--no-legend", "--plain",
f"dnsmasq-{PRODUCT_NAME}-*.service"],
capture_output=True, text=True,
)
units = [line.split()[0] for line in result.stdout.splitlines() if line.strip()]
if not units:
print(" No active dnsmasq instances found.")
return
for unit in units:
r = subprocess.run(["systemctl", "kill", "--signal=SIGHUP", unit],
capture_output=True, text=True)
if r.returncode == 0:
print(f" Reloaded: {unit}")
else:
print(f" WARNING: Failed to reload {unit}: {r.stderr.strip()}")
def main():
check_root()
data = load_config()
general = data.get("dns_blocking", {}).get("general", {})
setup_logging(
general.get("log_max_kb", 1024),
general.get("log_errors_only", False),
)
print("Updating blocklists =================================================")
success = update_blocklists(data)
print()
if success:
print("Reloading dnsmasq instances =========================================")
reload_dnsmasq_instances()
else:
print("WARNING: Blocklist update had errors -- skipping reload.")
print(" Existing merged files (if any) are unchanged.")
if __name__ == "__main__":
main()

26
routlin/status.py → routlin/health.py
View file

@ -1,11 +1,11 @@
"""
status.py -- System health checks for Routlin.
health.py -- System health checks for Routlin.
Reads core.json, checks services, configuration files, and logs, then writes
.status JSON. Imported by core.py; also runnable standalone.
.health JSON. Imported by core.py; also runnable standalone.
Public API:
run_and_write(data) -> dict run all checks, write .status, return dict
run_and_write(data) -> dict run all checks, write .health, return dict
print_table(status: dict) render the CLI service table from status dict
"""
import hashlib
@ -28,7 +28,7 @@ from validation import derive_interface, derive_vlan_id, is_wg
PRODUCT_NAME = "routlin"
SCRIPT_DIR = Path(__file__).parent
STATUS_FILE = SCRIPT_DIR / ".status"
HEALTH_FILE = SCRIPT_DIR / ".health"
CONFIG_FILE = SCRIPT_DIR / "core.json"
BLOCKLIST_DIR = SCRIPT_DIR / "blocklists"
DNSMASQ_CONF_DIR = Path(f"/etc/dnsmasq-{PRODUCT_NAME}")
@ -44,7 +44,7 @@ RADIUS_CLIENTS_CONF = Path("/etc/freeradius/3.0/clients.conf")
RADIUS_USERS_FILE = Path("/etc/freeradius/3.0/users")
BLIST_TIMER_NAME = f"{PRODUCT_NAME}-dns-blocklist-update"
DASHB_TIMER_NAME = f"{PRODUCT_NAME}-dashboard-queue"
STATUS_TIMER_NAME = f"{PRODUCT_NAME}-status-check"
HEALTH_TIMER_NAME = f"{PRODUCT_NAME}-health-check"
DDNS_TIMER_NAME = f"{PRODUCT_NAME}-ddns-update"
DASHB_QUEUE_FILE = SCRIPT_DIR / ".dashboard-queue"
NAT_SERVICE_NAME = f"{PRODUCT_NAME}-nat"
@ -166,8 +166,8 @@ def check_services(data):
"expected_enabled": "enabled",
"severity": "error"})
units.append({"id": f"{STATUS_TIMER_NAME}.timer",
"name": f"{STATUS_TIMER_NAME}.timer",
units.append({"id": f"{HEALTH_TIMER_NAME}.timer",
"name": f"{HEALTH_TIMER_NAME}.timer",
"expected_active": "active", "expected_enabled": "enabled",
"severity": "warning"})
@ -542,7 +542,7 @@ def check_configurations(data):
pass
# --- Blocklist file freshness ---
blocklists = data.get("blocklists", [])
blocklists = data.get("dns_blocking", {}).get("blocklists", [])
if blocklists:
combos = {}
for vlan in vlans:
@ -557,13 +557,13 @@ def check_configurations(data):
results.append(_problem(
f"blocklist_{h}", f"blocklist ({label})", "warning",
f"Merged blocklist file for '{label}' does not exist.",
"Run `sudo python3 core.py --update-blocklists` to download blocklists."))
"Run `sudo python3 dns-blocklists.py` to download blocklists."))
elif now - path.stat().st_mtime > BLOCKLIST_STALE_SECS:
age_h = int((now - path.stat().st_mtime) / 3600)
results.append(_problem(
f"blocklist_{h}", f"blocklist ({label})", "warning",
f"Merged blocklist for '{label}' is {age_h}h old (threshold 36h).",
"Run `sudo python3 core.py --update-blocklists` to refresh."))
"Run `sudo python3 dns-blocklists.py` to refresh."))
else:
results.append(_ok(f"blocklist_{h}", f"blocklist ({label})"))
@ -712,7 +712,7 @@ def _next_blocklist_update():
# ===================================================================
def run_and_write(data):
"""Run all checks, write .status atomically, return the status dict."""
"""Run all checks, write .health atomically, return the status dict."""
status = {
"checked_at": datetime.now().strftime("%Y-%m-%dT%H:%M:%S"),
"services": check_services(data),
@ -720,9 +720,9 @@ def run_and_write(data):
"logs": check_logs(data),
"next_blocklist_update": _next_blocklist_update(),
}
tmp = STATUS_FILE.with_suffix(".tmp")
tmp = HEALTH_FILE.with_suffix(".tmp")
tmp.write_text(json.dumps(status, indent=2))
tmp.replace(STATUS_FILE)
tmp.replace(HEALTH_FILE)
return status

4
routlin/install.py
View file

@ -30,7 +30,7 @@ DASHB_DONE_FILE = SCRIPT_DIR / ".dashboard-done"
DASHB_LAST_RUN_FILE = SCRIPT_DIR / ".dashboard-last-run"
DASHB_LOCK_FILE = SCRIPT_DIR / ".dashboard-lock"
DASHB_PENDING_FILE = SCRIPT_DIR / ".dashboard-pending"
STATUS_FILE = SCRIPT_DIR / ".status"
HEALTH_FILE = SCRIPT_DIR / ".health"
# ===================================================================
@ -331,7 +331,7 @@ def setup_docker_compose(reuse_config=False):
def create_dotfiles():
for f in (DASHB_QUEUE_FILE, DASHB_DONE_FILE, DASHB_LAST_RUN_FILE, DASHB_LOCK_FILE, DASHB_PENDING_FILE, STATUS_FILE):
for f in (DASHB_QUEUE_FILE, DASHB_DONE_FILE, DASHB_LAST_RUN_FILE, DASHB_LOCK_FILE, DASHB_PENDING_FILE, HEALTH_FILE):
if not f.exists():
f.touch()
# chown to the routlin dir owner so the timer can write

20
routlin/validation.py
View file

@ -283,7 +283,7 @@ def derive_vlan_id(subnet, prefix):
def derive_interface(vlan, data):
"""Derive the interface name for a VLAN without mutating data."""
lan = data.get('general', {}).get('lan_interface', 'eth0')
lan = data.get('network_interfaces', {}).get('lan_interface', 'eth0')
if is_wg(vlan):
wg_vlans = [v for v in data.get('vlans', []) if is_wg(v)]
wg_sorted = sorted(
@ -312,7 +312,7 @@ def validate_config(data):
seen_listen_ports = {}
# Pre-compute per-VLAN vlan_ids and interface names without mutating data
_lan = data.get("general", {}).get("lan_interface", "eth0")
_lan = data.get("network_interfaces", {}).get("lan_interface", "eth0")
_all_vlans = data.get("vlans", [])
_derived_ids = [
derive_vlan_id(_v.get("subnet", ""), _v.get("subnet_mask", 24))
@ -336,13 +336,13 @@ def validate_config(data):
errors.append("upstream_dns.upstream_servers is missing or empty.")
# -- WAN / LAN interfaces --------------------------------------------------
gen = data.get("general", {})
gen = data.get("network_interfaces", {})
wan = gen.get("wan_interface", "")
lan = gen.get("lan_interface", "")
if not wan:
errors.append("general.wan_interface is missing or empty.")
errors.append("network_interfaces.wan_interface is missing or empty.")
if not lan:
errors.append("general.lan_interface is missing or empty.")
errors.append("network_interfaces.lan_interface is missing or empty.")
if wan and lan:
available_interfaces = set()
try:
@ -351,17 +351,17 @@ def validate_config(data):
pass
if available_interfaces:
if wan not in available_interfaces:
errors.append(f"general.wan_interface: '{wan}' does not exist on this system.")
errors.append(f"network_interfaces.wan_interface: '{wan}' does not exist on this system.")
if lan not in available_interfaces:
errors.append(f"general.lan_interface: '{lan}' does not exist on this system.")
errors.append(f"network_interfaces.lan_interface: '{lan}' does not exist on this system.")
if wan == lan:
errors.append(f"general.wan_interface and general.lan_interface must be different (both set to '{wan}').")
errors.append(f"network_interfaces.wan_interface and network_interfaces.lan_interface must be different (both set to '{wan}').")
# -- Blocklist library -----------------------------------------------------
blocklists_by_name = {}
for idx, bl in enumerate(data.get("blocklists", [])):
for idx, bl in enumerate(data.get("dns_blocking", {}).get("blocklists", [])):
name = bl.get("name", "")
label = f"blocklists[{idx}] '{name}'"
label = f"dns_blocking.blocklists[{idx}] '{name}'"
for field in ("name", "description", "save_as", "url", "format"):
if not bl.get(field):
errors.append(f"{label}: missing or empty field '{field}'.")