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.