The problem: it grew past “I just know”

For a while, the mental model of the network lived entirely in my head. That works until a switch port flaps, a VM migrates, or a device gets a new IP, and you find out about it by symptom rather than by signal — the “why is the Wi-Fi pod offline” question that turns into twenty minutes of SSHing into things to check link status one port at a time.

The fix was to stop treating the network as a black box and start treating it like the rest of my infrastructure: observable, documented, and — where it’s safe to do so — automatable.

A small internal webapp

The centerpiece is a small internal dashboard with a handful of tabs:

• Topology — a live, auto-generated map of the LAN: router, switches, and every device, drawn from an actual scan rather than a diagram someone has to remember to update.
• Graph — the same topology, but as an actual graph database (Neo4j) rebuilt from scratch every 15 minutes. It’s deliberately current-state only, not a history store — every sync wipes and rebuilds the graph, so a query always reflects what’s plugged in right now. The tab embeds the real Neo4j Browser so I can run ad-hoc Cypher queries against my own LAN (“what’s connected to this switch port,” “show me every device with no hostname”) instead of grepping through ARP tables.
• Monitoring — Grafana/Prometheus, for the metrics side of things.
• Switch — port status and traffic for the managed switches, without opening their web UIs.
• Syslog — the one that ended up mattering most in practice.

Syslog: making the logs actually watch something

Every host on the network already ships logs to a central syslog collector — hundreds of sources’ worth. The problem was that nothing was reading them. The answer to “why did the WiFi pod drop” was sitting in a switch’s log the whole time (a port link-down event), completely unwatched.

The Syslog tab adds two things on top of the raw collector: a searchable, multi-host log viewer (term/regex filters, time ranges — with hundreds of sources and a lot of history, filtering has to happen server-side, not in the browser), and user-defined notification rules. A small engine runs every minute, tails only the new bytes each watched log has grown by, matches them against the rules, and — on a match, respecting a per-rule cooldown so one flapping port doesn’t turn into a hundred pages — fires a webhook into Home Assistant, which turns it into a phone notification.

It’s a small feature, but it’s the difference between “the network told me something broke” and “I noticed something was broken.”

Giving Claude Code supervised hands on the network

The more interesting piece, for me, was building an MCP (Model Context Protocol) layer so Claude Code can act on the network directly instead of me relaying show command output back and forth by hand. There’s a small set of MCP servers, each scoped to one thing:

• One that talks to the router — reads configuration and running state, and can apply changes (like adding a static host mapping) over SSH.
• One that reads switch port status and traffic over SNMP.
• One that lists and controls VMs/containers on the Proxmox cluster via its API.
• One that reads the centralized logs.
• A generic SSH connector for anything else on the LAN.

The point isn’t “let an AI reconfigure my network unsupervised” — it’s narrowing the interface. Each server exposes a specific, reviewable set of actions instead of a raw shell, so when I’m working through something like a VLAN migration or a switch swap with Claude Code, it can genuinely read the live state of the router and switches and reason about port assignments and firewall rules against what’s actually deployed — not against my possibly-stale mental model of it — while every actual change still goes through review before it’s applied.

The VLAN problem consumer mesh WiFi can’t solve

The most concrete recent project this stack enabled: putting IoT devices and IP cameras on their own isolated VLAN, firewalled off from the trusted network, while leaving everything else alone.

The obvious approach — tag a dedicated SSID to a VLAN on the existing mesh WiFi — turned out to be a dead end. Consumer-tier mesh systems generally don’t support mapping individual SSIDs to VLANs; that’s an enterprise-AP feature. Rather than replace a perfectly good mesh system, the fix was to add a couple of cheap, dedicated access points running OpenWrt, configured as dumb bridges rather than routers: no DHCP, no routing, no firewall of their own, just WiFi bridged straight onto a switch port that’s hard-set to the IoT VLAN. The switch does all the VLAN tagging; the access point doesn’t need to know VLANs exist at all.

On the router side, that VLAN gets its own subnet, its own DHCP scope, and a firewall policy that defaults to drop everything inbound except:

• established/related traffic (so replies to connections IoT devices themselves initiated still work),
• a narrow allow rule for the one thing that has to reach in — MQTT traffic to the home-automation host, so IoT devices can publish to it,
• and outbound internet access, since these devices still need it for NTP, firmware updates, and cloud features.

Everything else from the IoT VLAN toward the trusted network is dropped by default. Traffic in the other direction (trusted → IoT) stays unrestricted, since it’s the automation/monitoring hosts polling into the IoT VLAN, not the reverse, that needs to keep working.

The one wrinkle worth calling out for anyone doing this themselves: mDNS and similar local-discovery protocols don’t cross VLAN boundaries. Anything that relies on discovery (some smart-home integrations) needs a static IP/reservation instead of “just works” auto-discovery once it’s segmented.

Naming things like infrastructure, not like guesses

A smaller but satisfying piece of this: formalizing a DNS naming standard. Some of my hostnames dated back to a previous job’s naming convention (CLLI codes, if you know, you know) and had long since stopped meaning anything to anyone but me. The new standard is boring on purpose — a short role code plus a number for physical hosts (router, switch, storage, etc.), the purpose itself as the name for single-role VMs, and a separate tier of service aliases that point at whichever host currently provides a service and move with it if that ever changes. It’s a small thing, but “the name tells you what it is” pays for itself every time you’re debugging at 11pm.

Where this leaves things

None of this is exotic — a graph database, a syslog watcher, some MCP servers, and a VLAN. What made it worth doing was treating a home network like it deserves the same basic care as any other system I run: know what’s on it, get told when it breaks, and keep the blast radius of any one compromised device small. The AI-copilot layer is the part I’d call genuinely new — not because it does anything a human couldn’t, but because it turns “let me SSH into six things to check” into a conversation grounded in what the network actually looks like right now.

The end state: a Pi 5 (pi5-2) serving NTP to the LAN, disciplined by a u-blox NEO-series GPS module. The GPS’s NMEA sentences over serial say which second it is; a PPS (pulse-per-second) line on GPIO18 says exactly when that second starts. chrony locks onto the PPS pulse as its primary source, and the whole LAN gets genuine stratum-1 time.

Hardware

• Raspberry Pi 5
• A cheap u-blox NEO-6M/7M/8M GPS breakout board
• An outdoor active GPS antenna (added later — more on why below)

Wiring to the GPIO header:

The first debugging lesson, before any software was involved: if the module’s status LED never blinks, check the power pin voltage before anything else. A GPS module that looks “dead” is very often just under-powered.

Software setup

The UART on the GPIO header defaults to being the serial console/login shell, so that has to be freed up first:

raspi-config nonint do_serial_cons 1   # disable login shell over serial
raspi-config nonint do_serial_hw 0     # enable the UART hardware (adds
                                        # dtparam=uart0=on on Pi 5)
reboot                                 # required for the overlay to apply

Then install the two pieces that do the actual work:

apt install gpsd gpsd-clients chrony

gpsd talks to the GPS module and parses its NMEA output; chrony is the NTP daemon that turns that (plus PPS, later) into disciplined system time and serves it to the LAN.

Point gpsd at the device in /etc/default/gpsd:

DEVICES="/dev/ttyAMA0"
GPSD_OPTIONS="-n"

And give chrony a GPS refclock in /etc/chrony/conf.d/gps.conf:

refclock SHM 0 refid NMEA precision 0.05 poll 3 filter 8 offset 0.142
allow 192.168.1.0/24
local stratum 10

Then systemctl enable --now gpsd.socket gpsd.service chrony.

That looks simple. Getting there wasn’t — two gotchas ate most of the debugging time, and neither is obvious from the standard docs.

Gotcha #1: /dev/serial0 is a trap on the Pi 5

The conventional wisdom is “use /dev/serial0, it’s the stable alias for the GPIO UART.” On this Pi 5 + Bookworm image, that’s wrong. serial0 resolves to ttyAMA10 — the SoC’s internal PL011 UART, not the RP1 UART actually wired to the GPIO14/15 header pins. The header UART is ttyAMA0.

This is a nasty one to debug because every surface-level check says it should work: the device exists, gpsd can open it without error, and pinctrl shows the pins correctly muxed to TXD0/RXD0. It just silently receives zero bytes, because it’s listening to a UART with nothing physically connected to it.

I confirmed it by comparing /sys/class/tty/ttyAMA*/device/of_node against /proc/device-tree/aliases/serial0 (they pointed at different device-tree nodes), and with a physical loopback test — a jumper wire between pins 8 and 10, then writing and reading /dev/ttyAMA0 directly to prove the header UART was the one actually moving bytes.

Fix: use /dev/ttyAMA0, not /dev/serial0, on this board.

Gotcha #2: gpsd’s chrony SOCK integration is PPS-only

gpsd ships wired up to feed chrony directly over a Unix socket at /run/chrony.<device>.sock (chrony creates the socket; gpsd connects to it as a client, which is the opposite of what the naming suggests). It looks like the obvious modern integration path. On a module with no PPS wire yet, it just doesn’t work — refclock SOCK /run/chrony.ttyAMA0.sock sits at reachability 0 forever, with no error logged anywhere.

Digging through the strings in the gpsd binary turned up the reason: "PPS:%s using chrony socket ..." — that path only activates once gpsd has a PPS source. No PPS wire, no socket traffic, ever, silently.

Fix: use the older refclock SHM 0 interface, which gpsd always populates with coarse NMEA/UBX-derived time regardless of whether PPS is present. That’s the refclock SHM 0 refid NMEA ... line above.

Calibrating the NMEA offset

Without PPS, NMEA time arrives late over the serial link by a fixed amount — on this setup, a very stable +142ms (std dev under 2ms once the outdoor antenna gave a solid fix). That’s calibrated out with the offset parameter:

1. Let chrony run with a good GPS fix for a few minutes.
2. Read the Offset column for the GPS source in chronyc sourcestats — its offset relative to the NTP-disciplined system clock.
3. Put that value (in seconds, same sign) on the refclock SHM line’s offset parameter and restart chrony.
4. Verify with chronyc sources: the GPS offset should now sit within a few milliseconds of the pool servers.

The precision 0.05 on that line claims a conservative ±50ms error bar — small enough that chrony selects GPS as primary, large enough that if the NMEA latency ever drifts substantially, the pool servers out-vote it and chrony marks it a falseticker instead of quietly following bad time.

Indoors, the module struggled to get a fix at all. An outdoor active antenna fixed that — a solid fix on ~10 satellites is what made everything past this point (including PPS) practical.

Reading chronyc sources

If you haven’t stared at chrony output before, the symbols are worth knowing:

MS Name/IP address         Stratum Poll Reach LastRx Last sample
===============================================================================
#- NMEA                          0   3   377     2   +1234us[+1230us] +/- 50ms
^* time.pool.example.org         2   6   377    23   -123us[ -089us] +/-  12ms
^+ ntp2.pool.example.org         2   6   377    41   +456us[ +460us] +/-  15ms

• # marks a reference clock (GPS); ^ marks a network peer.
• * is the currently selected source; + is a candidate in agreement; - is reachable but not currently selected/combined.
• The trailing +/- Nms is chrony’s estimated error bound for that source — this is what the precision setting on a refclock line ultimately informs.

The PPS upgrade

NMEA-only gets you agreement with the pool to a couple of milliseconds, but the true accuracy is only as good as that +142ms latency is stable — and it can shift if gpsd, the sentence mix, or the module changes. PPS fixes this properly: it’s a hardware pulse on the exact top of each second, so sub-second timing stops depending on a measured constant entirely. The NMEA sentence still supplies which second it is; PPS supplies the precise edge within it.

1. Enable the PPS overlay. In /boot/firmware/config.txt (Bookworm’s path — not /boot/config.txt):

dtoverlay=pps-gpio,gpiopin=18

reboot for the overlay to load. GPIO18 is just the convention dtoverlay=pps-gpio defaults to; any free GPIO works if gpiopin= matches the wire.

2. Confirm the kernel sees pulses:

apt install pps-tools
lsmod | grep pps_gpio          # pps_gpio module loaded
dmesg | grep pps                # "new PPS source pps@12" + "Registered IRQ"
ppstest /dev/pps-gps            # one "assert" line per second, timed

If ppstest prints nothing, either the module has no fix yet (most NEO boards don’t pulse PPS without one) or the wiring/gpiopin is wrong.

3. Gotcha: /dev/ppsN numbering is a boot-time race. On the Pi 5, the Ethernet controller’s PTP clock (ptp0) and the GPIO PPS both register as /dev/pps*, and which number each gets depends on probe order at boot. On this box the GPIO PPS came up as pps0 and the Ethernet PTP clock as pps1 — the opposite of what I’d first assumed, and the opposite of how it had been before adding PPS. Trusting a bare device number risks chrony silently locking onto the Ethernet PTP clock after a reboot: no error, just quietly wrong time.

The fix is to match on the stable device-tree name instead of the number, via a udev rule (/etc/udev/rules.d/10-pps-gps.rules):

SUBSYSTEM=="pps", ATTR{name}=="pps@12.-1", SYMLINK+="pps-gps"

Then udevadm control --reload-rules && udevadm trigger --subsystem-match=pps, and confirm /dev/pps-gps points at whichever ppsN is actually the GPIO source. Check the name on your own board with cat /sys/class/pps/pps*/name — the GPIO one is the pps@NN entry, the Ethernet one is ptp0.

4. Add the PPS refclock to chrony. Keep the existing NMEA line (it still supplies the integer second) and add a native PPS refclock locked to it, in /etc/chrony/conf.d/gps.conf:

refclock SHM 0 refid NMEA precision 0.05 poll 3 filter 8 offset 0.142
refclock PPS /dev/pps-gps refid PPS lock NMEA precision 1e-7 poll 3 prefer

• lock NMEA tells chrony to take the ambiguous PPS second-number from the NMEA refclock — so the calibrated offset 0.142 still matters, just for a much looser reason: it only needs to land NMEA within ±0.2s of the pulse to keep the lock, and 142ms is comfortably inside that.
• prefer makes PPS the source chrony actually steers to; the pool servers and NMEA become agreement/sanity checks rather than the trusted source.
• precision 1e-7 (~100ns) tells chrony this is a high-quality source, so it gets weighted well above NMEA and the pool.

Restart chrony. In chronyc sources -v, PPS should now be the selected source (#*) with an estimated error in the hundreds of nanoseconds, NMEA reachable but not combined (#-, it’s just supplying the lock), and the pool servers as agreement checks (^-). journalctl -u chrony logs Selected source PPS.

Simpler alternative: once PPS is wired, gpsd’s SOCK integration from gotcha #2 finally has a PPS source to report, so refclock SOCK /run/chrony.ttyAMA0.sock refid GPS precision 1e-7 prefer works too, letting gpsd handle the PPS plumbing. I kept the native refclock PPS line instead — it’s explicit about the NMEA lock, doesn’t depend on gpsd’s internal PPS handling, and sidesteps needing gpsd to pick the correct device. SOCK is one line if you’d rather use it.

Where accuracy ended up

The calibrated NMEA constant went from “the thing being trusted” to a wide safety margin that only has to hold the PPS second-lock — a much easier job than being the actual accuracy source.

Verifying it’s all working

gpspipe -w -n 20        # raw gpsd JSON: satellites, fix mode, position
cgps -s                  # live satellite dashboard
ppstest /dev/pps-gps     # confirm PPS pulses (one assert/sec) reach the kernel
chronyc sources -v       # confirm PPS is selected (#*), NMEA reachable (#-)
chronyc sourcestats

If chronyc sources shows #* next to PPS, the whole chain — antenna, module, kernel PPS, chrony — is doing its job, and every other device on the LAN syncing against this Pi is getting time that isn’t waiting on an internet connection to be right.