1.\"- 2.\" Copyright (c) 2019 Conrad Meyer <cem@FreeBSD.org> 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 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. 12.\" 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 23.\" SUCH DAMAGE. 24.\" 25.Dd November 10, 2022 26.Dt NETGDB 4 27.Os 28.Sh NAME 29.Nm netgdb 30.Nd protocol for debugging the kernel with GDB over the network 31.Sh SYNOPSIS 32To compile NetGDB support into the kernel, place the following lines in your 33kernel configuration file: 34.Bd -ragged -offset indent 35.Cd "options DDB" 36.Cd "options GDB" 37.Cd "options INET" 38.Cd "options DEBUGNET" 39.Cd "options NETGDB" 40.Ed 41.Sh DESCRIPTION 42.Nm 43is a UDP-based protocol for communicating with a remote GDB client via an 44intermediary proxy. 45.Pp 46A 47.Nm 48session is started by using the 49.Ic netgdb Fl s Ar server Oo Fl g Ar gateway Fl c Ar client Fl i Ar iface Oc 50command in 51.Xr ddb 4 52to connect to a proxy server. 53When the connection is made, the proxy server logs a message that a 54.Nm 55client has connected. 56It subsequently establishes a TCP listening socket and logs a message 57specifying which port it is listening on. 58Then it waits for a GDB client to connect. 59The GDB command to connect is: 60.Bd -ragged -offset indent 61.Ic target remote Aq Ar proxyip:proxyport 62.Ed 63.Pp 64At this point, the server proxies traffic back and forth between 65.Nm 66and the ordinary GDB client, speaking the ordinary GDB remote protocol. 67The 68.Nm 69session is identical to any other kernel GDB session from the perspective 70of the GDB debugger. 71.Sh IMPLEMENTATION NOTES 72The UDP protocol is based on the same packet structure and a subset of the 73exact same message types as 74.Xr netdump 4 . 75It uses the 76.Dv HERALD , 77.Dv DATA ( née VMCORE ) , 78and 79.Dv FINISHED 80message types. 81Like 82.Xr netdump 4 , 83the client's initial 84.Dv HERALD 85message is acknowledged from a random source port, and the client sends 86subsequent communication to that port. 87.Pp 88Unlike 89.Xr netdump 4 , 90the initial 91.Dv HERALD 92port is 20025. 93Additionally, 94the proxy server sends responses to the source port of the client's initial 95.Dv HERALD , 96rather than a separate reserved port. 97.Nm 98message and acknowledgements are bidirectional. 99The sequence number and acknowledgement protocol is otherwise identical to 100the unidirectional version used by netdump; it just runs in both directions. 101Acknowledgements are sent to and from the same addresses and ports as 102regular messages. 103.Pp 104The first version of the 105.Nm 106protocol uses the protocol number 107.Dv Sq 0x2515f095 108in the 32-bit 109.Va aux2 110parameter of the initial 111.Dv HERALD 112message. 113.Pp 114The list of supported network drivers and protocol families is identical to 115that of 116.Xr netdump 4 . 117.Sh DIAGNOSTICS 118The following variable is available via both 119.Xr sysctl 8 120and 121.Xr loader 8 122(as a tunable): 123.Bl -tag -width "indent" 124.It Va debug.gdb.netgdb.debug 125Control debug message verbosity. 126Debug messages are disabled by default. 127They may be enabled by setting the variable to a non-zero value. 128.El 129.Sh SEE ALSO 130.Xr ddb 4 , 131.Xr gdb 4 , 132.Xr netdump 4 133.Sh HISTORY 134.Nm 135first appeared in 136.Fx 13.0 . 137.Sh BUGS 138.Nm 139may only be used after the kernel has panicked, due to limitations in the 140treatment of locking primitives under 141.Xr ddb 4 . 142.Sh SECURITY CONSIDERATIONS 143Version 1 of the 144.Nm 145protocol has no security properties whatsoever. 146All messages are sent and acknowledged in cleartext, and no message 147authentication codes are used to prevent attackers from forging messages. 148It is absolutely inappropriate for use across the public internet. 149