sbin/dumpon/dumpon.8

   1 .\" Copyright (c) 1980, 1991, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   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 .\" 3. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\"     From: @(#)swapon.8      8.1 (Berkeley) 6/5/93
  29 .\" $FreeBSD$
  30 .\"
  31 .Dd April 23, 2020
  32 .Dt DUMPON 8
  33 .Os
  34 .Sh NAME
  35 .Nm dumpon
  36 .Nd "specify a device for crash dumps"
  37 .Sh SYNOPSIS
  38 .Nm
  39 .Op Fl i Ar index
  40 .Op Fl r
  41 .Op Fl v
  42 .Op Fl C Ar cipher
  43 .Op Fl k Ar pubkey
  44 .Op Fl Z
  45 .Op Fl z
  46 .Ar device
  47 .Nm
  48 .Op Fl i Ar index
  49 .Op Fl r
  50 .Op Fl v
  51 .Op Fl C Ar cipher
  52 .Op Fl k Ar pubkey
  53 .Op Fl Z
  54 .Op Fl z
  55 .Op Fl g Ar gateway
  56 .Fl s Ar server
  57 .Fl c Ar client
  58 .Ar iface
  59 .Nm
  60 .Op Fl v
  61 .Cm off
  62 .Nm
  63 .Op Fl v
  64 .Fl l
  65 .Sh DESCRIPTION
  66 The
  67 .Nm
  68 utility is used to configure where the kernel can save a crash dump in the case
  69 of a panic.
  70 .Pp
  71 System administrators should typically configure
  72 .Nm
  73 in a persistent fashion using the
  74 .Xr rc.conf 5
  75 variables
  76 .Va dumpdev
  77 and
  78 .Va dumpon_flags .
  79 For more information on this usage, see
  80 .Xr rc.conf 5 .
  81 .Pp
  82 Starting in
  83 .Fx 13.0 ,
  84 .Nm
  85 can configure a series of fallback dump devices.
  86 For example, an administrator may prefer
  87 .Xr netdump 4
  88 by default, but if the
  89 .Xr netdump 4
  90 service cannot be reached or some other failure occurs, they might choose a
  91 local disk dump as a second choice option.
  92 .Ss General options
  93 .Bl -tag -width _k_pubkey
  94 .It Fl i Ar index
  95 Insert the specified dump configuration into the prioritized fallback dump
  96 device list at the specified index, starting at zero.
  97 .Pp
  98 If
  99 .Fl i
 100 is not specified, the configured dump device is appended to the prioritized
 101 list.
 102 .It Fl r
 103 Remove the specified dump device configuration or configurations from the
 104 fallback dump device list rather than inserting or appending it.
 105 In contrast,
 106 .Do
 107 .Nm
 108 off
 109 .Dc
 110 removes all configured devices.
 111 Conflicts with
 112 .Fl i .
 113 .It Fl k Ar pubkey
 114 Configure encrypted kernel dumps.
 115 .Pp
 116 A random, one-time symmetric key is automatically generated for bulk kernel
 117 dump encryption every time
 118 .Nm
 119 is used.
 120 The provided
 121 .Ar pubkey
 122 is used to encrypt a copy of the symmetric key.
 123 The encrypted dump contents consist of a standard dump header, the
 124 pubkey-encrypted symmetric key contents, and the symmetric key encrypted core
 125 dump contents.
 126 .Pp
 127 As a result, only someone with the corresponding private key can decrypt the symmetric key.
 128 The symmetric key is necessary to decrypt the kernel core.
 129 The goal of the mechanism is to provide confidentiality.
 130 .Pp
 131 The
 132 .Va pubkey
 133 file should be a PEM-formatted RSA key of at least 2048 bits.
 134 .It Fl C Ar cipher
 135 Select the symmetric algorithm used for encrypted kernel crash dump.
 136 The default is
 137 .Dq chacha20
 138 but
 139 .Dq aes256-cbc
 140 is also available.
 141 (AES256-CBC mode does not work in conjunction with compression.)
 142 .It Fl l
 143 List the currently configured dump device(s), or /dev/null if no devices are
 144 configured.
 145 .It Fl v
 146 Enable verbose mode.
 147 .It Fl Z
 148 Enable compression (Zstandard).
 149 .It Fl z
 150 Enable compression (gzip).
 151 Only one compression method may be enabled at a time, so
 152 .Fl z
 153 is incompatible with
 154 .Fl Z .
 155 .Pp
 156 Zstandard provides superior compression ratio and performance.
 157 .El
 158 .Ss Netdump
 159 .Nm
 160 may also configure the kernel to dump to a remote
 161 .Xr netdumpd 8
 162 server.
 163 (The
 164 .Xr netdumpd 8
 165 server is available in ports.)
 166 .Xr netdump 4
 167 eliminates the need to reserve space for crash dumps.
 168 It is especially useful in diskless environments.
 169 When
 170 .Nm
 171 is used to configure netdump, the
 172 .Ar device
 173 (or
 174 .Ar iface )
 175 parameter should specify a network interface (e.g.,
 176 .Va igb1 ) .
 177 The specified NIC must be up (online) to configure netdump.
 178 .Pp
 179 .Xr netdump 4
 180 specific options include:
 181 .Bl -tag -width _g_gateway
 182 .It Fl c Ar client
 183 The local IP address of the
 184 .Xr netdump 4
 185 client.
 186 .It Fl g Ar gateway
 187 The first-hop router between
 188 .Ar client
 189 and
 190 .Ar server .
 191 If the
 192 .Fl g
 193 option is not specified and the system has a default route, the default
 194 router is used as the
 195 .Xr netdump 4
 196 gateway.
 197 If the
 198 .Fl g
 199 option is not specified and the system does not have a default route,
 200 .Ar server
 201 is assumed to be on the same link as
 202 .Ar client .
 203 .It Fl s Ar server
 204 The IP address of the
 205 .Xr netdumpd 8
 206 server.
 207 .El
 208 .Pp
 209 All of these options can be specified in the
 210 .Xr rc.conf 5
 211 variable
 212 .Va dumpon_flags .
 213 .Ss Minidumps
 214 The default type of kernel crash dump is the mini crash dump.
 215 Mini crash dumps hold only memory pages in use by the kernel.
 216 Alternatively, full memory dumps can be enabled by setting the
 217 .Va debug.minidump
 218 .Xr sysctl 8
 219 variable to 0.
 220 .Ss Full dumps
 221 For systems using full memory dumps, the size of the specified dump
 222 device must be at least the size of physical memory.
 223 Even though an additional 64 kB header is added to the dump, the BIOS for a
 224 platform typically holds back some memory, so it is not usually
 225 necessary to size the dump device larger than the actual amount of RAM
 226 available in the machine.
 227 Also, when using full memory dumps, the
 228 .Nm
 229 utility will refuse to enable a dump device which is smaller than the
 230 total amount of physical memory as reported by the
 231 .Va hw.physmem
 232 .Xr sysctl 8
 233 variable.
 234 .Sh IMPLEMENTATION NOTES
 235 Because the file system layer is already dead by the time a crash dump
 236 is taken, it is not possible to send crash dumps directly to a file.
 237 .Pp
 238 The
 239 .Xr loader 8
 240 variable
 241 .Va dumpdev
 242 may be used to enable early kernel core dumps for system panics which occur
 243 before userspace starts.
 244 .Sh EXAMPLES
 245 In order to generate an RSA private key, a user can use the
 246 .Xr genrsa 1
 247 tool:
 248 .Pp
 249 .Dl # openssl genrsa -out private.pem 4096
 250 .Pp
 251 A public key can be extracted from the private key using the
 252 .Xr rsa 1
 253 tool:
 254 .Pp
 255 .Dl # openssl rsa -in private.pem -out public.pem -pubout
 256 .Pp
 257 Once the RSA keys are created in a safe place, the public key may be moved to
 258 the untrusted netdump client machine.
 259 Now
 260 .Pa public.pem
 261 can be used by
 262 .Nm
 263 to configure encrypted kernel crash dumps:
 264 .Pp
 265 .Dl # dumpon -k public.pem /dev/ada0s1b
 266 .Pp
 267 It is recommended to test if the kernel saves encrypted crash dumps using the
 268 current configuration.
 269 The easiest way to do that is to cause a kernel panic using the
 270 .Xr ddb 4
 271 debugger:
 272 .Pp
 273 .Dl # sysctl debug.kdb.panic=1
 274 .Pp
 275 In the debugger the following commands should be typed to write a core dump and
 276 reboot:
 277 .Pp
 278 .Dl db> call doadump(0)
 279 .Dl db> reset
 280 .Pp
 281 After reboot
 282 .Xr savecore 8
 283 should be able to save the core dump in the
 284 .Va Dq dumpdir
 285 directory, which is
 286 .Pa /var/crash
 287 by default:
 288 .Pp
 289 .Dl # savecore /dev/ada0s1b
 290 .Pp
 291 Three files should be created in the core directory:
 292 .Pa info.# ,
 293 .Pa key.#
 294 and
 295 .Pa vmcore_encrypted.#
 296 (where
 297 .Dq #
 298 is the number of the last core dump saved by
 299 .Xr savecore 8 ) .
 300 The
 301 .Pa vmcore_encrypted.#
 302 can be decrypted using the
 303 .Xr decryptcore 8
 304 utility:
 305 .Pp
 306 .Dl # decryptcore -p private.pem -k key.# -e vmcore_encrypted.# -c vmcore.#
 307 .Pp
 308 or shorter:
 309 .Pp
 310 .Dl # decryptcore -p private.pem -n #
 311 .Pp
 312 The
 313 .Pa vmcore.#
 314 can be now examined using
 315 .Xr kgdb 1 :
 316 .Pp
 317 .Dl # kgdb /boot/kernel/kernel vmcore.#
 318 .Pp
 319 or shorter:
 320 .Pp
 321 .Dl # kgdb -n #
 322 .Pp
 323 The core was decrypted properly if
 324 .Xr kgdb 1
 325 does not print any errors.
 326 Note that the live kernel might be at a different path
 327 which can be examined by looking at the
 328 .Va kern.bootfile
 329 .Xr sysctl 8 .
 330 .Pp
 331 The
 332 .Nm
 333 .Xr rc 8
 334 script runs early during boot, typically before networking is configured.
 335 This makes it unsuitable for configuring
 336 .Xr netdump
 337 when the client address is dynamic.
 338 To configure
 339 .Xr netdump
 340 when
 341 .Xr dhclient
 342 binds to a server,
 343 .Xr dhclient-script
 344 can be used to run
 345 .Xr dumpon .
 346 For example, to automatically configure
 347 .Xr netdump
 348 on the vtnet0 interface, add the following to
 349 .Pa /etc/dhclient-exit-hooks .
 350 .Bd -literal
 351 case $reason in
 352 BOUND|REBIND|REBOOT|RENEW)
 353         if [ "$interface" != vtnet0 ] || [ -n "$old_ip_address" -a \\
 354              "$old_ip_address" = "$new_ip_address" ]; then
 355                 break
 356         fi
 357         if [ -n "$new_routers" ]; then
 358                 # Take the first router in the list.
 359                 gateway_flag="-g ${new_routers%% *}"
 360         fi
 361         # Configure as the highest-priority dump device.
 362         dumpon -i 0 -c $new_ip_address -s $server $gateway_flag vtnet0
 363         ;;
 364 esac
 365 .Ed
 366 .Pp
 367 Be sure to fill in the server IP address and change the interface name if
 368 needed.
 369 .Sh SEE ALSO
 370 .Xr gzip 1 ,
 371 .Xr kgdb 1 ,
 372 .Xr zstd 1 ,
 373 .Xr ddb 4 ,
 374 .Xr netdump 4 ,
 375 .Xr fstab 5 ,
 376 .Xr rc.conf 5 ,
 377 .Xr config 8 ,
 378 .Xr decryptcore 8 ,
 379 .Xr init 8 ,
 380 .Xr loader 8 ,
 381 .Xr rc 8 ,
 382 .Xr savecore 8 ,
 383 .Xr swapon 8 ,
 384 .Xr panic 9
 385 .Sh HISTORY
 386 The
 387 .Nm
 388 utility appeared in
 389 .Fx 2.0.5 .
 390 .Pp
 391 Support for encrypted kernel core dumps and netdump was added in
 392 .Fx 12.0 .
 393 .Sh AUTHORS
 394 The
 395 .Nm
 396 manual page was written by
 397 .An Mark Johnston Aq Mt markj@FreeBSD.org ,
 398 .An Conrad Meyer Aq Mt cem@FreeBSD.org ,
 399 .An Konrad Witaszczyk Aq Mt def@FreeBSD.org ,
 400 and countless others.
 401 .Sh CAVEATS
 402 To configure encrypted kernel core dumps, the running kernel must have been
 403 compiled with the
 404 .Dv EKCD
 405 option.
 406 .Pp
 407 Netdump does not automatically update the configured
 408 .Ar gateway
 409 if routing topology changes.
 410 .Pp
 411 The size of a compressed dump or a minidump is not a fixed function of RAM
 412 size.
 413 Therefore, when at least one of these options is enabled, the
 414 .Nm
 415 utility cannot verify that the
 416 .Ar device
 417 has sufficient space for a dump.
 418 .Nm
 419 is also unable to verify that a configured
 420 .Xr netdumpd 8
 421 server has sufficient space for a dump.
 422 .Pp
 423 .Fl Z
 424 requires a kernel compiled with the
 425 .Dv ZSTDIO
 426 kernel option.
 427 Similarly,
 428 .Fl z
 429 requires the
 430 .Dv GZIO
 431 option.
 432 .Sh BUGS
 433 Netdump only supports IPv4 at this time.
 434 .Sh SECURITY CONSIDERATIONS
 435 The current encrypted kernel core dump scheme does not provide integrity nor
 436 authentication.
 437 That is, the recipient of an encrypted kernel core dump cannot know if they
 438 received an intact core dump, nor can they verify the provenance of the dump.
 439 .Pp
 440 RSA keys smaller than 1024 bits are practical to factor and therefore weak.
 441 Even 1024 bit keys may not be large enough to ensure privacy for many
 442 years, so NIST recommends a minimum of 2048 bit RSA keys.
 443 As a seatbelt,
 444 .Nm
 445 prevents users from configuring encrypted kernel dumps with extremely weak RSA
 446 keys.
 447 If you do not care for cryptographic privacy guarantees, just use
 448 .Nm
 449 without specifying a
 450 .Fl k Ar pubkey
 451 option.
 452 .Pp
 453 This process is sandboxed using
 454 .Xr capsicum 4 .