2 .\" Copyright (c) 2019 Conrad Meyer <cem@FreeBSD.org>
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\" notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\" notice, this list of conditions and the following disclaimer in the
11 .\" documentation and/or other materials provided with the distribution.
13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
16 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
32 .Nd protocol for debugging the kernel with GDB over the network
34 NetGDB support is compiled by default, if DDB, GDB, and INET are enabled.
35 To build a kernel without it, add the following line to your kernel
37 .Bd -ragged -offset indent
38 .Cd "nooptions NETGDB"
42 is a UDP-based protocol for communicating with a remote GDB client via an
47 session is started by using the
48 .Ic netgdb Fl s Ar server Oo Fl g Ar gateway Fl c Ar client Fl i Ar iface Oc
51 to connect to a proxy server.
52 When the connection is made, the proxy server logs a message that a
55 It subsequently establishes a TCP listening socket and logs a message
56 specifying which port it is listening on.
57 Then it waits for a GDB client to connect.
58 The GDB command to connect is:
59 .Bd -ragged -offset indent
60 .Ic target remote Aq Ar proxyip:proxyport
63 At this point, the server proxies traffic back and forth between
65 and the ordinary GDB client, speaking the ordinary GDB remote protocol.
68 session is identical to any other kernel GDB sesssion from the perspective
70 .Sh IMPLEMENTATION NOTES
71 The UDP protocol is based on the same packet structure and a subset of the
72 exact same message types as
76 .Dv DATA ( née VMCORE ) ,
84 message is acknowledged from a random source port, and the client sends
85 subsequent communication to that port.
93 the proxy server sends responses to the source port of the client's initial
95 rather than a separate reserved port.
97 message and acknowledgements are bidirectional.
98 The sequence number and acknowledgement protocol is otherwise identical to
99 the unidirectional version used by netdump; it just runs in both directions.
100 Acknowledgements are sent to and from the same addresses and ports as
103 The first version of the
105 protocol uses the protocol number
109 parameter of the initial
113 The list of supported network drivers and protocol families is identical to
117 The following variable is available via both
122 .Bl -tag -width "indent"
123 .It Va debug.gdb.netgdb.debug
124 Control debug message verbosity.
125 Debug messages are disabled by default.
126 They may be enabled by setting the variable to a non-zero value.
138 may only be used after the kernel has panicked, due to limitations in the
139 treatment of locking primitives under
141 .Sh SECURITY CONSIDERATIONS
144 protocol has no security properties whatsoever.
145 All messages are sent and acknowledged in cleartext, and no message
146 authentication codes are used to prevent attackers from forging messages.
147 It is absolutely inappropriate for use across the public internet.