d5f3e80f5a
The man page claims that netgdb will be enabled automatically with the presence of the DDB, GDB, and INET options. Based on the logic in conf/files, this is not the case. Update the manpage to list all of the options required to include netgdb. Reviewed by: pauamma, markj MFC after: 3 days Differential Revision: https://reviews.freebsd.org/D37330
151 lines
4.5 KiB
Groff
151 lines
4.5 KiB
Groff
.\"-
|
|
.\" Copyright (c) 2019 Conrad Meyer <cem@FreeBSD.org>
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd November 10, 2022
|
|
.Dt NETGDB 4
|
|
.Os
|
|
.Sh NAME
|
|
.Nm netgdb
|
|
.Nd protocol for debugging the kernel with GDB over the network
|
|
.Sh SYNOPSIS
|
|
To compile NetGDB support into the kernel, place the following lines in your
|
|
kernel configuration file:
|
|
.Bd -ragged -offset indent
|
|
.Cd "options DDB"
|
|
.Cd "options GDB"
|
|
.Cd "options INET"
|
|
.Cd "options DEBUGNET"
|
|
.Cd "options NETGDB"
|
|
.Ed
|
|
.Sh DESCRIPTION
|
|
.Nm
|
|
is a UDP-based protocol for communicating with a remote GDB client via an
|
|
intermediary proxy.
|
|
.Pp
|
|
A
|
|
.Nm
|
|
session is started by using the
|
|
.Ic netgdb Fl s Ar server Oo Fl g Ar gateway Fl c Ar client Fl i Ar iface Oc
|
|
command in
|
|
.Xr ddb 4
|
|
to connect to a proxy server.
|
|
When the connection is made, the proxy server logs a message that a
|
|
.Nm
|
|
client has connected.
|
|
It subsequently establishes a TCP listening socket and logs a message
|
|
specifying which port it is listening on.
|
|
Then it waits for a GDB client to connect.
|
|
The GDB command to connect is:
|
|
.Bd -ragged -offset indent
|
|
.Ic target remote Aq Ar proxyip:proxyport
|
|
.Ed
|
|
.Pp
|
|
At this point, the server proxies traffic back and forth between
|
|
.Nm
|
|
and the ordinary GDB client, speaking the ordinary GDB remote protocol.
|
|
The
|
|
.Nm
|
|
session is identical to any other kernel GDB sesssion from the perspective
|
|
of the GDB debugger.
|
|
.Sh IMPLEMENTATION NOTES
|
|
The UDP protocol is based on the same packet structure and a subset of the
|
|
exact same message types as
|
|
.Xr netdump 4 .
|
|
It uses the
|
|
.Dv HERALD ,
|
|
.Dv DATA ( née VMCORE ) ,
|
|
and
|
|
.Dv FINISHED
|
|
message types.
|
|
Like
|
|
.Xr netdump 4 ,
|
|
the client's initial
|
|
.Dv HERALD
|
|
message is acknowledged from a random source port, and the client sends
|
|
subsequent communication to that port.
|
|
.Pp
|
|
Unlike
|
|
.Xr netdump 4 ,
|
|
the initial
|
|
.Dv HERALD
|
|
port is 20025.
|
|
Additionally,
|
|
the proxy server sends responses to the source port of the client's initial
|
|
.Dv HERALD ,
|
|
rather than a separate reserved port.
|
|
.Nm
|
|
message and acknowledgements are bidirectional.
|
|
The sequence number and acknowledgement protocol is otherwise identical to
|
|
the unidirectional version used by netdump; it just runs in both directions.
|
|
Acknowledgements are sent to and from the same addresses and ports as
|
|
regular messages.
|
|
.Pp
|
|
The first version of the
|
|
.Nm
|
|
protocol uses the protocol number
|
|
.Dv Sq 0x2515f095
|
|
in the 32-bit
|
|
.Va aux2
|
|
parameter of the initial
|
|
.Dv HERALD
|
|
message.
|
|
.Pp
|
|
The list of supported network drivers and protocol families is identical to
|
|
that of
|
|
.Xr netdump 4 .
|
|
.Sh DIAGNOSTICS
|
|
The following variable is available via both
|
|
.Xr sysctl 8
|
|
and
|
|
.Xr loader 8
|
|
(as a tunable):
|
|
.Bl -tag -width "indent"
|
|
.It Va debug.gdb.netgdb.debug
|
|
Control debug message verbosity.
|
|
Debug messages are disabled by default.
|
|
They may be enabled by setting the variable to a non-zero value.
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr ddb 4 ,
|
|
.Xr gdb 4 ,
|
|
.Xr netdump 4
|
|
.Sh HISTORY
|
|
.Nm
|
|
first appeared in
|
|
.Fx 13.0 .
|
|
.Sh BUGS
|
|
.Nm
|
|
may only be used after the kernel has panicked, due to limitations in the
|
|
treatment of locking primitives under
|
|
.Xr ddb 4 .
|
|
.Sh SECURITY CONSIDERATIONS
|
|
Version 1 of the
|
|
.Nm
|
|
protocol has no security properties whatsoever.
|
|
All messages are sent and acknowledged in cleartext, and no message
|
|
authentication codes are used to prevent attackers from forging messages.
|
|
It is absolutely inappropriate for use across the public internet.
|