shc / arch / mesh-overlay ← lab docs

Two planes, three layers

mesh0 and shc0 are both kernel WireGuard, and they carry different traffic. mesh0 is the node plane (UDP 4244). It carries rqlite and the internal API. shc0 is the container plane (UDP 4243). It dials each peer's underlay address and never rides mesh0. mesh0 dials that same underlay, so neither plane is carried inside the other. A multi-node cluster runs mesh0 from the first join. The toggle below changes the underlay, one LAN or across sites. It does not turn mesh0 off.

L3 container
· app
shc0
whoami.1default_t10.0.9.4
whoami.2default_t10.0.9.7
postgres.1default_t10.0.9.9

identical in both shapes container↔container is shc0. It dials the underlay and never rides mesh0.

encapsulation: overlay frames become UDP between node addresses
L2 node
· control
cluster plane
node-1 raft leader
4002raft
4001rqlite http
4003api mTLS
4244mesh0
node-2 voter
4002raft
4001rqlite http
4003api mTLS
4244mesh0
node-3 voter
4002raft
4001rqlite http
4003api mTLS
4244mesh0

tcp 4001, 4002 and 4003 ride mesh0. shc0 does not.

bind: one interface carries every cluster-internal listener
L1 transport
· underlay
shared LAN
interfaceeth1 · 10.0.0.11
interfaceeth1 · 10.0.0.12
interfaceeth1 · 10.0.0.13
shared LAN segment · 10.0.0.0/24: every node reaches every node directly
mesh0, up mesh0 · 10.192.0.0/11 · udp/4244

mesh0 listens on udp/4244 and dials each peer's underlay. It is up from the first join.

Three nodes on one segment. mesh0 is up. rqlite and the internal API ride it. shc0 dials this LAN and never rides mesh0.

What rides which layer

the column matching the current shape is lit
traffic class port layer one LAN across sites
container ↔ container udp 4243 L3 shc0 dials the LAN. never rides mesh0 dials the site path. never rides mesh0
raft replication tcp 4002 rides mesh0 mesh0 over the LAN mesh0 over the site path
internal API (mTLS) tcp 4003 rides mesh0 mesh0 over the LAN mesh0 over the site path
rqlite HTTP API tcp 4001 rides mesh0 mesh0 over the LAN mesh0 over the site path
shc0 listen udp 4243 underlay dials the LAN dials the site path
mesh0 transport udp 4244 L1 plane on on
terminal: real commandssimulated

simulated No daemon and no packets. The commands and ports below are the ones in the repo. The host boxes use documentation addresses. The timings are invented.

The layering, precisely. mesh0 is the node plane: a kernel WireGuard device named mesh0, UDP 4244, addresses from the cluster block's mesh range (default 10.192.0.0/11). It carries rqlite (TCP 4001 and 4002) and the internal API (TCP 4003 on the mesh0 address). Each node generates its own key. Only the public key leaves the node. Peers come from a leader-signed peer table. shc0 is the container plane: a kernel WireGuard device named shc0, UDP 4243. It dials a peer's underlay address and never rides mesh0. mesh0 dials that underlay too, so neither plane is carried inside the other. There is no enable and no disable. A multi-node cluster runs mesh0 from the first join. The toggle only changes the underlay.

Ports. 4001 is rqlite HTTP, 4002 is raft, 4003 is the internal API (modules/fabric/nodeplane.go, modules/cluster/types.go). 4244 is mesh0 (modules/mesh/mesh.go). 4243 is shc0 (modules/fabric/types.go). Enrolment is POST /api/join/node.enroll on the public listener, which Traefik reaches on 443.

Network names. modules/network/state.go pins TenantNetworkSuffix = "_t" and StackPrivateSuffix = "_p", so the per-tenant network for tenant default is default_t. modules/network/service.go creates those networks with driver bridge. Cross-node container traffic is shc0, not that bridge.

What this page will not claim. mesh0 has no separate CA. shc cluster mesh status and shc cluster mesh diagnose read this node's mesh0. diagnose probes each peer's internal API over mesh0. One sweep is one moment. The internal API on 4003 is mTLS. rqlite on 4001 and 4002 rides mesh0 with it.