diff options
Diffstat (limited to 'static/freebsd/man4/netgdb.4 3.html')
| -rw-r--r-- | static/freebsd/man4/netgdb.4 3.html | 121 |
1 files changed, 121 insertions, 0 deletions
diff --git a/static/freebsd/man4/netgdb.4 3.html b/static/freebsd/man4/netgdb.4 3.html new file mode 100644 index 00000000..fc77e133 --- /dev/null +++ b/static/freebsd/man4/netgdb.4 3.html @@ -0,0 +1,121 @@ +<table class="head"> + <tr> + <td class="head-ltitle">NETGDB(4)</td> + <td class="head-vol">Device Drivers Manual</td> + <td class="head-rtitle">NETGDB(4)</td> + </tr> +</table> +<div class="manual-text"> +<section class="Sh"> +<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1> +<p class="Pp"><code class="Nm">netgdb</code> — <span class="Nd">protocol + for debugging the kernel with GDB over the network</span></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<p class="Pp">To compile NetGDB support into the kernel, place the following + lines in your kernel configuration file:</p> +<div class="Bd Pp Bd-indent"><code class="Cd">options DDB</code> +<br/> +<code class="Cd">options GDB</code> +<br/> +<code class="Cd">options INET</code> +<br/> +<code class="Cd">options DEBUGNET</code> +<br/> +<code class="Cd">options NETGDB</code></div> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp"><code class="Nm">netgdb</code> is a UDP-based protocol for + communicating with a remote GDB client via an intermediary proxy.</p> +<p class="Pp">A <code class="Nm">netgdb</code> session is started by using the + <code class="Ic">netgdb</code> <code class="Fl">-s</code> + <var class="Ar">server</var> [<code class="Fl">-g</code> + <var class="Ar">gateway</var> <code class="Fl">-c</code> + <var class="Ar">client</var> <code class="Fl">-i</code> + <var class="Ar">iface</var>] command in <a class="Xr">ddb(4)</a> to connect + to a proxy server. When the connection is made, the proxy server logs a + message that a <code class="Nm">netgdb</code> 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:</p> +<div class="Bd Pp Bd-indent"><code class="Ic">target remote</code> + ⟨<var class="Ar">proxyip:proxyport</var>⟩</div> +<p class="Pp">At this point, the server proxies traffic back and forth between + <code class="Nm">netgdb</code> and the ordinary GDB client, speaking the + ordinary GDB remote protocol. The <code class="Nm">netgdb</code> session is + identical to any other kernel GDB session from the perspective of the GDB + debugger.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="IMPLEMENTATION_NOTES"><a class="permalink" href="#IMPLEMENTATION_NOTES">IMPLEMENTATION + NOTES</a></h1> +<p class="Pp">The UDP protocol is based on the same packet structure and a + subset of the exact same message types as <a class="Xr">netdump(4)</a>. It + uses the <code class="Dv">HERALD</code>, <code class="Dv">DATA</code> + (<code class="Dv">née VMCORE</code>), and + <code class="Dv">FINISHED</code> message types. Like + <a class="Xr">netdump(4)</a>, the client's initial + <code class="Dv">HERALD</code> message is acknowledged from a random source + port, and the client sends subsequent communication to that port.</p> +<p class="Pp">Unlike <a class="Xr">netdump(4)</a>, the initial + <code class="Dv">HERALD</code> port is 20025. Additionally, the proxy server + sends responses to the source port of the client's initial + <code class="Dv">HERALD</code>, rather than a separate reserved port. + <code class="Nm">netgdb</code> 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.</p> +<p class="Pp">The first version of the <code class="Nm">netgdb</code> protocol + uses the protocol number ‘0x2515f095’ in the 32-bit + <var class="Va">aux2</var> parameter of the initial + <code class="Dv">HERALD</code> message.</p> +<p class="Pp">The list of supported network drivers and protocol families is + identical to that of <a class="Xr">netdump(4)</a>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DIAGNOSTICS"><a class="permalink" href="#DIAGNOSTICS">DIAGNOSTICS</a></h1> +<p class="Pp">The following variable is available via both + <a class="Xr">sysctl(8)</a> and <a class="Xr">loader(8)</a> (as a + tunable):</p> +<dl class="Bl-tag"> + <dt id="debug.gdb.netgdb.debug"><var class="Va">debug.gdb.netgdb.debug</var></dt> + <dd>Control debug message verbosity. Debug messages are disabled by default. + They may be enabled by setting the variable to a non-zero value.</dd> +</dl> +</section> +<section class="Sh"> +<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE + ALSO</a></h1> +<p class="Pp"><a class="Xr">ddb(4)</a>, <a class="Xr">gdb(4)</a>, + <a class="Xr">netdump(4)</a></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> +<p class="Pp"><code class="Nm">netgdb</code> first appeared in + <span class="Ux">FreeBSD 13.0</span>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="BUGS"><a class="permalink" href="#BUGS">BUGS</a></h1> +<p class="Pp"><code class="Nm">netgdb</code> may only be used after the kernel + has panicked, due to limitations in the treatment of locking primitives + under <a class="Xr">ddb(4)</a>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="SECURITY_CONSIDERATIONS"><a class="permalink" href="#SECURITY_CONSIDERATIONS">SECURITY + CONSIDERATIONS</a></h1> +<p class="Pp">Version 1 of the <code class="Nm">netgdb</code> 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.</p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">November 10, 2022</td> + <td class="foot-os">FreeBSD 15.0</td> + </tr> +</table> |