How to Inspect and Flush the TCP Metrics Cache in Linux Using ip tcp_metrics

Modern Linux servers and networking appliances process thousands of concurrent Transmission Control Protocol (TCP) streams. To maximise network throughput and eliminate the sluggish startup latency associated with initial window probing, the Linux kernel incorporates an internal performance database known as the TCP Metrics Cache. Whenever a TCP connection terminates cleanly, the kernel stores critical diagnostic parameters—including the measured Round-Trip Time (RTT), RTT variance, slow-start threshold (ssthresh), and congestion window (cwnd)—indexed by the remote destination IP address.

When subsequent connections are initiated to that same IP address, the kernel reuses these cached metrics to jump-start window sizing without undergoing standard TCP slow-start discovery. While advantageous under static network conditions, this caching behaviour can severely undermine throughput during network routing changes, WAN failovers, ISP bandwidth upgrades, or synthetic performance benchmarking. In this technical tutorial, you will learn how to inspect, query, and flush cached TCP metrics in Linux using the native ip tcp_metrics utility.

Understanding How the Linux TCP Metrics Cache Operates

In traditional networking stacks, every new TCP connection begins from scratch: the sender transmits an initial congestion window (typically 10 segments / initcwnd) and cautiously ramps up speed until it encounters packet loss or reaches network capacity. The Linux kernel streamlines this by saving historical connection performance metrics in a kernel hash table:

• rtt and rttvar: The smoothed round-trip time and jitter variance in microseconds.
• ssthresh: The slow start threshold. If a previous connection suffered congestion at a specific bandwidth window, subsequent connections will switch to conservative congestion avoidance before hitting that threshold.
• cwnd: The congestion window size used during the previous session.
• fo_cookie: TCP Fast Open cookies established during initial handshakes.

The operational danger arises when a transient network glitch or routing bottleneck throttles a single connection. The kernel saves an artificially shrunken ssthresh value for that destination IP. Subsequent transfers will immediately throttle themselves, causing persistent slowness even after the underlying network path has completely recovered. Managing this cache with ip tcp_metrics provides instant remediation.

Step 1: Listing All Cached TCP Metrics

To inspect every remote host and subnet currently tracked in your kernel’s TCP metrics database, execute:

ip tcp_metrics show

The output provides a detailed per-destination breakdown:

198.51.100.24 age 45.210sec rtt 18250us rttvar 1250us ssthresh 28 cwnd 10
203.0.113.10 age 120.400sec rtt 45000us rttvar 3200us ssthresh 14 fo_cookie 0123456789abcdef
2001:db8:85a3::8a2e:370:7334 age 12.180sec rtt 8400us rttvar 450us cwnd 20

Notice the diagnostic metrics:

• age: Time elapsed since the metrics were last updated by an active socket.
• rtt: Measured round-trip latency in microseconds (e.g. 18250us represents 18.25 milliseconds).
• ssthresh: The slow-start threshold measured in segments. A low number (e.g. ssthresh 4) indicates that past transfers encountered severe congestion and that subsequent connections will throttle early.

Step 2: Querying Metrics for a Specific Destination IP

In high-traffic production environments, the TCP metrics cache may contain thousands of entries. To narrow your investigation to a single problematic server, client, or storage endpoint, pass the target IP address to the show command:

ip tcp_metrics show 198.51.100.24

If the command returns nothing, no recent TCP sessions to that host have cached performance parameters, meaning new connections will initiate using default system-wide TCP stack parameters.

Step 3: Flushing Cached Metrics for a Specific Host

If you have recently reconfigured a remote server, upgraded an internet link, or noticed that transfers to a specific backup target or database remain inexplicably sluggish, purge that host’s cached parameters using ip tcp_metrics delete:

sudo ip tcp_metrics delete 198.51.100.24

The kernel will immediately evict the stored latency and threshold records for that IP address. The next connection opened to 198.51.100.24 will initiate a clean, unbiased slow-start discovery sequence.

Step 4: Purging the Entire System-Wide TCP Metrics Cache

During network troubleshooting, router failover drills, or before executing synthetic network throughput benchmarks (such as iperf3 or wrk tests), you should purge the entire kernel metrics database to prevent historical connection states from distorting your measurements:

sudo ip tcp_metrics flush

To verify that the database is completely empty, run ip tcp_metrics show. The command will return a clean, blank prompt.

Configuring Kernel Sysctl TCP Metrics Behaviour

If your Linux environment frequently operates across dynamic, fluctuating wireless links or rapidly changing cloud overlay networks, you may prefer to disable TCP metric caching permanently across the entire operating system.

To instruct the Linux kernel to discard connection metrics upon socket closure rather than storing them in memory, adjust the tcp_no_metrics_save sysctl parameter:

# Disable TCP metrics caching at runtime
sudo sysctl -w net.ipv4.tcp_no_metrics_save=1

To make this configuration permanent across system reboots, append the setting to your sysctl configuration file (e.g. /etc/sysctl.d/99-network-performance.conf):

# Do not save TCP metrics across connections
net.ipv4.tcp_no_metrics_save = 1

Apply the changes immediately with:

sudo sysctl --system

Troubleshooting Common TCP Performance Anomalies

• Throughput Stalls Following Temporary Network Packet Loss: If a burst of packet drops occurred during peak business hours, the kernel may have recorded a very low ssthresh. Even hours after congestion clears, large file transfers remain capped at suboptimal transfer speeds. Flushing the cache with ip tcp_metrics delete <IP> immediately restores full throughput.
• Inconsistent Benchmark Results in iperf3: Running successive iperf3 runs often shows faster initial throughput on the second and third runs compared to the first run because the kernel cached the optimal window size. Running sudo ip tcp_metrics flush between test runs ensures uniform, repeatable benchmark metrics.
• Command Not Found Errors: The ip tcp_metrics utility is an integral component of the standard iproute2 package. On minimal containers, install the base package using sudo apt install iproute2 (Debian/Ubuntu) or sudo dnf install iproute (RHEL/CentOS).

Frequently Asked Questions

Does ip tcp_metrics apply to IPv6 traffic?

Yes. The Linux kernel TCP metrics subsystem tracks both IPv4 and IPv6 remote endpoints identically. You can query, delete, or flush IPv6 metrics using the exact same command syntax.

How long do TCP metrics persist in the kernel cache?

By default, cached TCP metrics persist in kernel memory for up to 10 minutes (600 seconds) after the most recent connection to that host terminates. If no further packets are exchanged within that window, the kernel automatically reclaims the memory slot.

Does flushing the TCP metrics cache disconnect active sessions?

No. ip tcp_metrics flush only affects the historical cache used when *opening* new connections. Active, established TCP sockets continue executing their existing congestion control algorithms without interruption.

What is the difference between TCP Fast Open (fo_cookie) and general metrics?

TCP Fast Open allows clients to send data payloads inside the initial SYN handshake packet using an encrypted token (cookie) verified by the server. The ip tcp_metrics table stores these verified cookies alongside RTT and window thresholds.