Page MenuHomeFreeBSD

Implement NetGDB(4)

Authored by cem on Sep 9 2019, 5:55 AM.
Referenced Files
Fri, May 24, 2:37 AM
F84454898: D21568.id62445.diff
Fri, May 24, 2:37 AM
F84454896: D21568.id62911.diff
Fri, May 24, 2:37 AM
F84454891: D21568.id62449.diff
Fri, May 24, 2:37 AM
F84454886: D21568.id61817.diff
Fri, May 24, 2:37 AM
F84454884: D21568.id63418.diff
Fri, May 24, 2:36 AM
F84454882: D21568.id62409.diff
Fri, May 24, 2:36 AM
F84454880: D21568.id62441.diff
Fri, May 24, 2:36 AM


Group Reviewers
rS353700: Implement NetGDB(4)

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
  • Ideally, rewrite proxy in C or something

Diff Detail

rS FreeBSD src repository - subversion
Lint Not Applicable
Tests Not Applicable

Event Timeline

44 ↗(On Diff #61817)


582–586 ↗(On Diff #61817)

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

582–586 ↗(On Diff #61817)

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.

  • 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.
  • Return to DDB when GDB detaches after a session started with 'netgdb ...' instead of continuing. IMO, this should probably also be done when the DDB command 'gdb' is used to enter GDB, but that change felt orthogonal.
  • For consistency with debugnet and netdump, add a NETGDB option.
  • Add DEBUGNET and NETGDB to default yes options.
  • Document 'netgdb' command in ddb.4 and create a netgdb.4 heavily inspired by netdump.4.
  • Actually enable the config(8) option NETGDB in amd64 and i386 GENERIC; remove from DEFAULT_YES_OPTIONS, which is just for MK_ variables. I don't think this is the first time I've confused the two.

Clean up the netgdb state when gdb exits, so that ddb(4) 'netgdb' can be reused
more than once.

Rebase on mh_aux1 -> mh_offset, etc, restoration in parent debugnet revision.

This revision was not accepted when it landed; it landed in state Needs Review.Oct 17 2019, 9:33 PM
Closed by commit rS353700: Implement NetGDB(4) (authored by cem). · Explain Why
This revision was automatically updated to reflect the committed changes.