Repository navigation
Releases
v2.0.1
What's New
- Aligns the public v2.x architecture contract around master-owned coordination zones instead of a standalone control-plane daemon as the operational center.
- Keeps
mesh-ctlas the topology source of truth and configuration/deployment CLI for current v2.x releases.
Changes
- Updates README architecture diagrams and localized README mirrors to match the current master/egress/balancer/client model.
- Tightens coordination flag validation so coordination listen/cert options are only accepted in valid master-owned coordination contexts.
- Updates RouterOS/MikroTik release gate wording to point at the version matrix gate that dispatches the CHR E2E path.
Fixes
- Fixes RouterOS coordination target validation so invalid targets fail before generating unusable config.
- Hardens v2.0.1 release documentation against stale standalone control-plane wording.
- Preserves the exact post-merge release gate state for commit 599bddb.
Verification
- GitHub Actions
buildonmainpassed for 599bddb. - Local release gates passed on the same commit: race tests, node/client Docker builds, F-009 foundation smoke, strict critical suite, emulation playbook, MikroTik generator tests, CHR baseline runtime, and MikroTik version matrix.
v2.0.0
What's New
- Flat v2 mesh architecture with role-agnostic
mesh-ctl node ...workflows. - Go module path moved to
github.com/coonfuuseed-paandaa/awg-mesh/v2for correctgo install ...@v2.0.0behavior. - Release-facing documentation refreshed, including English, Russian, and Chinese README variants.
- Strict v2 critical suite, customer-mode emulation playbook, Docker gates, and MikroTik CHR runtime/product gates are green on the tagged commit.
- MikroTik RouterOS
/containerbridge generator supports documented RouterOS syntax pivots and validates runtime CHR behavior on RouterOS 7.21+. - Certificate lifecycle support adds CA-backed admin/client mTLS flows and cert rotation coverage.
- Migration tooling converts v1.x topology YAML to schema v2.
Release Gates
Passed locally on commit 96ebe520625ca08a60eca45970cbbe6ebe5cb2b3:
CGO_ENABLED=1 go test -race -count=1 ./...buf lint- README localization parity and minimal topology validation
- Docker node and client image builds
bash tests/critical/run-all.sh --strictbash tests/simulation/F-009-CR-001-foundation-smoke.shbash tests/emulation-playbook/run.sh(PRODUCT_WORKS)bash tests/simulation/mikrotik-chr-baseline-runtime.shbash tests/simulation/mikrotik-version-matrix.sh
v1.14.1 - release-quality patch
v1.14.1 — release-quality patch
Patch release clearing technical debt observed during v1.14.0 ship.
✅ No wire format change. Drop-in replacement for v1.14.0 — operators do NOT need to re-prepare nodes.
Fixed
Race detector flake on overlayRouterFn
TestEndpointRebuildAllOverlayRoutes and TestEndpointReconcilePeerKey both had t.Parallel() while mutating package-level seam vars. Go race detector caught real concurrent r/w in v1.14.0 tag-build CI; re-runs masked the bug. Fix removes t.Parallel() from both, aligning with the documented pattern used by other reconcile tests.
Verified: 10× go test -race runs in Docker golang:1.25-alpine PASS without race.
CI
Dropped chr-lint job
Boots a real RouterOS CHR via QEMU usermode networking on standard GHA runners, but without KVM acceleration CHR cold-boot exceeds 5 minutes and SSH auth subsystem stays unresponsive. Two reproductions on PR #92 confirmed.
Coverage replaced by:
pkg/mikrotik/golden_test.go— compile-time golden-fixture diff catching generator regressions deterministically.tests/simulation/mikrotik-chr-e2e.sh— operator-side full E2E with real CHR via QEMU/KVM (10/10 PASS on CHR 7.16.2).
Docs
AGENTS.md release gate updated: go test -race mandatory, CHR e2e step added, golden-fixture step added, chr-lint reference removed.
Verification (NON-NEGOTIABLE per AGENTS.md release gate)
go test -race -count=1 ./...→ 19/19 packages PASStests/simulation/issue-92-rotation.sh→ 73 PASS R1-R12 (Linux mesh data plane)tests/simulation/mikrotik-chr-e2e.sh CHR=7.16.2→ 10 PASS (real RouterOS CHR via QEMU/KVM)- CI all green WITHOUT re-run
Compatibility
Drop-in replacement for v1.14.0. No tag/operator action required beyond rolling upgrade.
v1.14.0 - mikrotik onboarding bundle (issue #181)
v1.14.0 — mikrotik onboarding bundle (issue #181)
Bundles three coordinated tracks fixing 13 bugs + 7 requirements that blocked mikrotik-home (RouterOS 7.21.3 ARM64) onboarding.
⚠️ WIRE FORMAT BREAKING CHANGE — operators MUST re-prepare every node. See Operator Cutover Runbook in CHANGELOG.md before deploying.
Tracks
F-001 — MikroTik generator fixes (LOW risk) — 7 tasks
Bugs 1, 2, 3a, 3b, 3c, 5, 14: deploy template ordering, RouterOS 7.21+ canonical params (mountlists=, list=, remote-image=), firewall fasttrack-connection anchor, mikrotik.storage_root topology field, bounded tunnel ID, golden-file regression test, CHR import lint CI.
F-002 — Client image rebuild (HIGH risk) — 9 tasks
Bugs 7, 9, 11, 12, 13: NEVER-FLUSH default route via ecmpRouteInstalled, SetupNAT + ClampMSSToPMTU in client mode, lumberjack v2.2.1 log rotation, DSCP rt_tables generator, POSIX client-init.sh, alpine Dockerfile.client (43.6 MB), Docker Hub manifest parity CI, full E2E mikrotik-onboard sim.
F-003 — Wire protocol token format v2 (MEDIUM risk, BREAKING) — 7 tasks
Bug 4: argon2id v2 token format mesh1.<base64url> (78 chars, charset [A-Za-z0-9._-]). Replaces bcrypt. Bootstrap fail-fast on legacy hashes. composeEscapeDollar deleted. RouterOS template emits raw hash (no $$ escape needed).
Verification (NON-NEGOTIABLE per AGENTS.md release gate)
go test -short -count=1 ./...→ all PASStests/simulation/issue-92-rotation.sh→ 73 PASS R1-R12 (Linux mesh data plane)tests/simulation/mikrotik-chr-e2e.sh CHR=7.16.2→ 10 PASS (real RouterOS CHR via QEMU/KVM)tests/simulation/lib/build-chr-baseline.sh→ baseline image OK for tier-2 CHR- shellcheck error-only PASS on all sim scripts
- PR #90 CI: test, windows-compile, lint, chr-lint, build, docker — all green
Multi-version compatibility
CR-002 multi-version dialect support (FR-G1..G10 + FR-C1..C7) deferred to v1.15.x — playbook published at docs/MIKROTIK-VERSION-COMPAT.md. v1.14.0 ships canonical 7.21+ generator output unconditionally.
For tier-2 (RouterOS 7.5–7.17) and tier-1.5 (7.18–7.20) operators: regenerate .rsc against v1.15.x once dialect selection ships; v1.14.0 .rsc requires 7.21+.
Operator action
- Backup
/config/mesh.tokenon every node - Per-node:
mesh-ctl <role> prepare → deploy → init → status --verify-data-plane - No transition window — v1.14.0 binary fail-fasts on legacy bcrypt hashes by design
- Rollback:
mesh-ctl upgrade rollback v1.13.0(existing recovery primitive)
Closes local tracker issue #181.
v1.13.0
What's New
Client Runtime Hardening (#84)
- 11 runtime fixes: tunnel naming, pubkey decode, cert skew tolerance, EnableL4Hash non-fatal, overlay src hint, AllowedIPs, healthcheck initial transition, idempotent tunnel re-create
- MikroTik .rsc generator rewrite: bridge+NAT+firewall+mount+DNS+logging+CAPS naming+CGN subnet
Metrics Auth (#86)
- Bearer token middleware on
/metricsendpoint whenMESH_METRICS_ADDRis non-localhost - Reuses existing
mesh.token— zero new config fields
Security Fixes (#87)
mesh-ctl reconcilegRPC connections now use mTLS (wasInsecure: true)- CA cert PEM validation before client creation prevents silent TLS downgrade
Bug Fixes (#88)
- Master
transport.ymlstores peer public key as hex (was base64) — fixes falsedisk_runtime_divergeinmesh-ctl inspect - E2E sim: R9b port assertion uses transport.yml match (userspace WG invisible to ss)
- E2E sim: R11 AllowedIPs assertion reads transport.yml directly (inspect truncation)
Documentation (#85)
- README What's New for v1.12.10-12
- CHANGELOG unreleased #165 entry
- OPERATOR_FAQ link cleanup
v1.12.12 mesh-ctl audit round 2
v1.12.12 — mesh-ctl audit round 2 (remaining 14 local tracker #151 items).
Behavioural changes:
- Upgrade JSONL logs move to
<configDir>/backups/upgrade-logs/. Legacy config-root logs still surfaced bymesh-ctl upgrade statusas fallback. Newupgrade.BackupsDirNameandupgrade.UpgradeLogsSubdirconstants define the layout.
Documentation:
docs/OPERATOR_FAQ.md(new) — authoritative operator-facing contracts for: token lifecycle + MESH_TOKEN_HASH semantics (identical across master/endpoint/client — #151 B5, B19); pubkey admin-side 32-raw/64-hex accept-both policy (#151 B16); client admin-side has no pubkey by design, self-registers via AddPeer RPC (#151 B22); what mesh-ctl writes vs does not write under config dir (#151 B24, B25, B28);mesh-ctl upgrade composestdout-is-preview (#151 B31).
Investigation finding: .bak.<ts>/ directories seen by deployer are NOT created by mesh-ctl — operator-managed (PowerShell Rename-Item). See FAQ for the explicit writer/non-writer table.
Release gate: R1-R12 unchanged. Test gates: TestMostRecentLogPath_LegacyFallback + TestMostRecentLogPath_NewerLocationWins.
CodeRabbit round 1 findings addressed (fd3e0d2): token rotation wording corrected (plain token is for mesh-ctl RPC bearer, not MESH_TOKEN_HASH env), MD040 language tag added to tree snippet.
v1.12.11 mesh-ctl audit round 1
v1.12.11 — mesh-ctl audit round 1 (17 of 32 local tracker #151 items).
Critical fixes: B11/B12 DSCP routing per-policy tables (MikroTik + Linux), B14 master compose TokenHash binding, B17 upgrade rollback tolerates missing .bak.
Additional: B1 scanner, B2 topology path, B3/B4 client output + veth, B13 gateway default, B15 image tag rewrite, B18 verify settle, B20 inspect allowedIPs nil, B21 status tunnel count, B27 log version, B29/B32 capture UX.
CodeRabbit round 1 findings (0e9fa47): 4 MAJOR + 6 UX fixups.
Release gate: R1-R12 unchanged.
Deferred to v1.12.12: B5/B19, B16, B22, B24-B28, B31.
v1.12.10
v1.12.10 — master wg-+ FORWARD ACCEPT auto-insert (closes #150)
Root cause (engram #150 layer-5)
Master container runs with network_mode: host. Endpoint↔endpoint traffic requires kernel forwarding between wg-<ep-a> → wg-<ep-b> on master — hits host FORWARD chain. Docker-managed hosts commonly have default FORWARD policy DROP, silently dropping these packets. Master↔endpoint (one-way) unaffected because master-originated packets use OUTPUT chain.
Deployer confirmed after v1.12.9 landed: 231 dropped packets on FORWARD chain = endpoint-↔-endpoint tests. Manual iptables -I FORWARD -i 'wg-+' -o 'wg-+' -j ACCEPT → 23/28 pairs green immediately.
Fixes
EnableWGCrossTunnelForward()added to Firewall interface. iptables CLI shell-out (idempotent via-Ccheck). Wired into MasterRunner.Run() after setupExitMode — non-fatal (warn + continue on failure).- Documented intentional no-teardown behavior in docstring (container netns cleanup makes rule removal redundant; retaining enables restart idempotency).
Test gates
- G15 unit:
TestEnableWGCrossTunnelForward_Idempotentin pkg/routing/nftables_test.go - R12 sim: asserts
iptables -C FORWARD -i 'wg-+' -o 'wg-+' -j ACCEPTon both master containers - G1-G14 + R1-R11b continue to gate. AGENTS release gate: R1-R12.
Verification
- go build ./... green
- go vet ./... green
- go test -short -count=1 ./pkg/routing/... PASS (G15 included)
- CI green: build, docker node+client multi-arch, lint, test, windows-compile, CodeRabbit
Upgrade notes
Drop-in PATCH. No proto/schema/migration changes. Rolling upgrade either direction. Master restart auto-inserts rule. No operator action required on update.
v1.12.9
v1.12.9 — fix AddTunnelRequest.allowed_ips wire drop (closes #147 layer 4)
Root cause (v1.12.8 failed at deployer)
Master's /config/transport.yml after master init still showed minimal [transport /30, endpoint /32] — missing the /27 endpoints-range CIDR. v1.12.8 added AddTunnelRequest.AllowedIps field 13 to the Go struct + getter but the raw file descriptor blob file_types_proto_rawDesc was NOT updated. google.golang.org/protobuf uses the descriptor as authoritative for wire encode/decode; master proto.Unmarshal silently dropped field 13 as unknown -> saveTransportState fallback to minimal.
Fixes
- Surgical bytes-level patch to
file_types_proto_rawDescinproto/types.pb.go— length varint 451 -> 484, field 13 entry inserted. Zero application code changes. - G14
TestAddTunnelRequest_AllowedIpsWireRoundtrip— wire round-trip gate. Would have caught the v1.12.8 failure at CI time.
Test gates
- G1-G13 continue to gate.
- G14 (new):
proto.Marshal -> proto.Unmarshalround-trip onAllowedIps, assertsreflect.DeepEqual. Permanent regression guard.
Verification
go build ./...greengo vet ./...greengo test -short -count=1 ./proto/...-> G14 PASS- CI green (build, docker node+client, lint, test, windows-compile, CodeRabbit)
Upgrade notes
Drop-in PATCH. No proto schema changes (the .proto file at line 85 already had field 13 correctly — only the generated descriptor was out of sync). No migration. Rolling upgrade either direction.
v1.12.8 — Master tunnel.AllowedIPs admin source of truth (closes #147)
v1.12.8 — Master tunnel.AllowedIPs admin source of truth (closes #147 layer 3)
Problem (4th failure in same class)
v1.12.7 shipped BuildAllowedIPsForMasterPeer and wired CLI to pass expanded AllowedIPs via UpdateTunnelPeerRequest.AllowedIps. Deployer verification: master's /config/transport.yml STILL had minimal [transport /30, endpoint overlay /32] — no /27. Root cause: saveTransportState ignored caller and recomputed via BuildAllowedIPsForMasterPeer(m.node.topology, ...). On master nodes in production m.node.topology == nil (deploy omits --topology flag). Recompute returned minimal → overwrote admin intent → next restore reverted UAPI to minimal → /27 forwarding filter lost.
Fix (architectural inversion)
Admin = source of truth, master persists verbatim:
MasterTunnelgainsAllowedIPs []stringfieldAddTunnelgets 10th arg; all callers updated (restore loop reads from disk; test sites pass nil)UpdateTunnelPeerwritestunnel.AllowedIPs = allowedIPsbefore savesaveTransportStateusestunnel.AllowedIPsverbatim; fallback to local recompute only when empty (legacy migration)- Proto:
AddTunnelRequestgainsallowed_ips = 13 - gRPC
AddPeer+AddTunnelhandlers validate + wirereq.GetAllowedIps()→ manager (codes.InvalidArgumentat boundary) - CLI (
master init,endpoint init,reconcile) computes viaBuildAllowedIPsForMasterPeerand sends in request endpoint initalready-exists path (UpdateTunnelPeer fallback) uses master-side AllowedIPs (not endpoint-side minimal)
Gates
- G12 unit (
TestSaveTransportState_PersistsAdminAllowedIPs+_FallbackToLocalOnEmpty): admin intent persisted verbatim when non-empty; local fallback when empty - G13 unit (
TestAddTunnelPassesThroughAllowedIPs): gRPC handler forwardsreq.GetAllowedIps()toTunnelManager.AddTunnel - R11b sim: master WITHOUT --topology →
master init→/27present in on-disk transport.yml (reproduces prod deploy scenario)
Upgrade
Drop-in PATCH on master side. No migration. Rolling upgrade either direction.