How to keep an IPv6 VPN address plan readable a year later
A readable plan says which prefix belongs to which site and how replies return. Record roles, notation, delegation and return routes beside each entry.
Two questions decide whether an address plan earns its place: which prefix belongs to which site, and how an answer gets back out of that site. Answer both in one pass and a maintainer can change a peer without interrogating anyone. Everything else in the document exists to support those two answers. Whatever supports neither is decoration.
What a reader has to answer before touching a peer
Compression makes addresses look tidy, and tidiness is not structure. Structure is knowing which range the provider delegated, which one you picked, which one is a client pool and which one sits behind a site.
Write for the colleague who joins next quarter and has to add a second site. Nothing on the page tells them where a prefix came from unless the entry does. Skip that and the first change turns into archaeology.
What each line of the plan has to carry
Four fields make an entry reviewable: how long the prefix is, who owns it, where traffic goes next, and which component hands the value out. Hold those against the running configuration and any disagreement surfaces on its own. A next hop aimed at a tunnel removed last month looks wrong immediately instead of blending in.
Keep roles in separate rows even when two of them share a prefix today. Merging them turns a later split into something that reads like a fresh allocation rather than a correction.
| Entry | Fields to record | Why a reviewer needs it |
|---|---|---|
| Endpoint addresses | Prefix, owning side, session initiator | Firewall rules and peer config both read it |
| Tunnel interfaces | Prefix and length, next hop, interface name | Shows the path a packet actually takes |
| Client allocations | Pool range, size, distributing component | Shows room left before a redesign |
| Downstream networks | Prefix, site label, return route | Explains a reply that never arrives |
Where canonical text and configuration syntax diverge
RFC 5952 fixes one text form for an address: lower case, no leading zeros, and the longest run of zero groups compressed exactly once. Use it in notes, tickets and change records so two documents compare without conversion. Readers who meet two spellings of one address start hunting for a difference that is not there. Consistency here is cheap and it removes a whole class of false alarms.
Configuration files obey their own rules, and they are not the readability rules. An address paired with a port needs brackets even when the bare address does not, and a copy from a note into a config file drops that distinction without warning. Name the form each field uses, or the plan causes the transcription error it was meant to prevent.
Two notations are fine as long as each one is labelled. Unlabelled mixing is what invites the mistake.
Where overlapping ranges and missing return paths show up
Overlap outlives other mistakes because nothing looks wrong until two sites answer for the same range. Label the site and generate unique-local prefixes through the documented procedure instead of copying an example.
A client list never explains which direction the reply travels. Record the LAN gateway's path back next to the peer range the tunnel carries, and the record explains a remote subnet that receives requests and stays silent. Run the checks below on the box and compare them with the entry. A plan that disagrees with ip -6 route is a plan people stop reading.
ip -6 route show default
ip -6 route get 2001:db8:2::10
ip -6 addr show dev wg0Reachability is not authorization, and a prefix never implies a policy. Write the intended access beside the route it applies to. Otherwise the next reader treats an address in the plan as permission to reach every service behind it.
How the plan survives the third site
Mark each prefix as delegated, locally assigned or routed some other way. For anything that can move, name the process that moves it. Then list the DNS records and firewall rules that must change in the same window, because a prefix update that stops at the router is half done.
After a change, reach a resource behind every boundary the change touched before you edit the document. A plan that describes last month's network is worse than none, since people trust it. Keep withdrawn allocations listed with the date they went away so nobody reissues them by accident. Secrets stay out of the file; a plan explains the network, it does not open it.
Store the plan where changes get reviewed, beside the configuration it describes. A document nobody re-reads rots faster than the network it maps.