share/man/man4/netdump.4

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