TL;DR: IPv6 examples need real hex grouping and optional compression, not decorated IPv4. Use the generator in IPv6 mode when your product accepts that family, and keep the samples in docs or labs—not as probes.
The “IPv6” that still had dots
A trainee built config fixtures by taking 203.0.113.10 and wrapping it in brackets with extra zeros. Parsers rejected it. Reviewers rejected it. The lesson stuck: IPv6 is not IPv4 with makeup. You need the other shape or you are testing nothing useful.
The trainee’s mistake echoed older tutorials that showed IPv4-mapped forms without explaining when they appear. Modern configs more often need native eight-hextet notation. Copying v4 habits into v6 fields is a common onboarding failure mode for teams that just enabled dual-stack on a load balancer.
What good samples look like
Eight hextets, hexadecimal digits, colons as separators, and compression with :: when long zero runs appear. Compressed and expanded forms can refer to the same address; tests that string-compare without canonicalization will flake. Decide whether your suite stores canonical form or accepts any valid textual form per RFC 5952 recommendations.
- UI tests: include compressed and expanded variants users might paste.
- Firewall labs: match the syntax your appliance shows in its GUI, not only CLI.
- Docs: pick one form and stay consistent in a single paragraph.
- Logs: expect mixed case from different vendors; normalize in parsers, not always in display.
Bracket notation matters in URLs: https://[2001:db8::1]/ is valid; bare colons break URL parsers. Config files that accept host:port for v4 need bracketed v6 to disambiguate ports. Samples in README files should demonstrate the bracket form once when the product listens on v6 HTTP.
Reserved and special IPv6 ideas to avoid mishandling
Loopback ::1, link-local fe80::/10, and documentation prefixes such as 2001:db8::/32 deserve labels when you use them. Random global-looking draws can land on space you should not scan. The generator’s warning applies equally to IPv6: samples are for testing and documentation, not for contacting systems you do not operate.
Unique local addresses (ULA, fc00::/7) appear in internal diagrams. They should not leak into public tutorials as if they were routable on the open internet. If your sample config includes ULA, caption it “site-local example.” Multicast and anycast addresses have their own chapters in textbooks—do not use them as generic “server IP” placeholders.
Dual-stack fixtures
If the product speaks both families, store pairs intentionally—do not invent a fake relationship between a random IPv4 and a random IPv6. In narrative docs, say “example IPv4” and “example IPv6” as separate characters. When you need to explain what a browser currently uses, leave samples behind and open the live lookup.
Zone IDs and link-local gotchas
On Linux and Windows, link-local addresses often need a zone suffix such as fe80::1%eth0 for bind or ping from the shell. Your web app’s text field may reject percent signs. Document whether the product supports scoped addresses or only global unicast. Samples in admin UIs rarely include zone IDs; CLI runbooks sometimes must.
Containers and Kubernetes add another layer: interfaces rename, and copy-pasted fe80 examples from a blog may not match the pod netns. Prefer documentation-prefix global addresses in published Kubernetes YAML unless the doc is explicitly about link-local discovery.
Validation logic worth unit testing
Regex-only validators often fail on legitimate compressed forms or accept impossible hextet counts. Table-driven tests with a generator-backed batch plus hand-picked edge cases catch regressions. Include uppercase 2001:DB8::1, leading zeros controversy (some systems forbid them in canonical form), and double-colon used twice—which must fail.
If you accept IPv4 literals for transition technologies, segment those tests from “pure v6” user input. Mixed-mode products confuse users who paste v4 into v6-only fields even when the backend could map them.
Workflow that keeps configs honest
Generate a short IPv6 batch, paste into a scratch buffer, and rewrite anything you will publish into 2001:db8:: documentation space when the text leaves your laptop. Keep raw random output for local mocks. Your future self debugging a customer ticket will be glad the public docs never pointed at a live network.
Version-control config templates alongside application code. When a customer pastes an address from your docs into a support ticket, you want to recognize documentation space instantly. That recognition short-circuits panic about “someone published our internal prefix”—it is the textbook prefix everyone shares.
Teaching sales engineers to demo dual-stack
Live demos should show one documentation v6 on a slide and the operator’s real v4 or v6 from a lookup tab when explaining “what we see on the wire today.” Mixing them without labels confuses buyers who think the slide literal is their home prefix. A thirty-second narration—“this hex is textbook space; this quad is my exit”—prevents support tickets after the pilot.
Reverse proxies that log X-Forwarded-For may store v6 with zone IDs stripped. When you replay logs into a staging parser, use generator samples for missing fields rather than copying production literals into git. Staging stays realistic; compliance stays intact.
