From nobody Sun Jul 12 10:25:35 2026 X-Original-To: dev-commits-src-all@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 4gyhY11jWxz6lBFH for ; Sun, 12 Jul 2026 10:25:41 +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 4gyhY06jCJz3QfT for ; Sun, 12 Jul 2026 10:25:40 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1783851941; 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=V+XFnpJf0WaXwl9Faf3IDYjycJsWkw+vT8wbGIDMiZ/GTbZpnQAup7DcoHtSO5a2PMZCi6 JBrjCUv1tBEXe4JWeocyBOh6RmaJoCek0rS+91YZTpwYQK7GR/vVjBU5y/gQkvIfx9KPnl 91KJt0CAAJpDPHYqhDCjNF6qyfA+6se6FP6jTTOOwQ3aE7cNUvn98dyAJ7HxK3H3o/YMO2 gx+/RkcSBXv3Tni8jEeG44aqa3zAFIQfQt/tWDgbv8BWJjrlk4KFlIevwltp3rCAhfcjuJ jfWBfnhkLIHSHLoAgw3aCeYi7id7X2k4VLGGZ54gJS5hft+rWiczqHJSuqLfJw== ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1783851941; a=rsa-sha256; cv=none; b=M6iFeYMQGcQGShDSeKNNgNRsql1x1nay4ZAIjZYUumh8hzsyEnuciDxpvr0eMSMdk4lkqJ JS7ij5YMmj3Bd7Ww6tqGpMJI3CeflC8wz3lJ+ehczXfMvf/fPPwyO2GBZ/BH0MhAd0wJBz 9hRqaZFKTi477HJ9BKvQjW2CPjYwiu6EOFzgq+JXIBUNZ6qkjOXZbOzNf6UBatDpy+Bl44 Bwc5IJlvI9whTbgn4PmG//H7bFpAOT8Oce2NskHxMNQfb95hWcIxizMdB5Ck6p4Qm4aKUu OlwSRqOJHf9DOiGqVBWhdVzIh1Ic6WpXHVi0r4YNsKbOlPLWoVj1tbBiP1x9+g== 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=1783851941; 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=mzkdTvBfO3I3zE178Ws+sGaxiPubb2URW3YidHRYsVa2yrpq/5SsSEWYd2/H3WxpSDJkJU 0zMAHA2I/z7pEwsYtON/zPju0CuqgyLHFYAFLNKthD+/KFwfUJqoW9WBQYWRiSHRiA8AYH K5qfG5Rb+avUJ/sRPMBV6mytrAVX/OjN3D3sOme1YLgnvaxMF25gwLBw+ReNxGjLufbXkK q9wPeR01rS9Mcyt8h9FsslYUiF6IWH9ZSie+UDcz9GdNXCEoSOzNhmnYwuX6uiT/a67MRt Yfuo+2+MoVs9a3KWSxAyO2bAW9411Jg3NvIcgFsR9VuB7TneFDkD2UsmMlbzQQ== Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) by mxrelay.nyi.freebsd.org (Postfix) with ESMTP id 4gyhY04xjqz1Mv8 for ; Sun, 12 Jul 2026 10:25:40 +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 all branches of the src repository List-Archive: https://lists.freebsd.org/archives/dev-commits-src-all List-Help: List-Post: List-Subscribe: List-Unsubscribe: X-BeenThere: dev-commits-src-all@freebsd.org Sender: owner-dev-commits-src-all@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.