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