Page MenuHomeFreeBSD

Handbook WG - network
ClosedPublic

Authored by carlavilla on Jun 14 2023, 7:33 PM.
Tags
None
Referenced Files
F103312316: D40546.id123742.diff
Sat, Nov 23, 10:13 AM
F103292418: D40546.id.diff
Sat, Nov 23, 3:50 AM
F103270313: D40546.id123512.diff
Fri, Nov 22, 9:24 PM
F103241535: D40546.id123742.diff
Fri, Nov 22, 1:28 PM
Unknown Object (File)
Fri, Nov 22, 11:44 AM
Unknown Object (File)
Fri, Nov 22, 6:31 AM
Unknown Object (File)
Thu, Nov 21, 9:09 AM
Unknown Object (File)
Thu, Nov 21, 8:48 AM

Details

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

Diff Detail

Repository
R9 FreeBSD doc repository
Lint
Lint Skipped
Unit
Tests Skipped

Event Timeline

carlavilla created this revision.
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 marked 7 inline comments as done.

Fix comments from Fernando and add more sections. WIP

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 added inline comments.
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 marked 3 inline comments as done.

Fix some comments and upgrade the rest of the chapters.

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 added inline comments.
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 marked an inline comment as done.

Finish the chapter and fill almost all the comments

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

carlavilla added a reviewer: jhb.

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–71

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
909

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.

999

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.
carlavilla marked 3 inline comments as done.

Looks good to me, thanks for working on this!

This revision is now accepted and ready to land.Jul 6 2023, 7:30 AM

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

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

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

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

496

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.

509

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

796

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

806

Similarly, use an FQDN.

814

s/who/that/

817

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

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