Handbook WG - network

[carlavilla]

Summary

The idea is to create a chapter with basic network configuration.

For example right now if you look into the handbook how to configure a wireless connection is in the "advanced networking chapter" (weird hehe)

The idea is to move information from other chapters to this new chapter.

Content:

• How to set up the network
• How to configure a wired/wireless network
• How to set up the hostname
• How to configure the DNS
• Basic virtual hosts
• Basic Troubleshooting

Output: https://www.carlavilla.es/freebsd/network.html

[fernape]

documentation/content/en/books/handbook/network/_index.adoc

117

I would simplify this sentences. Something like:

The text before the '@' symbol is the name of the driver controlling the device.

118

In this case are man:em[4] and... --> In this case these are man:em[4] and...

146

I would clarify as this:

...followed by the order in which... --> ...followed by a number representing the order in which...

160

This paragraph should probably be shown after the actual example.

208

We can use here Configuring Static IPv4 Address since in the next paragraph we use IPv6 instead of IP Version 6

384

I would use IPv6 here too.

396

s/folloing/following/

[carlavilla]

Fix comments from Fernando and add more sections. WIP

[• karels]

Looks like a good start.

documentation/content/en/books/handbook/network/_index.adoc

91

Join the last two sentence (fragments).

93

FreeBSD also includes support for a number of software network interfaces such as the loopback, man:lo[4].

127

For example, to load the man:alc[4] module, execute the following command:

131

Shouldn't this just be if_alc (no _load appended)?

146

I still find this sentence cumbersome. Also, I'd use "adapter" rather than "card", as not all interfaces are on cards, and there are cards with multiple interfaces.

149

186

s/card/interface/

195

s/card/interface/, here and later

226

Should we be modern and show CIDR notation too (ifconfig em0 inet 192.168.1.150/24)? I'd show both.

266

267

Would it be worthwhile mentioning how to run dhclient manually (just "dhclient interface_name"? That way, you can see if it succeeds. But it goes into background if it times out, and may need to be killed.

268

318

384

This seems like too much detail; things like site-local don't really need to be here. We could label the table something like "Example IPv6 Reserved Addresses" to make it clear that it is incomplete. Or these could be called something else, like types of addresses.

434

I don't understand this entry; 16 bits are shown, or 14 if you omit the always-0 bits. And with the ::, the examples are 128 bits. Should this be /16?

442

Why is rtsol needed for a static IPv6? I don't use it. I thought it was just for SLAAC. I think dynamic addressing should be a separate section. Also, I'd put a comma after "static IP address", and refer to rtsold(8).

503

s/stepp/step/

[carlavilla]

documentation/content/en/books/handbook/network/_index.adoc

131

I took the example from alc[4] and says:

     Alternatively, to load the	driver as a module at boot time, place the
     following line in loader.conf(5):

	   if_alc_load="YES"

146

Much better!

384

Good idea, I like it

[carlavilla]

Fix some comments and upgrade the rest of the chapters.

[• karels]

documentation/content/en/books/handbook/network/_index.adoc

131

That's correct for loader.conf, but not for the manual command above. Try it.

[carlavilla]

documentation/content/en/books/handbook/network/_index.adoc

131

you're right :)

434

TBH, I took this table from the advanced networking chapter, I don't know if the info is right or not

[carlavilla]

Finish the chapter and fill almost all the comments

[carlavilla]

@bapt can you please take a global look to the new network chapter? Thanks!

[dbaio]

Single HTML / books.adoc: Needs to add the new network chapter to it.

Besides that, the overall structure seems fine.

Note for future work:

• Replace all fxp* references for something newer all over the Handbook.

documentation/content/en/books/handbook/advanced-networking/_index.adoc

70

We should add links between network/ and advanced-networking/ chapters.

Add a new topic here:

• Understand basic network configuration on FreeBSD (Network[link]).

documentation/content/en/books/handbook/network/_index.adoc

908

Virtual hosts with several IPs is an outdated approach to implementing SSL/TLS, I don't know if it's only with me, but this chapter bothers me for being here.
Maybe move this to the Advanced Networking chapter?
Or rewrite it, saying only how to add aliases. But I don't have a strong opinion about what is better here.

998

We should add links between network/ and advanced-networking/ chapters.

Maybe adding this on the bottom here.

• Advanced topics
  
  See the Advanced Networking(link) chapter for more details and advanced networking topics.

[bcr]

Looks good to me, thanks for working on this!

[carlavilla]

I made the commit, we can improve the chapter later.
I want to continue with the next chapter, config and I need this in the tree

[• karels]

Sorry if I missed some of these before. Overall, looking very good!

documentation/content/en/books/handbook/network/_index.adoc

213

Here and a couple of lines down are two remaining references to NIC; I prefer just "interface".

497

I don't think dhcient supports IPv6. I'm not sure of the state of play on DHCPv6. rtsold implements SLAAC (Stateless Address Auto-Configuration) as a daemon, or if invoked as rtsol, it runs in foreground and accepts an interface name. I think DHCP can just be removed from the rc line.

510

This should be done only on a router, and advertises the network prefix as well as default route.

797

Maybe show an FQDN. maybe freebsdhostname.example.com?

807

Similarly, use an FQDN.

815

s/who/that/

818

[• karels]

Have you asked Bjorn Zeeb to review this? He is the IPv6 expert and one of the WiFi experts.

[grahamperrin]

Noted with thanks:

• Handbook WG - Create a new network chapter · freebsd/freebsd-doc@b113509

– b113509f32da681db41fd60594b723c13334df8e

[carlavilla]

Fixed and I'll ask for a review to Bjorn Zeeb, good idea