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