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 To compile NetGDB support into the kernel, place the following lines in your
35 kernel configuration file:
36 .Bd -ragged -offset indent
40 .Cd "options DEBUGNET"
45 is a UDP-based protocol for communicating with a remote GDB client via an
50 session is started by using the
51 .Ic netgdb Fl s Ar server Oo Fl g Ar gateway Fl c Ar client Fl i Ar iface Oc
54 to connect to a proxy server.
55 When the connection is made, the proxy server logs a message that a
58 It subsequently establishes a TCP listening socket and logs a message
59 specifying which port it is listening on.
60 Then it waits for a GDB client to connect.
61 The GDB command to connect is:
62 .Bd -ragged -offset indent
63 .Ic target remote Aq Ar proxyip:proxyport
66 At this point, the server proxies traffic back and forth between
68 and the ordinary GDB client, speaking the ordinary GDB remote protocol.
71 session is identical to any other kernel GDB sesssion from the perspective
73 .Sh IMPLEMENTATION NOTES
74 The UDP protocol is based on the same packet structure and a subset of the
75 exact same message types as
79 .Dv DATA ( née VMCORE ) ,
87 message is acknowledged from a random source port, and the client sends
88 subsequent communication to that port.
96 the proxy server sends responses to the source port of the client's initial
98 rather than a separate reserved port.
100 message and acknowledgements are bidirectional.
101 The sequence number and acknowledgement protocol is otherwise identical to
102 the unidirectional version used by netdump; it just runs in both directions.
103 Acknowledgements are sent to and from the same addresses and ports as
106 The first version of the
108 protocol uses the protocol number
112 parameter of the initial
116 The list of supported network drivers and protocol families is identical to
120 The following variable is available via both
125 .Bl -tag -width "indent"
126 .It Va debug.gdb.netgdb.debug
127 Control debug message verbosity.
128 Debug messages are disabled by default.
129 They may be enabled by setting the variable to a non-zero value.
141 may only be used after the kernel has panicked, due to limitations in the
142 treatment of locking primitives under
144 .Sh SECURITY CONSIDERATIONS
147 protocol has no security properties whatsoever.
148 All messages are sent and acknowledged in cleartext, and no message
149 authentication codes are used to prevent attackers from forging messages.
150 It is absolutely inappropriate for use across the public internet.