From nobody Sun Jul 12 10:25:35 2026 X-Original-To: dev-commits-src-main@mlmmj.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mlmmj.nyi.freebsd.org (Postfix) with ESMTP id 4gyhXv6pHbz6l9mb for ; Sun, 12 Jul 2026 10:25:35 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "YR1" (not verified)) by mx1.freebsd.org (Postfix) with ESMTPS id 4gyhXv6FJYz3Qdt for ; Sun, 12 Jul 2026 10:25:35 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1783851935; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=RRlSc7QrAznodRvXqMAVbLc6DSm4zHaVKhYG5zRlJ8s=; b=oXHk9nDtW41rvvKtF+GZYo0rYmJ4HCjlooW+n+BVChKsKy8cARE/wG3cA5+DpC1FR+uZuX 95FXIeBqgmoPP1Q4p4/kgbgIuXqLRcgCyfxeBoNegSPy6VtyeE5/xtwGNZ8Wtvzks7gXF1 LmKwKjawIA4GGwZDU17Q0vP7lSimQD3LYpxkYzJecicAqPtaYM38ImWDHxqhjA7dJdhQNt hr8lM36RuZ49qNGneLqyCqj2Q1j8oau6bcsyAPVnm8EO9N2f9ZfwhLgjm7BJECgnGyNAmA IlSCeuKCVBHirCNTmAvCvWK+S0iL7HbVKyIEn6jkt2RoCOppf+d8Cu/gyy0XHQ== ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1783851935; a=rsa-sha256; cv=none; b=Lhpoz7S7XQFNjwEJCad95n8EG4fP3bQabDzCnZtatn5ZO2JJjRCA3UYHX9uQcihg+LdoIF 7k9/o+7VFP8MxK+nju47/6cVNH5j3Fnb3+fhaIg+wryQ1/kCkCb8kg139DzYw28lAPZ1Dx mzI3M2yzM6ulsxrvTg/BCYECRUrF9WmgsDLh+urtVR2/S1anjbQpzxvYhW6Har2/mOhahq IFKwzjIAHg3xaNtvBUucu6RcjQJliOH0UOBQL2kMAJfRvAvqnvMU67wDtuz15MnwIgAL+V vjHeWPw2p9hdaJwBBpLkPH6GInRcpHjpCqdh6YgpDB/KKinwhtBrn/A6hc4aEA== ARC-Authentication-Results: i=1; mx1.freebsd.org; none ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1783851935; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=RRlSc7QrAznodRvXqMAVbLc6DSm4zHaVKhYG5zRlJ8s=; b=HwybETN7+PELJ5+sTjwwjY0zwc/JqFjEjAevgXh9WkywK1iKFhcgEpN1Xw3/4aK+mmNCEO Or+PsetUfu21+ClJO6F5SSi0q1WxIMbH05+8sN8o5T03Vx6O6R+TMyqo69eKKCOUMq4xsd y4o6ih7/aGCaMUWBtlIw+x+mucZz9d4iAGoongkCwmUVl1Zdt8zp616773+9O9o+sItsZ4 7YenoJ7kJ6HVeiCNhfNmqBDl1FSfT4VTxTLZ7UgIaRJNXfCBAnEMyE1g6fzAg4fK+jbm06 0b1GQPMEfAzS6VmRLcvzHCKHWBvC6PzHmkxCnxVEeG83usCaG4oGE90kkyxgsg== Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) by mxrelay.nyi.freebsd.org (Postfix) with ESMTP id 4gyhXv4STsz1Mh6 for ; Sun, 12 Jul 2026 10:25:35 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from git (uid 1279) (envelope-from git@FreeBSD.org) id 3ef4b by gitrepo.freebsd.org (DragonFly Mail Agent v0.13+ on gitrepo.freebsd.org); Sun, 12 Jul 2026 10:25:35 +0000 To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-main@FreeBSD.org From: Gordon Bergling Subject: git: 62e22d7cfc1c - main - tcp_bblog.4: Add a manual page for TCP Blackbox Logging List-Id: Commit messages for the main branch of the src repository List-Archive: https://lists.freebsd.org/archives/dev-commits-src-main List-Help: List-Post: List-Subscribe: List-Unsubscribe: X-BeenThere: dev-commits-src-main@freebsd.org Sender: owner-dev-commits-src-main@FreeBSD.org List-Id: List-Post: List-Help: List-Subscribe: List-Unsubscribe: List-Owner: Precedence: list MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: gbe X-Git-Repository: src X-Git-Refname: refs/heads/main X-Git-Reftype: branch X-Git-Commit: 62e22d7cfc1ca1c25bede6aaeca370c163a9a1ef Auto-Submitted: auto-generated Date: Sun, 12 Jul 2026 10:25:35 +0000 Message-Id: <6a536b9f.3ef4b.69164639@gitrepo.freebsd.org> The branch main has been updated by gbe: URL: https://cgit.FreeBSD.org/src/commit/?id=62e22d7cfc1ca1c25bede6aaeca370c163a9a1ef commit 62e22d7cfc1ca1c25bede6aaeca370c163a9a1ef Author: Gordon Bergling AuthorDate: 2026-07-12 10:25:01 +0000 Commit: Gordon Bergling CommitDate: 2026-07-12 10:25:01 +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 MFC after: 1 week Relnotes: yes Differential Revision: https://reviews.freebsd.org/D56252 --- 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 9bee23f1df8f..ab937d5cacee 100644 --- a/share/man/man4/Makefile +++ b/share/man/man4/Makefile @@ -600,6 +600,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 +.\" +.\" 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 rrs@freebsd.org +and +.An Jonathan Looney Aq Mt jtl@freebsd.org +and sponsored by Netflix, Inc. +This manual page was written by +.An Gordon Bergling Aq Mt gbe@FreeBSD.org . +.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.