ip6addrctl: Reference RFC 6724 instead

[jlduran]

ip6addrctl.8: Reference RFC 6724 instead

Commit e695500 updated the policy table to match RFC 6724, which obsoletes RFC 3484.

Add a reference to RFC 6724, and mark it up as a technical report (%R).

---

ip6addrctl: Update the sample configuration file

Update the sample ip6addrctl.conf.sample file to match the default policy, currently based on RFC 6724.

---

getaddrinfo.{1,3}: Cross-reference ip6addrctl(8)

[concussious]

I think this is a very nice addition. These RFCs are standards for this implementation, right? Would you be willing to s/EE ALSO/TANDARDS/?

Edit: If you do so, you will need a .Pp in between the bibliographic blocks to preserve the spacing.

[jlduran]

I think this is a very nice addition. These RFCs are standards for this implementation, right? Would you be willing to s/EE ALSO/TANDARDS/?

Edit: If you do so, you will need a .Pp in between the bibliographic blocks to preserve the spacing.

Done! Thank you!

[concussious]

LGTM!

[concussious]

Please excuse me for not following though enough initially, but I had some new ideas:

1. Looking at the referenced commit, updating to the new standard was MFC'd to 13.0, therefore this documentation fix should also have a commit message trailer like MFC after: 3 days.

2. Since RFC 6724 obsoletes RFC 3484 (and crossreferences it), does it make sense to remove RFC 3484?

3. The standards sections often uses a syntax like:

.Nm
conforms to
.Rs
...

Or is expected to conform to. Thoughts?

[jlduran]

1. Looking at the referenced commit, updating to the new standard was MFC'd to 13.0, therefore this documentation fix should also have a commit message trailer like MFC after: 3 days.

Yes, but normally I do not add that line. It has usually been up to the committer. If I remember correctly, some committers have automated workflows, that add the GH pull request line, the Reviewed by line, etc. By applying the MFC line, instead of helping, I'm getting in the way.

2. Since RFC 6724 obsoletes RFC 3484 (and crossreferences it), does it make sense to remove RFC 3484?

It is a valid point. I'll also update the sample file, although it is not installed.

3. The standards sections often uses a syntax like:

.Nm
conforms to
.Rs
...

Or is expected to conform to. Thoughts?

Yes, it usually refers to some POSIX standard(s), and normally not cited like a bibliography. These RFCs are "proposed standards", technically not standards (but mature, well-reviewed specifications). Let me know if we should move them back to the SEE ALSO section.

[concussious]

I recently found out that was the case for the pull request trailer, but I'm still under the impression that MFC is up to the author to suggest (and apologize I am mistaken).

I still think that they belong in standards if you find that language inappropriate, but all of these choices are your own.

My suggestions/questions/approval is just one reviewer's efforts to be helpful. Thanks!

[jlduran]

I still think that they belong in standards if you find that language inappropriate, but all of these choices are your own.

While I also agree, I'll leave it under SEE ALSO, to match the related getaddrinfo(3) man page, and marking it up as %R (Technical Report).

My suggestions/questions/approval is just one reviewer's efforts to be helpful. Thanks!

Highly appreciated, thank you!

[concussious]

If you provide some instructions, I would be happy to test this change.

[jlduran]

If you provide some instructions, I would be happy to test this change.

It is no big deal, ip6addrctl(8) is a user space utility that allows you to configure a source address selection policy, as outlined in RFC 6724.

We'll be using The KAME project site for testing, as a tribute to the FreeBSD IPv6 stack. As much as I'd like to test with a dancing turtle (kame 亀), different browser implementations will make it hard. So we'll stick to the terminal.

1. Verify that our dual-stack (IPv6 and IPv4) is working:

   % ip6addrctl 
   Prefix                          Prec Label      Use
   ::1/128                           50     0        0 # Loopback
   ::/0                              40     1 NNNNNNNN # Default unicast route
   ::ffff:0.0.0.0/96                 35     4        0 # IPv4-mapped
   2002::/16                         30     2        0 # 6to4
   2001::/32                          5     5        0 # Teredo
   fc00::/7                           3    13        0 # ULA
   ::/96                              1     3        0 # IPv4-compatible [Deprecated (RFC 4291)]
   fec0::/10                          1    11        0 # Site-local (RFC 1884)
   3ffe::/16                          1    12        0 # 6bone (RFC 5156) [Returned]

   By default, FreeBSD uses the table in RFC 6724, changed in e695500.

2. Using getaddrinfo(1), query The KAME project's web site. getaddrinfo(1) is simply a user space wrapper for getaddrinfo(3), which is ultimately our objective.

   % getaddrinfo www.kame.net
   dgram inet6 udp 2001:2f0:0:8800::1:1 0
   dgram inet6 udp 2001:2f0:0:8800:226:2dff:fe0b:4311 0
   stream inet6 tcp 2001:2f0:0:8800::1:1 0
   stream inet6 tcp 2001:2f0:0:8800:226:2dff:fe0b:4311 0
   seqpacket inet6 sctp 2001:2f0:0:8800::1:1 0
   seqpacket inet6 sctp 2001:2f0:0:8800:226:2dff:fe0b:4311 0
   dgram inet udp 210.155.141.200 0
   stream inet tcp 210.155.141.200 0
   seqpacket inet sctp 210.155.141.200 0

   Notice how the IPv6 addresses are shown first.

3. We'll change the precedence, so that IPv4-mapped addresses are preferred. We can easily do this by issuing service ip6addrctl prefer_ipv4, but we'll use ip6addrctl and our sample file.

   Create a copy of the ip6addrctl.conf.sample file updated in this patch, and assign the line that contains the label 4 (IPv4-mapped) a precedence of 100, as stated in section 10.3 of RFC 6724.

   The resulting file should look like this:

   % cat myip6addrctl.conf
   # default policy table based on RFC 6724.
   # usage: ip6addrctl install path_to_this_file
   #
   #
   #Format:
   #Prefix       Precedence Label
   ::1/128               50     0
   ::/0                  40     1 # <- 40 precedence, lower than
   ::ffff:0:0/96        100     4 # <- 100 precedence
   2002::/16             30     2
   2001::/32              5     5
   fc00::/7               3    13
   ::/96                  1     3
   fec0::/10              1    11
   3ffe::/16              1    12

4. Flush the current policy, and issue the command as documented in the file:

   # ip6addrctl flush
   # ip6addrctl install myip6addrctl.conf

5. Verify that IPv4-mapped addresses have a priority of 100, and test with The KAME project. Your system now prefers IPv4 addresses:

   % getaddrinfo www.kame.net
   dgram inet udp 210.155.141.200 0
   stream inet tcp 210.155.141.200 0
   seqpacket inet sctp 210.155.141.200 0
   dgram inet6 udp 2001:2f0:0:8800:226:2dff:fe0b:4311 0
   dgram inet6 udp 2001:2f0:0:8800::1:1 0
   stream inet6 tcp 2001:2f0:0:8800:226:2dff:fe0b:4311 0
   stream inet6 tcp 2001:2f0:0:8800::1:1 0
   seqpacket inet6 sctp 2001:2f0:0:8800:226:2dff:fe0b:4311 0
   seqpacket inet6 sctp 2001:2f0:0:8800::1:1 0

6. Revert by issuing service ip6addrctl prefer_ipv6 and removing the test file.

Perhaps, a more realistic scenario would be when an organization that only uses a Unique Local Addresses (ULA) prefix internally, and Network Prefix Translates (NPTv6) it into a Global Unicast Addresss (GUA) prefix (some network administrators are used to a similar setup with IPv4). The problem is that ULAs have a precedence of 3 by default, lower than the 35 assigned to IPv4-mapped addresses. Manually assigning ULAs a higher precedence should be necessary (ouch!).

At any rate, this is a not-so-exciting change. It is mostly a documentation update, there is really nothing to test. But thank you for the offer!

Although, there is an effort to modernize/cleanup some userland utilities, by using getaddrinfo(3), for example. That can really benefit from testing!

[jlduran]

cc/ @hrs-allbsd @lwhsu

[markjdb]

@glebius does this change look ok to you?

[hrs-allbsd]

It looks good to me. Since the sample configuration file is not installed, simply dropping it might be another option.

[concussious]

Thanks @jlduran! Awesome detailed instructions!

[glebius]

@glebius does this change look ok to you?

To be fair, don't feel myself expert here. Maybe @AlexanderChernikov or @bu7cher can help?