1.\"- 2.\" Copyright (c) 2018 Mark Johnston <markj@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 August 25, 2020 28.Dt NETDUMP 4 29.Os 30.Sh NAME 31.Nm netdump 32.Nd protocol for transmitting kernel dumps to a remote server 33.Sh SYNOPSIS 34To compile netdump client support into the kernel, place the following line in 35your kernel configuration file: 36.Bd -ragged -offset indent 37.Cd "options NETDUMP" 38.Ed 39.Sh DESCRIPTION 40netdump is a UDP-based protocol for transmitting kernel dumps to a remote host. 41A netdump client is a panicking kernel, and a netdump server is a host 42running the 43.Nm 44daemon, available in ports as 45.Pa ports/ftp/netdumpd . 46.Nm 47clients are configured using the 48.Xr dumpon 8 49utility or the 50.Ic netdump 51command in 52.Xr ddb 4 . 53.Pp 54.Nm 55client messages consist of a fixed-size header followed by a variable-sized 56payload. 57The header contains the message type, a sequence number, the offset of 58the payload data in the kernel dump, and the length of the payload data 59(not including the header). 60The message types are 61.Dv HERALD , FINISHED , KDH , VMCORE , 62and 63.Dv EKCD_KEY . 64.Nm 65server messages have a fixed size and contain only the sequence number of 66the client message. 67These messages indicate that the server has successfully processed the 68client message with the corresponding sequence number. 69All client messages are acknowledged this way. 70Server messages are always sent to port 20024 of the client. 71.Pp 72To initiate a 73.Nm , 74the client sends a 75.Dv HERALD 76message to the server at port 20023. 77The client may include a relative path in its payload, in which case the 78.Nm 79server should attempt to save the dump at that path relative to its configured 80dump directory. 81The server will acknowledge the 82.Dv HERALD 83using a random source port, and the client must send all subsequent messages 84to that port. 85.Pp 86The 87.Dv KDH , VMCORE , 88and 89.Dv EKCD_KEY 90message payloads contain the kernel dump header, dump contents, and 91dump encryption key respectively. 92The offset in the message header should be treated as a seek offset 93in the corresponding file. 94There are no ordering requirements for these messages. 95.Pp 96A 97.Nm 98is completed by sending the 99.Dv FINISHED 100message to the server. 101.Pp 102The following network drivers support netdump: 103.Xr alc 4 , 104.Xr bge 4 , 105.Xr bnxt 4 , 106.Xr bxe 4 , 107.Xr cxgb 4 , 108.Xr em 4 , 109.Xr igb 4 , 110.Xr ix 4 , 111.Xr ixl 4 , 112.Xr mlx4en 4 , 113.Xr mlx5en 4 , 114.Xr re 4 , 115.Xr vtnet 4 . 116.Sh SYSCTL VARIABLES 117The following variables are available as both 118.Xr sysctl 8 119variables and 120.Xr loader 8 121variables: 122.Bl -tag -width "indent" 123.It Va net.netdump.debug 124Control debug message verbosity. 125Debug messages are disabled by default, but are useful when troubleshooting 126or when developing driver support. 127.It Va net.netdump.path 128Specify a path relative to the server's dump directory in which to store 129the dump. 130For example, if the 131.Nm 132server is configured to store dumps in 133.Pa /var/crash , 134a path of 135.Dq foo 136will cause the server to attempt to store dumps from the client in 137.Pa /var/crash/foo . 138The server will not automatically create the relative directory. 139.It Va net.netdump.polls 140The client will poll the configured network interface while waiting for 141acknowledgements. 142This parameter controls the maximum number of poll attempts before giving 143up, which typically results in a re-transmit. 144Each poll attempt takes 0.5ms. 145.It Va net.netdump.retries 146The number of times the client will re-transmit a packet before aborting 147a dump due to a lack of acknowledgement. 148The default may be too small in environments with lots of packet loss. 149.It Va net.netdump.arp_retries 150The number of times the client will attempt to learn the MAC address of 151the configured gateway or server before giving up and aborting the dump. 152.El 153.Sh SEE ALSO 154.Xr decryptcore 8 , 155.Xr dumpon 8 , 156.Xr savecore 8 157.Sh HISTORY 158.Nm 159client support first appeared in 160.Fx 12.0 . 161.Sh BUGS 162Only IPv4 is supported. 163.Pp 164.Nm 165may only be used after the kernel has panicked. 166