share/man/man4/netgdb.4

   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
  34 To compile NetGDB support into the kernel, place the following lines in your
  35 kernel 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
  45 is a UDP-based protocol for communicating with a remote GDB client via an
  46 intermediary proxy.
  47 .Pp
  48 A
  49 .Nm
  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
  52 command in
  53 .Xr ddb 4
  54 to connect to a proxy server.
  55 When the connection is made, the proxy server logs a message that a
  56 .Nm
  57 client has connected.
  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
  64 .Ed
  65 .Pp
  66 At this point, the server proxies traffic back and forth between
  67 .Nm
  68 and the ordinary GDB client, speaking the ordinary GDB remote protocol.
  69 The
  70 .Nm
  71 session is identical to any other kernel GDB sesssion from the perspective
  72 of the GDB debugger.
  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
  76 .Xr netdump 4 .
  77 It uses the
  78 .Dv HERALD ,
  79 .Dv DATA ( née VMCORE ) ,
  80 and
  81 .Dv FINISHED
  82 message types.
  83 Like
  84 .Xr netdump 4 ,
  85 the client's initial
  86 .Dv HERALD
  87 message is acknowledged from a random source port, and the client sends
  88 subsequent communication to that port.
  89 .Pp
  90 Unlike
  91 .Xr netdump 4 ,
  92 the initial
  93 .Dv HERALD
  94 port is 20025.
  95 Additionally,
  96 the proxy server sends responses to the source port of the client's initial
  97 .Dv HERALD ,
  98 rather than a separate reserved port.
  99 .Nm
 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
 104 regular messages.
 105 .Pp
 106 The first version of the
 107 .Nm
 108 protocol uses the protocol number
 109 .Dv Sq 0x2515f095
 110 in the 32-bit
 111 .Va aux2
 112 parameter of the initial
 113 .Dv HERALD
 114 message.
 115 .Pp
 116 The list of supported network drivers and protocol families is identical to
 117 that of
 118 .Xr netdump 4 .
 119 .Sh DIAGNOSTICS
 120 The following variable is available via both
 121 .Xr sysctl 8
 122 and
 123 .Xr loader 8
 124 (as a tunable):
 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.
 130 .El
 131 .Sh SEE ALSO
 132 .Xr ddb 4 ,
 133 .Xr gdb 4 ,
 134 .Xr netdump 4
 135 .Sh HISTORY
 136 .Nm
 137 first appeared in
 138 .Fx 13.0 .
 139 .Sh BUGS
 140 .Nm
 141 may only be used after the kernel has panicked, due to limitations in the
 142 treatment of locking primitives under
 143 .Xr ddb 4 .
 144 .Sh SECURITY CONSIDERATIONS
 145 Version 1 of the
 146 .Nm
 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.