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