docs(nodes): require a dedicated, routed, unique IPv6 /64 for CRNs - #81
Conversation
The CRN install guides told operators to derive their IPv6 pool from their node's address and strip it to a /64. On shared-subnet providers (e.g. budget VPS where many machines share one /64) that produces a /64 the node does not exclusively own, so VM /124 allocations collide and the network scoring zeroes all-but-one node sharing the range (duplicate-IP gate, code 1005). Operators had no way to connect their score dropping to 0 with their IPv6 setup. Clarify in both the Ubuntu 24.04 and Debian 12 guides that the pool must be a globally-routable /64 that is routed to the host and unique to the node, warn about shared-subnet providers and the duplicate-IP scoring penalty, document that the unset default fc00:1:2:3::/64 is a non-routable ULA placeholder, and add a verification section. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
Deployed on:
|
foxpatch-aleph
left a comment
foxpatch-aleph
left a comment
There was a problem hiding this comment.
Documentation-only PR that clearly and accurately addresses a real operational issue (shared IPv6 /64 causing CRN score zeroing). The new requirement line, warnings, and verification subsection are well-written, technically sound, and kept in sync across both the Debian 12 and Ubuntu 24.04 install guides. Technical claims (default ULA pool fc00:1:2:3::/64, /124 VM sub-ranges, diagnostic code 1005, /status/config endpoint) are internally consistent and the PR description states they were verified against aleph-vm source. No correctness, security, or build issues introduced. Minor nits only.
docs/nodes/compute/installation/debian-12/index.md (line 131): Minor: ping6 is deprecated on some modern Linux distributions (iputils 20210202+ uses ping -6). Consider mentioning ping -6 as an alternative, or noting ping6 may not be available on all systems. Non-blocking.
docs/nodes/compute/installation/debian-12/index.md (line 119): Style nit: the ##### (h5) heading for "Verifying your IPv6 pool" jumps from the parent #### (h4) "IPv6 address pool" to h5, then the next section returns to #### (h4). Consider using #### for consistency with sibling subsections, or keep as-is — valid either way. Non-blocking.
docs/nodes/compute/installation/debian-12/index.md (line 110): Observation: diagnostic code 1005 is not referenced anywhere else in the docs (e.g., the metrics page at docs/nodes/resources/metrics/index.md). A cross-reference from the metrics page would let operators independently verify the claim, but that's a follow-up, not a blocker for this PR.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
foxpatch-aleph
left a comment
foxpatch-aleph
left a comment
There was a problem hiding this comment.
Documentation-only PR that updates both CRN install guides (debian-12 and ubuntu-24.04) with clearer IPv6 pool requirements, scoring-penalty warnings, default-pool warnings, and a verification subsection. The two files are kept in sync with identical content. Technical claims are accurate: 2000::/3 for global-unicast, fc00::/7 for ULA, fe80::/10 for link-local, fc00:1:2:3::/64 as the ULA fallback, and /124 per-VM sub-ranges. The /status/config endpoint and jq JSON path are consistent with pre-existing references in the docs. No code, no security surface, no tests needed. The PR explicitly notes the underlying file duplication as a follow-up rather than addressing it here, which is appropriate scope discipline.
2 participants
Why
Two node operators recently saw their CRN scores drop to 0 despite running v1.13.0 and being otherwise healthy. Root cause in both cases: multiple CRNs sharing one IPv6
/64, which trips the scoring system's duplicate-IP gate (diagnostic code1005) — only one node per shared/64is scored, the rest are zeroed.2602:f8ea:0:ae1::/64; two independently-verified nodes advertised the identical pool./64subnets; 14 of 15 still ran the defaultfc00:1:2:3::/64, so their VMs got non-routable ULA addresses and no working public IPv6.The existing install docs were partly responsible: they told operators to derive the pool from their node's address and strip it to a
/64. On shared-subnet providers that yields a/64the node doesn't exclusively own — exactly the misconfiguration above. Nothing warned about uniqueness, the scoring penalty, or the placeholder default.What changed
Updated both CRN install guides (
ubuntu-24.04anddebian-12, which carry duplicated content):/64must be dedicated, routed, and not shared with any other node./64routed to the host and unique to the node; added a shared-subnet-provider warning./64zeroes the score (code1005).ALEPH_VM_IPV6_ADDRESS_POOLfalls back to the non-routable ULA placeholderfc00:1:2:3::/64(verified against aleph-vmconf.py)./status/config, confirm global-unicast prefix, and ping a VM's IPv6 from outside.All technical claims verified against
aleph-vmsource and live node/status/configdata.Note
The two install guides duplicate this IPv6 content verbatim; this PR keeps them in sync but does not address the underlying duplication. Worth a follow-up to factor shared install steps into a partial.
🤖 Generated with Claude Code