wmantly
ace7b441c2
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.
61 lines
2.7 KiB
Markdown
61 lines
2.7 KiB
Markdown
---
|
||
layout: default
|
||
title: 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](connecting.html) 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
|
||
|
||
1. 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.
|
||
2. On the new gateway, use **Join a Remote Gateway's Mesh**: paste the other
|
||
gateway's URL and the token.
|
||
3. 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](../sso/multi-site.html) (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](https://github.com/theta42/theta-suite/blob/master/docs/MULTI_SITE_SPEC.md)
|
||
for current status.
|