071e927e22
This is a component of a system which lets the kernel dump core to a remote host after a panic, rather than to a local storage device. The server component is available in the ports tree. netdump is particularly useful on diskless systems. The netdump(4) man page contains some details describing the protocol. Support for configuring netdump will be added to dumpon(8) in a future commit. To use netdump, the kernel must have been compiled with the NETDUMP option. The initial revision of netdump was written by Darrell Anderson and was integrated into Sandvine's OS, from which this version was derived. Reviewed by: bdrewery, cem (earlier versions), julian, sbruno MFC after: 1 month X-MFC note: use a spare field in struct ifnet Sponsored by: Dell EMC Isilon Differential Revision: https://reviews.freebsd.org/D15253
128 lines
3.8 KiB
Groff
128 lines
3.8 KiB
Groff
.\"-
|
|
.\" 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 May 4, 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
|
|
.Pp
|
|
Debug output can be enabled by adding the following line:
|
|
.Bd -ragged -offset indent
|
|
.Cd "options NETDUMP_DEBUG"
|
|
.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 bxe 4 ,
|
|
.Xr cxgb 4 ,
|
|
.Xr em 4 ,
|
|
.Xr igb 4 ,
|
|
.Xr ix 4 ,
|
|
.Xr mlx4en 4 ,
|
|
.Xr re 4 ,
|
|
.Xr vtnet 4 .
|
|
.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.
|