1.\" 2.\" Copyright (c) 2026, Gordon Bergling <gbe@FreeBSD.org> 3.\" 4.\" SPDX-License-Identifier: BSD-2-Clause 5.\" 6.Dd July 10, 2026 7.Dt TCP_BBLOG 4 8.Os 9.Sh NAME 10.Nm tcp_bblog 11.Nd TCP Black Box Logging facility 12.Sh SYNOPSIS 13.Cd options TCP_BLACKBOX 14.Sh DESCRIPTION 15The 16.Nm 17facility provides structured logging of TCP stack activity for 18debugging and performance analysis. 19It is implemented in the kernel and allows per-connection tracing 20of TCP events with low overhead. 21Each TCP endpoint may maintain an internal log buffer recording 22events such as packet transmission, reception, retransmissions, 23and state transitions. 24Unlike earlier debugging mechanisms, 25.Nm 26records structured metadata without capturing TCP payload data. 27Logs are exported to userland via the device 28.Pa /dev/tcp_log . 29If no process is actively reading from this device, log records 30may be discarded. 31Each log entry includes: 32.Pp 33.Bl -bullet -compact 34.It 35Connection identifiers, including local and remote addresses and ports 36.It 37Timestamp information 38.It 39TCP state and sequence variables 40.It 41Event-specific metadata 42.El 43.Pp 44Logging may be enabled globally using 45.Xr sysctl 8 46or on a per-connection basis using 47.Xr setsockopt 2 48or 49.Xr tcpsso 8 . 50.Sh MODES 51The following logging modes are supported: 52.Pp 53.Bl -tag -width "TCP_LOG_STATE_CONTINUAL" -compact 54.It Dv TCP_LOG_STATE_OFF 55Disable logging. 56.It Dv TCP_LOG_STATE_TAIL 57Maintain a ring buffer of recent events. 58.It Dv TCP_LOG_STATE_HEAD 59Log only the initial events of a connection. 60.It Dv TCP_LOG_STATE_HEAD_AUTO 61Log initial events and automatically export them. 62.It Dv TCP_LOG_STATE_CONTINUAL 63Continuously log and export events as buffers fill. 64.It Dv TCP_LOG_STATE_TAIL_AUTO 65Maintain a tail buffer and export on overflow. 66.El 67.Sh CONFIGURATION 68Global configuration is available via 69.Xr sysctl 8 70under the 71.Va net.inet.tcp.bb 72namespace. 73Notable variables include: 74.Bl -tag -width "net.inet.tcp.bb.log_session_limit" -compact 75.It Va net.inet.tcp.bb.log_auto_all 76Enable logging consideration for all TCP connections. 77.It Va net.inet.tcp.bb.log_auto_ratio 78Select one out of N connections for logging. 79.It Va net.inet.tcp.bb.log_auto_mode 80Default logging mode applied automatically. 81When set to 1 the last net.inet.tcp.bb.log_session_limit entries 82are stored at the TCP endpoint. 83This is a good way to capture information when debugging TCP 84related panics. 85.It Va net.inet.tcp.bb.log_session_limit 86Maximum number of log entries per connection. 87.It Va net.inet.tcp.bb.log_global_limit 88Global limit on allocated log entries. 89.El 90.Sh FILES 91.Bl -tag -width "/var/log/tcplog_dumps" -compact 92.It Pa /dev/tcp_log 93TCP BBLog device interface 94.It Pa /var/log/tcplog_dumps 95Default directory for stored log output 96.El 97.Sh EXAMPLES 98Enable continual logging for all TCP connections: 99.Bd -literal -offset indent 100sysctl net.inet.tcp.bb.log_auto_all=1 101sysctl net.inet.tcp.bb.log_auto_ratio=1 102sysctl net.inet.tcp.bb.log_auto_mode=4 103.Ed 104.Pp 105Enable logging on a specific socket: 106.Bd -literal -offset indent 107int mode = TCP_LOG_STATE_CONTINUAL; 108setsockopt(sd, IPPROTO_TCP, TCP_LOG, &mode, sizeof(mode)); 109.Ed 110.Sh SEE ALSO 111.Xr tcpdump 1 , 112.Xr setsockopt 2 , 113.Xr tcp 4 , 114.Xr sysctl 8 , 115.Xr tcpsso 8 116.Rs 117.%A "Randall Stewart" 118.%A "Michael T\(:uxen" 119.%T "Adventures in TCP/IP: TCP Black Box Logging" 120.%J "FreeBSD Journal" 121.%D "May / June 2024" 122.%U "https://freebsdfoundation.org/adventures-in-tcp-ip-tcp-black-box-logging/" 123.Re 124.Sh HISTORY 125The 126.Nm 127facility first appeared in 128.Fx 13.0 129and replaced earlier TCP debugging mechanisms. 130.Sh AUTHORS 131The 132.Nm 133facility was written by 134.An -nosplit 135.An Randall Stewart Aq Mt rrs@freebsd.org 136and 137.An Jonathan Looney Aq Mt jtl@freebsd.org 138and sponsored by Netflix, Inc. 139This manual page was written by 140.An Gordon Bergling Aq Mt gbe@FreeBSD.org . 141.Sh CAVEATS 142Log records may be dropped if userland does not drain 143.Pa /dev/tcp_log 144fast enough. 145TCP payload data is not recorded. 146.Sh BUGS 147Logging may introduce measurable overhead under high connection rates. 148