From owner-freebsd-doc@FreeBSD.ORG Sun Feb 23 20:33:19 2014 Return-Path: Delivered-To: freebsd-doc@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTPS id 593122D6 for ; Sun, 23 Feb 2014 20:33:19 +0000 (UTC) Received: from aspen.ignorare.net (unknown [IPv6:2600:3c01::f03c:91ff:fe69:913d]) (using TLSv1.1 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.freebsd.org (Postfix) with ESMTPS id 32E4212DC for ; Sun, 23 Feb 2014 20:33:18 +0000 (UTC) Received: from [192.168.1.10] (c-76-121-48-30.hsd1.wa.comcast.net [76.121.48.30]) (using TLSv1 with cipher ECDHE-RSA-AES256-SHA (256/256 bits)) (No client certificate requested) (Authenticated sender: psagers@ignorare.net) by aspen.ignorare.net (Postfix) with ESMTPSA id AFD2C3B93B for ; Sun, 23 Feb 2014 12:33:11 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=simple/simple; d=ignorare.net; s=201209; t=1393187591; bh=flGTp85VfJ+rCg5jbppacpzSgRBvrK7+aGmSGNSOVsY=; h=From:Subject:Date:To; b=cQPuKsaCNz7JsjriNwNOTg94ufqCiLlO0IU6Fg3LbpRxbQs5GOOjQcFjS7jLZxfx+ IPKEiIQHj1KjgegAqL6NvCtLyuPl2YcXDEqY4nhkvmcBaahlXt9L0ZGD7NewFsHK30 LUuQx4nmy31JIKn5vBUWFJZu+E3677S9RX3dM2L4= From: Peter Sagerson Content-Type: multipart/signed; boundary="Apple-Mail=_4E93B2C6-ECB0-4242-9A1E-EC29B81308AB"; protocol="application/pgp-signature"; micalg=pgp-sha1 Subject: IPv6 handbook improvements Message-Id: <3472A13A-348C-460F-A159-A78C46BB5243@ignorare.net> Date: Sun, 23 Feb 2014 12:33:10 -0800 To: freebsd-doc@freebsd.org Mime-Version: 1.0 (Mac OS X Mail 7.1 \(1827\)) X-Mailer: Apple Mail (2.1827) X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.17 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sun, 23 Feb 2014 20:33:19 -0000 --Apple-Mail=_4E93B2C6-ECB0-4242-9A1E-EC29B81308AB Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset=us-ascii 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=3D1 count=3D5 if=3D/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=3D"-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 --Apple-Mail=_4E93B2C6-ECB0-4242-9A1E-EC29B81308AB Content-Transfer-Encoding: 7bit Content-Disposition: attachment; filename=signature.asc Content-Type: application/pgp-signature; name=signature.asc Content-Description: Message signed with OpenPGP using GPGMail -----BEGIN PGP SIGNATURE----- Comment: GPGTools - http://gpgtools.org iQIcBAEBAgAGBQJTClsGAAoJENfXJ2LQ+g524rUQAJmMGwW1jraX6eL8r5+c40CW EHIPn7PhfJ4pAeHfF5kJxWnBznUQ7QbqbUlwLCiR5oSO8wRCMp8eoqvgJnbfDg+x 1CPeUgaiEhYwFw8/eKGyrSdwGgIvMOsJ2jnXB4C8TTsqhJ0JLEbFqKomHms1+OoN A5KqZsFVvNyA8O3dYVU+1MJB8HtF/VxGtfbuAC3wQWvoaIOt+h4q4dERbFes3Wx1 MMntJm5QUs2WU8DJ8E831mJ4XowckhmxdNweLvZ3waOSoe5ZqYbDheNTJ2xMuXWE 70kd6U/YN4zsdjey/3oDX3FPIM87JCYJAx6NQs8CDCtuFUUAt/sT/WVQRwxQe8Ua FIdvIKppm2meFLHbCmNLi7c8TvWX+3teRVTmIagwQEXgcg0Z9ENUNjTvORGkJrqY 9G4qlNAYaL2J7kzSz6GUlAtZzbDSlIkGd5U7vR4XVfxEgVROpHhQ45m8TZT+jLEB eo2ZjK/zUgv2ylmDGo01RLU0W+efYyBYP00VUtIh1ayugAacoheiPJ5Z2JYhQHRY pEVdDL8dEWYGNnkwzGodtSMeCYhQiA4oud6pxnCbcKBvJrauLdTdT28C9s3oFUve Qif7xjGYABrZA+tFaDenmrPJJEnd2QUPnkPJlQpO/VW+qIkp9UP7BrxvpQs3BqYs 4xYMWskJ/iz1NUufIXAV =2IUc -----END PGP SIGNATURE----- --Apple-Mail=_4E93B2C6-ECB0-4242-9A1E-EC29B81308AB--