Page MenuHomeFreeBSD

Implement NetGDB(4)
Needs ReviewPublic

Authored by cem on Mon, Sep 9, 5:55 AM.



NetGDB(4) is a component of a system using a panic-time network stack to
remotely debug crashed FreeBSD kernels over the network, instead of traditional
serial interfaces.

There are three pieces in the complete NetGDB system.

First, a dedicated proxy server must be running to accept connections from
both NetGDB and gdb(1), and pass bidirectional traffic between the two

Second, the NetGDB client is activated much like ordinary 'gdb' and
similarly to 'netdump' in ddb(4) after a panic. Like other debugnet(4)
clients (netdump(4)), the network interface on the route to the proxy server
must be online and support debugnet(4).

Finally, the remote (k)gdb(1) uses 'target remote <proxy>:<port>' (like any
other TCP remote) to connect to the proxy server.

The NetGDB v1 protocol speaks the literal GDB remote serial protocol, and
uses a 1:1 relationship between GDB packets and plain debugnet packets.
There is no encryption utilized to keep debugging sessions private, so this
is only appropriate for local segments or trusted networks.

The panic-time network stack is mostly appropriated from netdump(4).

Submitted by: John Reimer <john.reimer AT> (earlier version)

Test Plan

Working proxy draft version here: P314


  • Clean up proxy
  • Implement and hook GDB no-Ack mode to reduce RTTs-per-packet by 2x
  • Ideally, rewrite proxy in C or something

Diff Detail

Lint OK
No Unit Test Coverage
Build Status
Buildable 26611
Build 24990: arc lint + arc unit

Event Timeline

cem created this revision.Mon, Sep 9, 5:55 AM
cem added a reviewer: emaste.Mon, Sep 9, 10:55 PM
emaste added inline comments.Mon, Sep 9, 11:07 PM



if you're so inclined feel free to commit with my reviewed-by these bits, static keyword changes etc. independently now while waiting on review of the rest. I've looked over all but the main part of the change, the addition of netgdb.c

cem added inline comments.Mon, Sep 9, 11:49 PM

The debugnet changes aren't in tree yet, so there's no urgency on most of those changes.

Really the only similar thing that could go in by itself is the sys/kdb.h change in this revision.

cem updated this revision to Diff 62409.Sun, Sep 22, 2:47 AM
  • Do GDB TX framing on the NetGDB side. This matches RX and is just more straightforward than trying to infer what is what on the proxy.
  • Use aux1 (aka netdump's offset) as a intra-packet offset for each fragment. There is no actual need anymore, but it seems vaguely useful for debugging and might provide flexibility in the future.
  • Probably other things I am forgetting. But I have an adapted version of John's Python proxy adapted to debugnet working as a PoC, which I'll share shortly.
cem edited the test plan for this revision. (Show Details)Sun, Sep 22, 2:55 AM