Page MenuHomeFreeBSD

handbook/config: Add section on configuring IPv6
Needs ReviewPublic

Authored by debdrup on Feb 12 2021, 5:17 PM.

Details

Reviewers
phk
gnn
bz
hrs
Group Reviewers
docs
Summary

Since the IPv6 implementation is a quarter century in the making,
it's time for the FreeBSD handbook to catch up and document how to do
this outside of bsdinstall.

Submitted by: phk (earlier version)
PR: 253453

Diff Detail

Repository
R9 FreeBSD doc repository
Lint
No Linters Available
Unit
No Unit Test Coverage
Build Status
Buildable 37189
Build 34078: arc lint + arc unit

Event Timeline

debdrup created this revision.
thj added inline comments.
documentation/content/en/books/handbook/config/_index.adoc
418

I think this and the one below for v6 should be "Network Interface" rather than card

518

IPv6 configuration is separated from IPv4 configuration in [.filename]#/etc/rc.conf# IPv4 configuration is unaffected by IPv6.

518
535

This is not helpful language.

Here you should explain how to restart networking without a reboot. Sadly there is not a v6 only service restart netif.

Reboot should be suggested as a way to 'validate' the persisent config only

539

ping now has the -6 flag

562
564
566

which autoconfiguration protocol? A name will help people do more research and understand

568
590
592
593

please check that prefix is correct. I think ipv6 subnet is almost always wrong

595
597

delete

599

I am not sure about the advice in everything below this point.

I think it is an 'advanced' topic, the information in chapter 32.9 is clear and the resource I use when I have to manually setup v6.

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

That chapter really isn't advanced networking, but that is a different review.

This revision is now accepted and ready to land.Feb 12 2021, 6:34 PM

first pass at a review

documentation/content/en/books/handbook/config/_index.adoc
539

ping6 has been merged into ping, so we should use ping -6 here, unless we want to be really daring and set ip6addrctl_policy=“ipv6_prefer"

590

drop obviously.

595

should this be:

Even if your ISP *supports* it

?

621

now we're using ie0 instead of ed0?
oh, this is for internal LAN.
maybe we should announce this on top, too

635

the does not -> that does not

Thank you for your effort in updating the IPv6 parts of the runbook! It's awesome to have if refreshed.
Please see some comments inline.

documentation/content/en/books/handbook/config/_index.adoc
550

Didn't we deprecate ed? Maybe it's worth grabbing em as that's the common interface used in physical servers/VMs?

553

Maybe we can use mac documentation prefix 00-53-00 and IPv4 documentation prefix 192.0.2.0/24 to make it easier to grasp?

572

probably worth considering showing shortcut syntax (-6 instead of -f inet6) ?

592

Maybe we could consider laying out multiple approaches from IPv6 BCPs like RFC 7381 and explain how to configure them.
It will be up to the user to actually decide what approach suits best for him.

621

Probably worth considering em instead of ie (was the latter 10Mbit/s driver)?

documentation/content/en/books/handbook/config/_index.adoc
592

That would be wonderful, I spent quite some time looking for precisely that kind of document, which is why I ended up doing this write-up.

621

Please see the Note at the bottom :-)

I should add: I have absolutely no fine feelings about this text, feel free to beat it into any kind of shape you thing suits the project these days.

debdrup marked 27 inline comments as done.

Address feedback by multiple people

This revision now requires review to proceed.Feb 19 2021, 2:38 PM
documentation/content/en/books/handbook/config/_index.adoc
553

I changed the MAC prefix as requested, but since IPv4 and IPv6 configuration aren't really linked, I would prefer leaving the ellipsis for IPv4 as there's no way to know what blocks or VLSM is used.

592

This seems supplemental and can be added in a later commit by a subject matter domain expert (which I am not, despite 20-odd years of being a network admin), if and when a phrasing can be worked out.

599

Equivalent instructions aren't provided, so unless you're volunteering to move the instructions to that file, I'm happy to leave them as they are.

One advantage of this is also that this will match the expectations non-advanced users have about how IPv4 is configured (ie. where NAT is almost-ubiquitous.

621

I changed ed0 and ie0 to em0 and em1, because ed0 is deprecated and ie(4) has no manual page.

Avoid the use of you, with some suggestions on how to fix it.
I generally like the update, though. Thanks for writing it.

documentation/content/en/books/handbook/config/_index.adoc
519

s/all this/all of this/

524

We discourage the use of 'you', so you could write at the end: ... and the ISP routes to use.

554

Another use of 'you' here.

572

And 'you' again.
2001:db8:: will not appear here, but the assigned ISP's IPv6 prefix endpoint instead.

576

Some IPv6 routes are available now:

598

s/your/the/

600

s/your/the/

603

s/your/the/g

605

s/and if you follow/and when following/
s/and use random numbers/and random numbers are used/
s/you are/it is/
s/as you did//

618

/Your/This/

643

s/you used a different netmask for you internal network/a different netmask for the internal network is used/

669

Long sentence, probably better to split it in two to also kill the 'you':
(A bug in FreeBSD-12 prevents this from working. Enter the actual address ... on the em0 interface and change it in case the ISP changes...)

700

s/You do not need/There is no need/