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