2 .\" Copyright (c) 2018 Mark Johnston <markj@FreeBSD.org>
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
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.
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
32 .Nd protocol for transmitting kernel dumps to a remote server
34 To compile netdump client support into the kernel, place the following lines in
35 your kernel configuration file:
36 .Bd -ragged -offset indent
38 .Cd "options DEBUGNET"
42 netdump is a UDP-based protocol for transmitting kernel dumps to a remote host.
43 A netdump client is a panicking kernel, and a netdump server is a host
46 daemon, available in ports as
47 .Pa ports/ftp/netdumpd .
49 clients are configured using the
57 client messages consist of a fixed-size header followed by a variable-sized
59 The header contains the message type, a sequence number, the offset of
60 the payload data in the kernel dump, and the length of the payload data
61 (not including the header).
63 .Dv HERALD , FINISHED , KDH , VMCORE ,
67 server messages have a fixed size and contain only the sequence number of
69 These messages indicate that the server has successfully processed the
70 client message with the corresponding sequence number.
71 All client messages are acknowledged this way.
72 Server messages are always sent to port 20024 of the client.
78 message to the server at port 20023.
79 The client may include a relative path in its payload, in which case the
81 server should attempt to save the dump at that path relative to its configured
83 The server will acknowledge the
85 using a random source port, and the client must send all subsequent messages
92 message payloads contain the kernel dump header, dump contents, and
93 dump encryption key respectively.
94 The offset in the message header should be treated as a seek offset
95 in the corresponding file.
96 There are no ordering requirements for these messages.
100 is completed by sending the
102 message to the server.
104 The following network drivers support netdump:
119 The following variables are available as both
124 .Bl -tag -width "indent"
125 .It Va net.netdump.debug
126 Control debug message verbosity.
127 Debug messages are disabled by default, but are useful when troubleshooting
128 or when developing driver support.
129 .It Va net.netdump.path
130 Specify a path relative to the server's dump directory in which to store
134 server is configured to store dumps in
138 will cause the server to attempt to store dumps from the client in
140 The server will not automatically create the relative directory.
141 .It Va net.netdump.polls
142 The client will poll the configured network interface while waiting for
144 This parameter controls the maximum number of poll attempts before giving
145 up, which typically results in a re-transmit.
146 Each poll attempt takes 0.5ms.
147 .It Va net.netdump.retries
148 The number of times the client will re-transmit a packet before aborting
149 a dump due to a lack of acknowledgement.
150 The default may be too small in environments with lots of packet loss.
151 .It Va net.netdump.arp_retries
152 The number of times the client will attempt to learn the MAC address of
153 the configured gateway or server before giving up and aborting the dump.
161 client support first appeared in
164 Only IPv4 is supported.
167 may only be used after the kernel has panicked.