# The handbook on IPv6 is .. lacking.



## johnblue (Dec 29, 2018)

(this is an airing of handbook instructional grievances from an IPv6 via DHCP newbie)

https://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/network-ipv6.html

31.9 starts off with this encouraging statement:





> This section focuses on getting IPv6 configured and running.


Great!  That is why I am reading the handbook.  

The first problem is that section 31.9.1 makes the assumption that IPv6 is ready to go:





> To view a FreeBSD system's IPv6  address, use ifconfig(8):
> 
> rl0: flags=8943<UP,BROADCAST,RUNNING,PROMISC,SIMPLEX,MULTICAST> mtu 1500
> inet 10.0.0.10 netmask 0xffffff00 broadcast 10.0.0.255
> inet6 fe80::200:21ff:fe03:8e1%rl0 prefixlen 64 scopeid 0x1



During a clean install the *only* way to enable IPv6 on an interface would be to choose SLAAC.  The result of that choice is an edit to /etc/rc.conf:
	
	



```
ifconfig_your-interface-here_ipv6="inet6 accept_rtadv"
```

If SLAAC was not selected then ifconfig(8) is only going to return that the interface is configured for IPv4.  This misleading workflow immediately causes confusion, "Why didn't I get the same result as the handbook?"  Follow by absolutely nothing to assist the reader to understand the discrepancy.

If you are thinking that the handbook was going to be able to re-rail itself in 31.9.2 you could not be more wrong.  This is where the cars in this train wreck start piling up:


> 31.9.2. Configuring IPv6
> 
> To configure a FreeBSD system as an IPv6 client, add these two lines to rc.conf:
> 
> ...



I think the thing that most annoys me about this blurb is that a) it wasted my time and b) it presents an incredibly simplistic "world view" of how to configure IPv6 on FreeBSD wherein SLAAC and a statically assigned address are the only two options.  The following subsections need to be added to 31.9.2 and walked out:

31.9.2.1 - Configure SLAAC
31.9.2.2 - Configure a DHCPv6 client
31.9.2.3 - Configure a static assignment

The next section made me laugh a bit:





> 31.9.3. Connecting to a Provider
> 
> In order to connect to other IPv6 networks, one must have a provider or a tunnel that supports IPv6:
> 
> Contact an Internet Service Provider to see if they offer IPv6.


Really?  Can someone please be sure to get Captain Obvious a byline credit on this?



I do not have enough experience to comment on the rest of section 31.9.3 plus sections 31.9.4 and 31.9.5 but it appears like these cars stayed on the tracks insomuch as that a bit more effort was attempted at providing guidance.

This is one of those time where I can answer the question "Did you read the handbook?" with a "yes, and it sucked."


----------



## drhowarddrfine (Dec 29, 2018)

Why are you telling us? What are we supposed to do about it? Most unhelpful! Did you report this?


----------



## scottro (Dec 29, 2018)

The forum is not really a place to reach anyone who can do anything about it. The mailing lists might  have people see and helpfully react, but the best thing to do is file a pr against documentation.

The handbook is good for basic things, but, (not so much ipv6, haven't tried the handbook on that) but especially on 3rd party things, will frequently be lacking. If you complain on these forums, you'll usually be told to file a pr or write the documentation yourself, which is, of course, not useful in solving an immediate problem. 

However, these forums can be very helpful, if you can isolate a problem, or even show how far you were able to get--such as, read the handbook, but now I want to do X, and if the handbook shows it, I'm missing it. (Note that it's  best to assume you missed it, because you probably did, even if "it" is in some place that the average person wouldn't think of looking)


----------



## johnblue (Dec 29, 2018)

Gents .. thought I did a good job of stating the intent of the post.

Stand down red alert .. no action needed or requested.


----------



## Datapanic (Dec 29, 2018)

I'm going to retire before I need to know how to use IPv6 for a living, but maybe if you're not, you should write up a How To on FreeBSD and IPv6 for those that come after us


----------



## johnblue (Dec 29, 2018)

> I'm going to retire before I need to know how to use IPv6 for a living, but maybe if you're not, you should write up a How To on FreeBSD and IPv6 for those that come after us


It is always amazing to me when I reach a point of diminishing returns on a thing that I really enjoyed what I was doing but now it is like .. yeah .. no.

heh.

Yes sir, given my level of frustration on this .. a how-to will be an output.


----------



## SirDice (Dec 31, 2018)

johnblue said:


> (this is an airing of handbook instructional grievances from an IPv6 via DHCP newbie)


Everybody is more than welcome to send in submissions for changes or updates. You don't need to be a registered committer or have any other kind of "special" access. The only requirement is a willingness to participate. 

FreeBSD Documentation Project Primer for New Contributors


----------

