How to Trace TCP Socket TCP_REPAIR_WINDOW in Linux Using eBPF

Live process migration and container checkpointing engines—such as CRIU (Checkpoint/Restore in Userspace)—rely on Linux TCP repair mode to restore established network connections without dropping active TCP sessions. During restoration, restoring sequence numbers alone is insufficient: the migration controller must also restore the exact sliding window parameters (send window, receive window, window scaling factors, and maximum window clamp). The Linux kernel provides the TCP_REPAIR_WINDOW socket option via setsockopt() to inject raw sliding window state. Tracing window state reconstruction using eBPF provides kernel-level visibility into container network migration health.

Mechanics of Sliding Window Restoration

When a socket is switched to repair mode (TCP_REPAIR enabled), the kernel allows privileged userspace applications to read and write sliding window parameters via struct tcp_repair_window:

struct tcp_repair_window {
    __u32   snd_wl1;
    __u32   snd_wnd;
    __u32   max_window;
    __u32   rcv_wnd;
    __u32   rcv_wup;
};

The kernel parses these values to re-arm tp->snd_wnd, tp->rcv_wnd, and related window update tracking variables. If corrupted window values are injected, the restored connection may immediately stall due to a zero-window deadlock or trigger immediate connection resets (RST) when packets arrive outside the restored sequence window.

Authoring a Custom bpftrace Window Repair Script

To inspect when TCP_REPAIR_WINDOW is invoked and trace the exact window values being injected, create an eBPF script using bpftrace:

#!/usr/bin/env bpftrace

#include <net/sock.h>
#include <linux/tcp.h>

kprobe:tcp_repair_set_window
{
  $sk = (struct sock *)arg0;
  $tp = (struct tcp_sock *)arg0;

  time("%H:%M:%S: TCP_REPAIR_WINDOW invoked on sock %p\n", $sk);
  @window_repair_events = count();
}

kprobe:tcp_select_window
{
  $sk = (struct sock *)arg0;
  $tp = (struct tcp_sock *)arg0;

  if ($tp->repair) {
    @repaired_active_windows[$sk] = $tp->rcv_wnd;
  }
}

interval:s:10
{
  print(@window_repair_events);
  print(@repaired_active_windows);
  clear(@window_repair_events);
  clear(@repaired_active_windows);
}

Save this script as trace_repair_window.bt. It instruments tcp_repair_set_window() to track window restoration calls and monitors active receive window values.

Executing and Evaluating Kernel Telemetry

Run the bpftrace monitoring script with administrative privileges:

sudo bpftrace trace_repair_window.bt

Trigger a live container restoration cycle. Review the output telemetry:

• Window restoration events: Increments in @window_repair_events confirm that CRIU is restoring window state before exiting repair mode.
• Receive window validation: Ensure @repaired_active_windows reflects reasonable non-zero values (e.g. 64KB to 1MB) matching pre-migration socket configurations.
• Zero-window stall detection: If rcv_wnd is restored as 0, senders will enter persistent zero-window probing, stalling data flow.

Operational Safeguards for Window State Restoration

To ensure flawless container migration across production environments:

1. Verify that TCP_REPAIR_WINDOW is executed in tandem with TCP_REPAIR_OPTIONS (to restore window scale factors).
2. Ensure sequence numbers are unfrozen in the correct state order (receive queue before send queue).
3. Monitor conntrack tables using conntrack -L to verify that connection tracking window markers match restored socket states.