---
name: "tcp_bblog"
section: "4"
platform: "freebsd"
package: "base"
version: "16.0-CURRENT-20261027-61c70dc16a79"
release: "FreeBSD 16.0-CURRENT (2026-10-27)"
platforms: ["freebsd"]
url: "https://new.carta.tech/tcp_bblog"
---

# tcp\_bblog(4)

TCP Black Box Logging facility

## NAME

**tcp\_bblog** – TCP Black Box Logging facility

## SYNOPSIS

**options** **TCP\_BLACKBOX**

## DESCRIPTION

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. Each TCP endpoint may maintain an internal log buffer recording events such as packet transmission, reception, retransmissions, and state transitions. Unlike earlier debugging mechanisms, **tcp\_bblog** records structured metadata without capturing TCP payload data. Logs are exported to userland via the device */dev/tcp\_log*. If no process is actively reading from this device, log records may be discarded. Each log entry includes:

- Connection identifiers, including local and remote addresses and ports

- Timestamp information

- TCP state and sequence variables

- Event-specific metadata

Logging may be enabled globally using [sysctl(8)](/sysctl/8.md) or on a per-connection basis using [setsockopt(2)](/setsockopt/2.md) or [tcpsso(8)](/tcpsso/8.md).

## MODES

The following logging modes are supported:

- TCP\_LOG\_STATE\_OFF

  Disable logging.

- TCP\_LOG\_STATE\_TAIL

  Maintain a ring buffer of recent events.

- TCP\_LOG\_STATE\_HEAD

  Log only the initial events of a connection.

- TCP\_LOG\_STATE\_HEAD\_AUTO

  Log initial events and automatically export them.

- TCP\_LOG\_STATE\_CONTINUAL

  Continuously log and export events as buffers fill.

- TCP\_LOG\_STATE\_TAIL\_AUTO

  Maintain a tail buffer and export on overflow.

## CONFIGURATION

Global configuration is available via [sysctl(8)](/sysctl/8.md) under the *net.inet.tcp.bb* namespace. Notable variables include:

- *net.inet.tcp.bb.log\_auto\_all*

  Enable logging consideration for all TCP connections.

- *net.inet.tcp.bb.log\_auto\_ratio*

  Select one out of N connections for logging.

- *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.

- *net.inet.tcp.bb.log\_session\_limit*

  Maximum number of log entries per connection.

- *net.inet.tcp.bb.log\_global\_limit*

  Global limit on allocated log entries.

## FILES

- */dev/tcp\_log*

  TCP BBLog device interface

- */var/log/tcplog\_dumps*

  Default directory for stored log output

## EXAMPLES

Enable continual logging for all TCP connections:

```
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
```

Enable logging on a specific socket:

```
int mode = TCP_LOG_STATE_CONTINUAL;
setsockopt(sd, IPPROTO_TCP, TCP_LOG, &mode, sizeof(mode));
```

## SEE ALSO

[tcpdump(1)](/tcpdump/1.md), [setsockopt(2)](/setsockopt/2.md), [tcp(4)](/tcp/4.md), [sysctl(8)](/sysctl/8.md), [tcpsso(8)](/tcpsso/8.md) Randall Stewart and Michael Tüxen, “Adventures in TCP/IP: TCP Black Box Logging”, *FreeBSD Journal*, May / June 2024, https://freebsdfoundation.org/adventures-in-tcp-ip-tcp-black-box-logging/.

## HISTORY

The **tcp\_bblog** facility first appeared in FreeBSD 13.0 and replaced earlier TCP debugging mechanisms.

## AUTHORS

The **tcp\_bblog** facility was written by Randall Stewart ⟨*rrs@FreeBSD.org*⟩ and Jonathan Looney ⟨*jtl@FreeBSD.org*⟩ and sponsored by Netflix, Inc. This manual page was written by Gordon Bergling ⟨*gbe@FreeBSD.org*⟩.

## CAVEATS

Log records may be dropped if userland does not drain */dev/tcp\_log* fast enough. TCP payload data is not recorded.

## BUGS

Logging may introduce measurable overhead under high connection rates.