Files

T

wmantly ace7b441c2 docs(site): publish multi-site + gateway mesh to the actual docs website

Everything shipped this pass (live replication, master/spoke join,
gateway-to-gateway WireGuard mesh) had real spec docs in the repo
(docs/MULTI_SITE_SPEC.md, sso-manager-node's docs/site-join.md) but
nothing on the actual published docs site (theta42.github.io/theta-suite/)
-- a reader landing there would find no mention of it at all beyond a
vague, unlinked "multi-site replication" bullet on the homepage.

- New docs/sso/multi-site.md: the operator-facing master/spoke join guide
  (why, how, promoting a spoke, what replicates, current limits), with an
  explicit section distinguishing it from the pre-existing N-way LDAP MMR
  replication page (replication.html) -- two different mechanisms that
  were at real risk of being conflated with nothing to tell them apart.
- New docs/jump-host/mesh.md: the gateway-to-gateway WireGuard mesh guide,
  linked from a "WireGuard mesh routing" bullet that already existed on
  the jump-host homepage but pointed nowhere.
- docs/sso/index.md, docs/jump-host/index.md: link the new pages from
  each component's Features list.
- docs/index.md: replaced the oversold, unlinked "multi-site replication
  running in seconds" homepage copy with an accurate, linked claim.

2026-08-10 19:54:25 -04:00

2.7 KiB

Raw Blame History

layout, title

layout	title
default	Gateway Mesh

Gateway Mesh

Theta Gateway can mesh with other Theta Gateway instances over real site-to-site WireGuard tunnels — separate from its SSH jump host role, and separate from the roaming-client/exit-node WireGuard feature (individual peer configs for laptops/phones). This is gateway-to-gateway: two sites' networks reaching each other directly.

Why and when to use this

Direct site-to-site networking, not just SSH. Once two gateways are meshed, hosts behind each can reach each other over the tunnel using the mesh addressing scheme below — not limited to jumping through SSH.
No manual WireGuard config. Meshing is a join-token exchange; both sides come out with a live, working peer entry for each other automatically.
Works without a kernel WireGuard module. Prefers in-kernel WireGuard, falls back to the userspace wireguard-go implementation automatically — useful for older kernels, some container/cloud images, or hosts where the kernel module isn't available.

How it works

On the gateway you want others to join, mint a join token: Mesh page → Mint a Join Token. It's single-use and expires in 15 minutes.
On the new gateway, use Join a Remote Gateway's Mesh: paste the other gateway's URL and the token.
Both sides now have a live WireGuard peer for each other. The Meshed Gateways table shows every peer, its assigned mesh subnet, and when it was last seen.

Each gateway is assigned a mesh index (an integer 1–254) the first time it either mints a token or is registered by another gateway. That index determines its subnet: 172.24.<index>.0/24 for the mesh tunnel itself, plus 10.<index>.0.0/16 reserved for that site's own local network — 254 sites is the hard ceiling this addressing scheme supports.

Requirements

Both gateways need a reachable endpoint (host:port) for the WireGuard handshake — typically the same public host the SSH/web ports are already on, with UDP 51820 reachable.
NET_ADMIN capability (or equivalent) on the container/host running the gateway, to create the WireGuard interface.

Not yet connected to directory sync

This mesh is a networking layer on its own. Theta Directory's multi-site join (catalog + LDAP replication between a master and its spokes) does not currently route its traffic over this mesh — the two features work independently today. Routing directory sync over the mesh, and using the mesh to reach a spoke site with no inbound access of its own, are both designed but not yet automated — see the architecture spec for current status.

2.7 KiB Raw Blame History Unescape Escape