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