Design question: WireGuard peers — managed-only vs. preserve manually-added

[ispyisail]

Design question: how should the WireGuard plugin treat manually-added peers?

This is an open design question, not a decision that's been made. It came out of review feedback from Lantis, and both positions have real merit. Laying out the trade-offs neutrally so it can be discussed on the substance — input welcome, especially real-world use cases.

Background

The WireGuard plugin manages peers through its own UI (the allowed_client model — inbound/"server mode" clients that connect to the router). A user can also add peers by hand, directly in /etc/config/network (config wireguard_wg0 sections) — for example a site-to-site tunnel or an outbound peer set up by following a VPN provider's guide.

The question is what a GUI Save should do with those hand-added peers.

Two behaviours are on the table (a third option may reconcile them — see below).

---

Position A — Managed-only: the plugin owns the config; unmanaged peers are deleted on save

This is the maintainer's position, and how Gargoyle's plugins generally work.

In favour

• Single source of truth. What the UI shows is exactly what's on the device. No hidden state.
• Predictable and auditable. A peer that exists is a peer you can see and edit in the GUI.
• Simplest model and code. The plugin can regenerate the peer set from scratch on every save; no "is this section mine or not?" reconciliation.
• Consistent with how every other Gargoyle config page behaves — the plugin manages its domain.
• No orphan accumulation of stale sections the UI can't see.

Against

• Silently deletes hand-added peers on a save that may be about something unrelated — a real data-loss / potential lockout risk for anyone who edited config by hand (e.g. an SSH-added road-warrior peer).
• Pushes unsupported use cases out of the GUI entirely: if the UI can't express a configuration, the user must either avoid the GUI or lose that config.

---

Position B — Preserve: a save keeps hand-added peers it didn't create

This is the behaviour currently shipped in the fork (peers the plugin didn't create are snapshotted and restored across a save).

In favour

• No data loss. Hand-added peers survive GUI saves.
• Lets power users mix GUI-managed peers with manually-maintained ones on the same interface.
• Removes a "save X, lose Y" surprise for users who don't know the GUI owns the whole section.

Against

• Two sources of truth. Some peers are managed by the UI, some aren't — so the UI no longer fully reflects the device, which undercuts the point of a management UI.
• Invisible state: the preserved peers don't appear in the GUI, so they can't be viewed, edited, or removed there — arguably more confusing than deleting them.
• Added reconciliation complexity (snapshot/restore of "not mine" sections) that every future change to the save path has to keep working.
• Can mask the real gap — the reason people hand-edit is that the UI can't express their config — instead of closing it.
• Diverges from the rest of Gargoyle and from mainline, so it isn't a change the upstream project would take.

---

Position C — Close the gap: expand what the plugin can natively express

Lantis's actual suggestion: "Is Gargoyle not able to import/read/work with some configurations you are trying to do? That should be looked at and expanded on."

The plugin's current model is inbound/server-mode only — it has no field for endpoint, persistent_keepalive, or preshared_key, and no site-to-site (subnet AllowedIPs) peer type. Those are exactly the things a hand-added peer usually needs. If the UI could express them, there would be little reason to hand-edit — and managed-only (Position A) becomes safe, because everything is representable in the GUI.

In favour

• Resolves the root cause rather than the symptom.
• Keeps single-source-of-truth and stays mainline-friendly.
• Turns "unmanaged peers" into managed ones.

Against / open questions

• More UI + backend work than either A or B alone.
• Needs a clear list of which configurations to support first (scope), which is where real-world use cases matter.

---

What would help decide

The most useful input is concrete: which WireGuard configurations are people setting up by hand today that the GUI can't currently express? (Outbound peer with an endpoint? Site-to-site with subnet routes? A pre-shared key? Multiple peers on one interface?) Knowing the real use cases pins down whether Position C is worth building and what it needs to cover.

Thoughts welcome — particularly from anyone running WireGuard configurations the current UI doesn't handle.

[ispyisail]

How Position B came about — and a lean toward reverting

For transparency on the history, since it bears directly on the decision:

Position B (preserving hand-added peers) was not a deliberate choice to move away from managed-only. It came out of our automated GUI-testing tooling. An adversarial save-fuzzing check saw that saving the WireGuard page issued a wholesale delete of the wireguard_wg0 peer sections — the plugin clears them and rebuilds only from its own managed list — and, in doing so, removed a peer that had been added by hand. The tooling flags any wholesale delete of user data as a data-loss bug (it had just caught a genuine one of that class), so it raised this too. We fixed it reactively by snapshotting the unmanaged peers and restoring them after the rebuild (PR #57).

The catch: that deletion isn't a bug — it's the intended managed-only behaviour (Position A). The plugin owns the config and regenerates the whole peer set on save. Our tooling can't distinguish "intended managed-only deletion" from "accidental data loss" — it only sees a wholesale delete and flags it. We took the flag at face value instead of asking whether the deletion was by design.

Reading it back with that context, Position B looks like a fix to a false positive. It's real reconciliation code and ongoing maintenance for a fairly narrow benefit, and it introduces the two-sources-of-truth / invisible-state problems listed above — which is precisely the anti-pattern raised in review. So we're leaning toward reverting to Position A (managed-only), and only pursuing Position C (expanding what the UI can natively express) if a concrete use case turns up that the GUI genuinely can't represent.

The revert is cheap — PR #57 was purely additive — so this isn't costly to undo.

Still genuinely interested in the Position C question, which is the one that actually matters going forward: which WireGuard configurations are people hand-editing today because the current UI can't represent them?

[lantis1008]

The plugin's current model is inbound/server-mode only — it has no field for endpoint, persistent_keepalive, or preshared_key, and no site-to-site (subnet AllowedIPs) peer type. Those are exactly the things a hand-added peer usually needs. If the UI could express them, there would be little reason to hand-edit — and managed-only (Position A) becomes safe, because everything is representable in the GUI.

I don't think this is correct.

1. WireGuard is not server/client model. It is inherently peer/peer. We just call it Server/Client to be similar to OpenVPN plugin and how people understand it.
2. Gargoyle has no need to know the peer (client) endpoint as the peer knows Gargoyle's IP and can connect that way. Only 1 peer needs to know the endpoint and connection is established bidirectionally.
3. persistent_keepalive is flagged on (25s) by default
4. Peer subnets are supported already and all peer subnets are pushed into AllowedIPs on config generate

If you want persistent_keepalive configurable that would be a trivial change. I don't think we should be pushing it at all and letting the client decide what it wants personally.
If you want to support preshared_key that is also trivial, but do you need this? It's post-quantum protection and not really a 2026 concern. But it is easy to add.
If you want to support additional subnets behind the "server" (like I recently added to OpenVPN), then this is also trivial.

[ispyisail]

Thanks — you're right on all four, and I went back through the plugin to confirm rather than just take it on the chin.

• peer/peer: understood. I'd read the "server/client" labels as an architectural split — that was my misread, not the plugin's design.
• endpoint: confirmed the plugin already does exactly what you describe. configureAC() only writes endpoint_host/endpoint_port when they're actually provided, so inbound peers get none (Gargoyle learns it from the handshake) and only the client-mode (wgserver) path sets one. No gap here.
• keepalive: yep — PersistentKeepalive = 25 is already emitted by default, and I agree there's no need to add a knob for it; the client's call.
• subnets: confirmed — allowed_ips is populated from the peer's IP list with route_allowed_ips=1, so peer subnets already land in AllowedIPs.

So my "the UI can't express these" premise was wrong — most of it is already there. That removes basically all of the justification for the peer-preservation behaviour, so we'll revert to Position A (managed-only) and let the plugin own the config as intended. PR #57 was purely additive, so it's a clean back-out.

On the genuinely-optional bits: keepalive we'll leave alone per above; preshared_key we'll skip unless someone actually asks (agree it's not a 2026 concern); and "extra subnets behind the server" is the one that seems plausibly useful — if we do anything there it'd follow the same shape as your recent OpenVPN change, and only on real demand.

Appreciate you setting it straight.