tcp_bblog.4: Add a manual page for TCP Blackbox Logging

[gbe]

Summary

Add a manual page for the TCP Blackbox Logging.

The tcp_bblog facility provides structured logging of TCP stack activity
for debugging and performance analysis. It is implemented in the kernel
and allows per-connection tracing of TCP events with low overhead.

MFC after: 1 week
Relnotes: yes

Test Plan

mandoc -Tlint checks

[tuexen]

share/man/man4/tcp_bblog.4

15

I don't see this anywhere in the tree. Remove this line?

49

... or tcpsso. You might want to mention it.

86

This directory is not specific to black box logging, but the userland tool tcplog_dumper. Not sure if it should be mentioned here.

93

Maybe: Enable continual logging for all TCP connections:

97

You might want to add a note that using a config with

net.inet.tcp.bb.log_auto_mode=1

keeps up to the last net.inet.tcp.bb.log_session_limit entries stored at the TCP endpoint. Nothing is dumped to disk.
So when debugging TCP related panics, this is a good way to capture information about the panic.

108

You also might want to cross reference to tcpsso.8. The man page shows an example how to enable continual logging for a specific TCP connection via the command line.

122

It was written by Jonathan Looney (jtl) and Randall Stewart (rrs), not by me.

[tuexen]

Thanks for the effort of writing an initial man page. I wanted to do this for a long time...

[tuexen]

share/man/man4/tcp_bblog.4

108

You might also add a reference to Adventures in TCP/IP: TCP Black Box Logging.

[ziaee]

Couple of minor nits, thank you so much for doing this! Also, don't forget to add this manual to the Makefile!

share/man/man4/tcp_bblog.4

2–6

we still use this blank comment for consistency with C, but we don't use the hyphen anymore. style.9 and the licensing guide suggest putting the copyright at the top in spdx only format.

14

these don't need to be quoted, and thank you so much for using mdoc conformant style.

51–52

72–73

[gbe]

tcp_bblog.4: Incorporate Feedback

• Update Copyright statement to match style(9)
• Mention tcpsso(8)
• Add a note about the possible usage of net.inet.tcp.bb.log_auto_mode=1
• Mention FreeBSD Journal entry "Adventures in TCP/IP: TCP Black Box Logging"
• Correct the authors section
• Connect tcp_bblog.4 to the build

[gbe]

share/man/man4/tcp_bblog.4

97

I mentioned it in the CONFIGURATION section.

[gbe]

incorporate feedback

[ziaee]

Would you also add a Relnotes: yes? I'd like to list all new manpages in the manpage section of the release notes.

share/man/man4/tcp_bblog.4

72–73

This was for padding

96

These are not sentences and traditionally do not have periods or capital letters.

[gbe]

• Address Comments

[gbe]

Address comments by @ziaee

[ziaee]

LGTM with the highlighted attribution fix. Thanks for writing this!

share/man/man4/tcp_bblog.4

122

This still needs to be fixed.

[gbe]

share/man/man4/tcp_bblog.4

122

It's already fixed in the AUTHORS section. But this mentioned paper was written by Randall and Michael.

[ziaee]

Oh I see

[tuexen]

share/man/man4/tcp_bblog.4

122

It is fixed. The comment was about the code, not the article.