git: c8e8fa04dc05 - stable/15 - tcp_bblog.4: Add a manual page for TCP Blackbox Logging

The branch stable/15 has been updated by gbe:

URL: https://cgit.FreeBSD.org/src/commit/?id=c8e8fa04dc05a1f23be4d618b52d68b6d2820aac

commit c8e8fa04dc05a1f23be4d618b52d68b6d2820aac
Author:     Gordon Bergling <[email protected]>
AuthorDate: 2026-07-12 10:25:01 +0000
Commit:     Gordon Bergling <[email protected]>
CommitDate: 2026-07-28 05:36:09 +0000

    tcp_bblog.4: Add a manual page for 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.
    
    Reviewed by:    tuexen, ziaee
    Relnotes:       yes
    Differential Revision:  https://reviews.freebsd.org/D56252
    
    (cherry picked from commit 62e22d7cfc1ca1c25bede6aaeca370c163a9a1ef)
---
 share/man/man4/Makefile    |   1 +
 share/man/man4/tcp_bblog.4 | 147 +++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 148 insertions(+)

diff --git a/share/man/man4/Makefile b/share/man/man4/Makefile
index 06726e0360a8..a8ed4efc6c44 100644
--- a/share/man/man4/Makefile
+++ b/share/man/man4/Makefile
@@ -591,6 +591,7 @@ MAN=	aac.4 \
 	tarfs.4 \
 	targ.4 \
 	tcp.4 \
+	tcp_bblog.4 \
 	tcp_bbr.4 \
 	tcp_rack.4 \
 	tdfx.4 \
diff --git a/share/man/man4/tcp_bblog.4 b/share/man/man4/tcp_bblog.4
new file mode 100644
index 000000000000..37c076dddfc5
--- /dev/null
+++ b/share/man/man4/tcp_bblog.4
@@ -0,0 +1,147 @@
+.\"
+.\" Copyright (c) 2026, Gordon Bergling <[email protected]>
+.\"
+.\" SPDX-License-Identifier: BSD-2-Clause
+.\"
+.Dd July 10, 2026
+.Dt TCP_BBLOG 4
+.Os
+.Sh NAME
+.Nm tcp_bblog
+.Nd TCP Black Box Logging facility
+.Sh SYNOPSIS
+.Cd options TCP_BLACKBOX
+.Sh DESCRIPTION
+The
+.Nm
+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.
+Each TCP endpoint may maintain an internal log buffer recording
+events such as packet transmission, reception, retransmissions,
+and state transitions.
+Unlike earlier debugging mechanisms,
+.Nm
+records structured metadata without capturing TCP payload data.
+Logs are exported to userland via the device
+.Pa /dev/tcp_log .
+If no process is actively reading from this device, log records
+may be discarded.
+Each log entry includes:
+.Pp
+.Bl -bullet -compact
+.It
+Connection identifiers, including local and remote addresses and ports
+.It
+Timestamp information
+.It
+TCP state and sequence variables
+.It
+Event-specific metadata
+.El
+.Pp
+Logging may be enabled globally using
+.Xr sysctl 8
+or on a per-connection basis using
+.Xr setsockopt 2
+or
+.Xr tcpsso 8 .
+.Sh MODES
+The following logging modes are supported:
+.Pp
+.Bl -tag -width "TCP_LOG_STATE_CONTINUAL" -compact
+.It Dv TCP_LOG_STATE_OFF
+Disable logging.
+.It Dv TCP_LOG_STATE_TAIL
+Maintain a ring buffer of recent events.
+.It Dv TCP_LOG_STATE_HEAD
+Log only the initial events of a connection.
+.It Dv TCP_LOG_STATE_HEAD_AUTO
+Log initial events and automatically export them.
+.It Dv TCP_LOG_STATE_CONTINUAL
+Continuously log and export events as buffers fill.
+.It Dv TCP_LOG_STATE_TAIL_AUTO
+Maintain a tail buffer and export on overflow.
+.El
+.Sh CONFIGURATION
+Global configuration is available via
+.Xr sysctl 8
+under the
+.Va net.inet.tcp.bb
+namespace.
+Notable variables include:
+.Bl -tag -width "net.inet.tcp.bb.log_session_limit" -compact
+.It Va net.inet.tcp.bb.log_auto_all
+Enable logging consideration for all TCP connections.
+.It Va net.inet.tcp.bb.log_auto_ratio
+Select one out of N connections for logging.
+.It Va net.inet.tcp.bb.log_auto_mode
+Default logging mode applied automatically.
+When set to 1 the last net.inet.tcp.bb.log_session_limit entries
+are stored at the TCP endpoint.
+This is a good way to capture information when debugging TCP
+related panics.
+.It Va net.inet.tcp.bb.log_session_limit
+Maximum number of log entries per connection.
+.It Va net.inet.tcp.bb.log_global_limit
+Global limit on allocated log entries.
+.El
+.Sh FILES
+.Bl -tag -width "/var/log/tcplog_dumps" -compact
+.It Pa /dev/tcp_log
+TCP BBLog device interface
+.It Pa /var/log/tcplog_dumps
+Default directory for stored log output
+.El
+.Sh EXAMPLES
+Enable continual logging for all TCP connections:
+.Bd -literal -offset indent
+sysctl net.inet.tcp.bb.log_auto_all=1
+sysctl net.inet.tcp.bb.log_auto_ratio=1
+sysctl net.inet.tcp.bb.log_auto_mode=4
+.Ed
+.Pp
+Enable logging on a specific socket:
+.Bd -literal -offset indent
+int mode = TCP_LOG_STATE_CONTINUAL;
+setsockopt(sd, IPPROTO_TCP, TCP_LOG, &mode, sizeof(mode));
+.Ed
+.Sh SEE ALSO
+.Xr tcpdump 1 ,
+.Xr setsockopt 2 ,
+.Xr tcp 4 ,
+.Xr sysctl 8 ,
+.Xr tcpsso 8
+.Rs
+.%A "Randall Stewart"
+.%A "Michael T\(:uxen"
+.%T "Adventures in TCP/IP: TCP Black Box Logging"
+.%J "FreeBSD Journal"
+.%D "May / June 2024"
+.%U "https://freebsdfoundation.org/adventures-in-tcp-ip-tcp-black-box-logging/"
+.Re
+.Sh HISTORY
+The
+.Nm
+facility first appeared in
+.Fx 13.0
+and replaced earlier TCP debugging mechanisms.
+.Sh AUTHORS
+The
+.Nm
+facility was written by
+.An -nosplit
+.An Randall Stewart Aq Mt [email protected]
+and
+.An Jonathan Looney Aq Mt [email protected]
+and sponsored by Netflix, Inc.
+This manual page was written by
+.An Gordon Bergling Aq Mt [email protected] .
+.Sh CAVEATS
+Log records may be dropped if userland does not drain
+.Pa /dev/tcp_log
+fast enough.
+TCP payload data is not recorded.
+.Sh BUGS
+Logging may introduce measurable overhead under high connection rates.