Page MenuHomeFreeBSD

netlink: add netlink user documentation.
ClosedPublic

Authored by melifaro on Oct 15 2022, 4:38 PM.
Tags
None
Referenced Files
Unknown Object (File)
Tue, Jan 24, 2:00 AM
Unknown Object (File)
Jan 6 2023, 6:41 PM
Unknown Object (File)
Jan 6 2023, 2:18 PM
Unknown Object (File)
Dec 15 2022, 8:14 PM
Unknown Object (File)
Dec 15 2022, 6:17 AM
Unknown Object (File)
Dec 14 2022, 3:28 AM
Subscribers

Details

Summary

Add documentation that initially appeared in D36002.
These manpages address most (if not all) comments from the D36002.
rtnetlink(4) has been expanded to include more details on the netxthops, interfaces, addresses and neighbours.
genetlink(4) has been added.

Diff Detail

Repository
rG FreeBSD src repository
Lint
Lint Not Applicable
Unit
Tests Not Applicable

Event Timeline

pauamma added a subscriber: pauamma.

Will review the rest later.

share/man/man4/genetlink.4
32
43
44–45

Maybe use "string family name" throughout instead? Having both a string identifier and another id(entifier) of an unspecified type is confusing.

46–47

"the application" or "applications" (leaning toward the latter).

48
50
53

Not sure "families" is right, but there's definitely a word missing.

64–66

Or remove "The".

69

Same as above.

71
73

Needs to say which family id it has, here or somewhere. Here is probably best.

81

What I think you mean.

This revision now requires changes to proceed.Oct 15 2022, 10:59 PM

Done for this round.

share/man/man4/netlink.4
57

VNETs? Not other kinds of network?

68
84
112

Spurious space.

276
share/man/man4/rtnetlink.4
104
105
110

VNET?

135–136
222

Or "The required objects are" if more than 1.

290
293

Is this really restricted to VNETs?

296
309

For brevity and consistency with later ones.

311
341

Is there an active 802.1x standard other than 802.11?

421–423

US spelling

437

(or get rid of "The")

454
463
470
476

Also, VNET?

492
494
504
bapt added inline comments.
share/man/man4/netlink.4
236

NETLINK_DROP_MEMBERSHIP

melifaro marked 32 inline comments as done.

Address the comments.

share/man/man4/genetlink.4
73

GENL_ID_CTRL is the actual Id. I’d rather not specify its value here, to avoid any encouragement for using number instead of a header constant. Also typically we don’t provide such mappings in man page. Thoughts?

share/man/man4/netlink.4
57

Vnets. Or namespaces in Linux land

share/man/man4/rtnetlink.4
110

Yes.

293

Well, yes. Similar to ifconfig. There is a socket option & attribute that allows to interact with the objects in the VNET different from the current one, but it’s not implemented yet.

341

A lot (even too many, maybe). 802.1D is about bridging, including loop prevention protocols, .1Q is about vlans and so on. 802.1X is a standard handling authentication in LAN / wireless. If network is using it, there will be a temporary state when an interface is already able to send/receive frames, but encryption is not negotiated yet. This condition is an example of the aforementioned state.

Other than a few nits all fixable on commit, LGTM. If it matches the implementation, it's good to go.

share/man/man4/genetlink.4
28

Bump on commit.

73

Never mind. I misparsed the whole paragraph. Ignore the noise.

share/man/man4/netlink.4
112

"32-bit" when the length is in bytes doesn't look quite right. For consistency, I'd change the other occurrences as well.

200

"message", maybe?

277
341
This revision is now accepted and ready to land.Nov 1 2022, 2:27 PM
melifaro added inline comments.
share/man/man4/netlink.4
341

Mm, I'm a bit unsure about this one. Technically it's indeed an OS feature, but it sounds a bit abstract to me. We typically say, "X has IPv6 [protocol] support" or "X has TCP [protocol]" and refer to the word "feature" when there is no better word to describe it. Thoughts?

This revision was landed with ongoing or failed builds.Nov 1 2022, 5:08 PM
This revision was automatically updated to reflect the committed changes.
share/man/man4/netlink.4
341

Well, there's definitely a word missing, so we need to choose one to add. I was trying to avoid repeating "protocol", but that would work.