1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
|
.\"-
.\" Copyright (c) 2018 Mark Johnston <markj@FreeBSD.org>
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD$
.\"
.Dd October 29, 2018
.Dt NETDUMP 4
.Os
.Sh NAME
.Nm netdump
.Nd protocol for transmitting kernel dumps to a remote server
.Sh SYNOPSIS
To compile netdump client support into the kernel, place the following line in
your kernel configuration file:
.Bd -ragged -offset indent
.Cd "options NETDUMP"
.Ed
.Sh DESCRIPTION
netdump is a UDP-based protocol for transmitting kernel dumps to a remote host.
A netdump client is a panicking kernel, and a netdump server is a host
running the
.Nm
daemon, available in ports as
.Pa ports/ftp/netdumpd .
.Nm
clients are configured using the
.Xr dumpon 8
utility.
.Pp
.Nm
client messages consist of a fixed-size header followed by a variable-sized
payload.
The header contains the message type, a sequence number, the offset of
the payload data in the kernel dump, and the length of the payload data
(not including the header).
The message types are
.Dv HERALD , FINISHED , KDH , VMCORE ,
and
.Dv EKCD_KEY .
.Nm
server messages have a fixed size and contain only the sequence number of
the client message.
These messages indicate that the server has successfully processed the
client message with the corresponding sequence number.
All client messages are acknowledged this way.
Server messages are always sent to port 20024 of the client.
.Pp
To initiate a
.Nm ,
the client sends a
.Dv HERALD
message to the server at port 20023.
The client may include a relative path in its payload, in which case the
.Nm
server should attempt to save the dump at that path relative to its configured
dump directory.
The server will acknowledge the
.Dv HERALD
using a random source port, and the client must send all subsequent messages
to that port.
.Pp
The
.Dv KDH , VMCORE ,
and
.Dv EKCD_KEY
message payloads contain the kernel dump header, dump contents, and
dump encryption key respectively.
The offset in the message header should be treated as a seek offset
in the corresponding file.
There are no ordering requirements for these messages.
.Pp
A
.Nm
is completed by sending the
.Dv FINISHED
message to the server.
.Pp
The following network drivers support netdump:
.Xr alc 4 ,
.Xr bge 4 ,
.Xr bnxt 4 ,
.Xr bxe 4 ,
.Xr cxgb 4 ,
.Xr em 4 ,
.Xr igb 4 ,
.Xr ix 4 ,
.Xr re 4 ,
.Xr vtnet 4 .
.Sh SYSCTL VARIABLES
The following variables are available as both
.Xr sysctl 8
variables and
.Xr loader 8
variables:
.Bl -tag -width "indent"
.It Va net.netdump.debug
Control debug message verbosity.
Debug messages are disabled by default, but are useful when troubleshooting
or when developing driver support.
.It Va net.netdump.path
Specify a path relative to the server's dump directory in which to store
the dump.
For example, if the
.Nm
server is configured to store dumps in
.Pa /var/crash ,
a path of
.Dq foo
will cause the server to attempt to store dumps from the client in
.Pa /var/crash/foo .
The server will not automatically create the relative directory.
.It Va net.netdump.polls
The client will poll the configured network interface while waiting for
acknowledgements.
This parameter controls the maximum number of poll attempts before giving
up, which typically results in a re-transmit.
Each poll attempt takes 0.5ms.
.It Va net.netdump.retries
The number of times the client will re-transmit a packet before aborting
a dump due to a lack of acknowledgement.
The default may be too small in environments with lots of packet loss.
.It Va net.netdump.arp_retries
The number of times the client will attempt to learn the MAC address of
the configured gateway or server before giving up and aborting the dump.
.El
.Sh SEE ALSO
.Xr decryptcore 8 ,
.Xr dumpon 8 ,
.Xr savecore 8
.Sh HISTORY
.Nm
client support first appeared in
.Fx 12.0 .
.Sh BUGS
Only IPv4 is supported.
.Pp
.Nm
may only be used after the kernel has panicked.
|
