IPv6 handbook improvements

[Peter Sagerson]

Hello all,

I recently went through a voyage of discovery getting access to my ISP's recently-introduced native IPv6. When my consumer router failed to come through, it seemed like a perfect opportunity for a little FreeBSD project. It turned out to be a bit of an adventure, though, as practical information about IPv6 seems surprisingly hard to come by and the handbook's page appears to be rather out of date. I would be happy to contribute some fixes and new content to the page, but I'm not sure what that process looks like, so I figured I'd start here.

Assuming no changes to the basic structure of the document, the first thing to do is obviously to add a CPE section, probably based on the relevant content in section 3.2.4 of the 9.0 detailed release notes.[1] ipv6_cpe_wanif is crucial to the home- or office-router scenario. Those release notes turned out to be the most obscure piece of indispensable documentation I found.

More generally, I think there's probably an expository section missing about whether and how to enable IPv6 on individual interfaces and the common options available. Also the relationship between router advertisement and DHCPv6 and the common use of self-assigned addresses in various /64 subnets. It would probably be especially helpful to identify areas where IPv4 analogies hold and areas where IPv4-based instincts are likely to lead one astray. This section might also include pointers on things like bridging and pf, if only to reassure the reader that all of the same rules apply as for IPv4.

On a more specific note, the reserved address section still lists the fec0::/10 site-local addresses, despite the fact that these were deprecated over nine years ago in RFC 3879. RFC 4193 specifies unique local addresses in fc00::/7 (in practice, currently fd00::/8) to replace them.


Just to sum up in a handy list, here are the things that I needed to discover in my particular--hopefully increasingly common--situation of sharing my ISP's native IPv6 with my LAN and that I'd like future users to be able to find in the handbook:

- ipv6_cpe_wanif is necessary to make the system act like a traditional home/office router with a WAN side and a LAN side.

- IPv4's local subnets (192.168/16, etc.) are replaced by globally unique /64 subnets in fd00::/8. Ideally, FreeBSD would have a tool to generate global IDs according to the RFC (SHA1(ntp-time, EUI-64(mac))[-5:]), but all you really need in practice in this scenario is five random bytes (dd bs=1 count=5 if=/dev/random | hexdump). Frankly, you can probably get away with fd00::/64, but I'd hesitate to recommend it.

- LAN clients can generally just self-assign IPv6 addresses, so no need for a DHCP server here. However, my ISP still uses DHCPv6 to assign a publicly routable address to the WAN interface. rtsold_flags="-O /path/to/script/run-dhclient-v6" should take care of this, although rtsold seems to be ignoring this documented setting, so there may be a bug here. Some ISPs might also use DHCPv6's prefix delegation, but I can't speak to that.


On a more general topic, one of the things that was enormously helpful to me recently was discovering the man page for rc.conf. I have long wished for some general reference to rc.conf variables, but somehow never found this document or thought to look there. Maybe that's unusual, or maybe it's one of those things that the knowledgable take for granted, so it slips through the documentation cracks. One thing I can say is that in the Advanced Networking chapter of the handbook, there are many many references to rc.conf and its various settings, but only one link to the man page (in section 30.2.4). As an intermittent-to-casual user who leans fairly heavily on the handbook, I would suggest linking to this reference rather more prominently and regularly. It's extremely helpful both as a map of the possibilities and as a way to discover ancillary settings (foo_flags) that may not merit inclusion in the handbook itself.

As I said at the top, I'm happy to actually propose a diff for the IPv6 page, although it will presumably want an editor with deeper IPv6 and/or FreeBSD experience to smoke out inaccuracies and over-generalizations. Please advise if you'd like me to take this to the next step and what that process looks like.

Thanks,
Peter


[1] https://www.freebsd.org/releases/9.0R/relnotes-detailed.html#AEN1395
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 841 bytes
Desc: Message signed with OpenPGP using GPGMail
URL: <http://lists.freebsd.org/pipermail/freebsd-doc/attachments/20140223/5e954995/attachment.sig>