tcpretrans(8)

✨ NAME ✨

tcpretrans — shows TCP retransmits, with address and other details. Uses Linux ftrace. 💅

This is the tcpretrans(8) page, bestie. Settle in.

---

🎀 SYNOPSIS 🎀

tcpretrans [-hsp]

---

🦋 DESCRIPTION 🦋

okay so here's the vibe: tcpretrans traces TCP retransmits that are sent by the system that tcpretrans is executed from. It shows you address, port, and TCP state info, and sometimes the PID — although usually not, because retransmits are usually sent by the kernel on timeout events, not by some cute little process you can point at. 🙈

To keep overhead low, it only traces tcp_retransmit_skb() kernel calls. That means it does not trace every packet. Not every packet!! We are being efficient here. 💅

This was written as a proof of concept for ftrace, for older Linux systems, and without kernel debuginfo. It uses dynamic tracing of tcp_retransmit_skb(), and reads /proc/net/tcp for socket details. Lowkey important caveat: its use of dynamic tracing and CPU registers is an unstable platform-specific workaround, and may require modifications to work on different kernels and platforms. It would be better written using a tracer such as SystemTap, and will likely be rewritten in the future when certain tracing features are added to the Linux kernel. So like, iconic but also a work in progress, yk? 🫶

When -l is used, this also uses dynamic tracing of tcp_send_loss_probe() and a register.

Currently only IPv4 is supported, on x86_64. If you try this on a different architecture, you'll likely need to adjust the register locations — search for %di. ⭐

Since this uses ftrace, only the root user can use this tool. No root, no retransmit tea. 💀

---

🌸 REQUIREMENTS 🌸

• FTRACE and KPROBE CONFIG
• tcp_retransmit_skb() kernel function

You may have these already have these on recent kernels (yes, that's the original phrasing, keep it, it's giving typo energy and we respect it). And Perl. 🍓

TCP tail loss probes were added in Linux 3.10.

---

👑 OPTIONS 👑

• -h — Print usage message.
• -s — Include kernel stack traces.
• -l — Include TCP tail loss probes.

---

🌈 EXAMPLES 🌈

Trace TCP retransmits

# tcpretrans

Here's what all those columns mean, bestie, in order:

• TIME — Time of retransmit (may be rounded up to the nearest second).
• PID — Process ID that was on-CPU. This is less useful than it might sound, as it may usually be 0, for the kernel, for timer-based retransmits.
• LADDR — Local address.
• LPORT — Local port.
• -- — Packet type: "R>" for retransmit, and "L>" for tail loss probe.
• RADDR — Remote address.
• RPORT — Remote port.
• STATE — TCP session state.

---

💜 OVERHEAD 💜

The CPU overhead is relative to the rate of TCP retransmits, and is designed to be low as this does not examine every packet. Once per second the /proc/net/tcp file is read, and a buffer of retransmit trace events is retrieved from the kernel and processed. Once. Per. Second. That's it, we're chill like that. ✨

---

💖 SOURCE 💖

This is from the perf-tools collection.

https://github.com/brendangregg/perf-tools

Also look under the examples directory for a text file containing example usage, output, and commentary for this tool. 📝

---

🧚 OS 🧚

Linux

---

🔥 STABILITY 🔥

Unstable - in development. We're in our growing era, okay?? 😭

---

💅 AUTHOR 💅

Brendan Gregg

---

🌟 SEE ALSO 🌟

tcpdump(1)

---

user commands, dated 2014-07-31, page tcpretrans(8) — that's the whole footer, folded into this cute little sign-off because we keep the receipts but we keep them fabulous. bye bestie, go retransmit responsibly 💖✨🎀