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 66The 67.Nm 68utility is used to configure where the kernel can save a crash dump in the case 69of a panic. 70.Pp 71System administrators should typically configure 72.Nm 73in a persistent fashion using the 74.Xr rc.conf 5 75variables 76.Va dumpdev 77and 78.Va dumpon_flags . 79For more information on this usage, see 80.Xr rc.conf 5 . 81.Pp 82Starting in 83.Fx 13.0 , 84.Nm 85can configure a series of fallback dump devices. 86For example, an administrator may prefer 87.Xr netdump 4 88by default, but if the 89.Xr netdump 4 90service cannot be reached or some other failure occurs, they might choose a 91local disk dump as a second choice option. 92.Ss General options 93.Bl -tag -width _k_pubkey 94.It Fl i Ar index 95Insert the specified dump configuration into the prioritized fallback dump 96device list at the specified index, starting at zero. 97.Pp 98If 99.Fl i 100is not specified, the configured dump device is appended to the prioritized 101list. 102.It Fl r 103Remove the specified dump device configuration or configurations from the 104fallback dump device list rather than inserting or appending it. 105In contrast, 106.Do 107.Nm 108off 109.Dc 110removes all configured devices. 111Conflicts with 112.Fl i . 113.It Fl k Ar pubkey 114Configure encrypted kernel dumps. 115.Pp 116A random, one-time symmetric key is automatically generated for bulk kernel 117dump encryption every time 118.Nm 119is used. 120The provided 121.Ar pubkey 122is used to encrypt a copy of the symmetric key. 123The encrypted dump contents consist of a standard dump header, the 124pubkey-encrypted symmetric key contents, and the symmetric key encrypted core 125dump contents. 126.Pp 127As a result, only someone with the corresponding private key can decrypt the symmetric key. 128The symmetric key is necessary to decrypt the kernel core. 129The goal of the mechanism is to provide confidentiality. 130.Pp 131The 132.Va pubkey 133file should be a PEM-formatted RSA key of at least 2048 bits. 134.It Fl C Ar cipher 135Select the symmetric algorithm used for encrypted kernel crash dump. 136The default is 137.Dq chacha20 138but 139.Dq aes256-cbc 140is also available. 141(AES256-CBC mode does not work in conjunction with compression.) 142.It Fl l 143List the currently configured dump device(s), or /dev/null if no devices are 144configured. 145.It Fl v 146Enable verbose mode. 147.It Fl Z 148Enable compression (Zstandard). 149.It Fl z 150Enable compression (gzip). 151Only one compression method may be enabled at a time, so 152.Fl z 153is incompatible with 154.Fl Z . 155.Pp 156Zstandard provides superior compression ratio and performance. 157.El 158.Ss Netdump 159.Nm 160may also configure the kernel to dump to a remote 161.Xr netdumpd 8 162server. 163(The 164.Xr netdumpd 8 165server is available in ports.) 166.Xr netdump 4 167eliminates the need to reserve space for crash dumps. 168It is especially useful in diskless environments. 169When 170.Nm 171is used to configure netdump, the 172.Ar device 173(or 174.Ar iface ) 175parameter should specify a network interface (e.g., 176.Va igb1 ) . 177The specified NIC must be up (online) to configure netdump. 178.Pp 179.Xr netdump 4 180specific options include: 181.Bl -tag -width _g_gateway 182.It Fl c Ar client 183The local IP address of the 184.Xr netdump 4 185client. 186.It Fl g Ar gateway 187The first-hop router between 188.Ar client 189and 190.Ar server . 191If the 192.Fl g 193option is not specified and the system has a default route, the default 194router is used as the 195.Xr netdump 4 196gateway. 197If the 198.Fl g 199option is not specified and the system does not have a default route, 200.Ar server 201is assumed to be on the same link as 202.Ar client . 203.It Fl s Ar server 204The IP address of the 205.Xr netdumpd 8 206server. 207.El 208.Pp 209All of these options can be specified in the 210.Xr rc.conf 5 211variable 212.Va dumpon_flags . 213.Ss Minidumps 214The default type of kernel crash dump is the mini crash dump. 215Mini crash dumps hold only memory pages in use by the kernel. 216Alternatively, full memory dumps can be enabled by setting the 217.Va debug.minidump 218.Xr sysctl 8 219variable to 0. 220.Ss Full dumps 221For systems using full memory dumps, the size of the specified dump 222device must be at least the size of physical memory. 223Even though an additional 64 kB header is added to the dump, the BIOS for a 224platform typically holds back some memory, so it is not usually 225necessary to size the dump device larger than the actual amount of RAM 226available in the machine. 227Also, when using full memory dumps, the 228.Nm 229utility will refuse to enable a dump device which is smaller than the 230total amount of physical memory as reported by the 231.Va hw.physmem 232.Xr sysctl 8 233variable. 234.Sh IMPLEMENTATION NOTES 235Because the file system layer is already dead by the time a crash dump 236is taken, it is not possible to send crash dumps directly to a file. 237.Pp 238The 239.Xr loader 8 240variable 241.Va dumpdev 242may be used to enable early kernel core dumps for system panics which occur 243before userspace starts. 244.Sh EXAMPLES 245In order to generate an RSA private key, a user can use the 246.Xr genrsa 1 247tool: 248.Pp 249.Dl # openssl genrsa -out private.pem 4096 250.Pp 251A public key can be extracted from the private key using the 252.Xr rsa 1 253tool: 254.Pp 255.Dl # openssl rsa -in private.pem -out public.pem -pubout 256.Pp 257Once the RSA keys are created in a safe place, the public key may be moved to 258the untrusted netdump client machine. 259Now 260.Pa public.pem 261can be used by 262.Nm 263to configure encrypted kernel crash dumps: 264.Pp 265.Dl # dumpon -k public.pem /dev/ada0s1b 266.Pp 267It is recommended to test if the kernel saves encrypted crash dumps using the 268current configuration. 269The easiest way to do that is to cause a kernel panic using the 270.Xr ddb 4 271debugger: 272.Pp 273.Dl # sysctl debug.kdb.panic=1 274.Pp 275In the debugger the following commands should be typed to write a core dump and 276reboot: 277.Pp 278.Dl db> call doadump(0) 279.Dl db> reset 280.Pp 281After reboot 282.Xr savecore 8 283should be able to save the core dump in the 284.Va Dq dumpdir 285directory, which is 286.Pa /var/crash 287by default: 288.Pp 289.Dl # savecore /dev/ada0s1b 290.Pp 291Three files should be created in the core directory: 292.Pa info.# , 293.Pa key.# 294and 295.Pa vmcore_encrypted.# 296(where 297.Dq # 298is the number of the last core dump saved by 299.Xr savecore 8 ) . 300The 301.Pa vmcore_encrypted.# 302can be decrypted using the 303.Xr decryptcore 8 304utility: 305.Pp 306.Dl # decryptcore -p private.pem -k key.# -e vmcore_encrypted.# -c vmcore.# 307.Pp 308or shorter: 309.Pp 310.Dl # decryptcore -p private.pem -n # 311.Pp 312The 313.Pa vmcore.# 314can be now examined using 315.Xr kgdb 1 : 316.Pp 317.Dl # kgdb /boot/kernel/kernel vmcore.# 318.Pp 319or shorter: 320.Pp 321.Dl # kgdb -n # 322.Pp 323The core was decrypted properly if 324.Xr kgdb 1 325does not print any errors. 326Note that the live kernel might be at a different path 327which can be examined by looking at the 328.Va kern.bootfile 329.Xr sysctl 8 . 330.Pp 331The 332.Nm 333.Xr rc 8 334script runs early during boot, typically before networking is configured. 335This makes it unsuitable for configuring 336.Xr netdump 337when the client address is dynamic. 338To configure 339.Xr netdump 340when 341.Xr dhclient 342binds to a server, 343.Xr dhclient-script 344can be used to run 345.Xr dumpon . 346For example, to automatically configure 347.Xr netdump 348on the vtnet0 interface, add the following to 349.Pa /etc/dhclient-exit-hooks . 350.Bd -literal 351case $reason in 352BOUND|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 ;; 364esac 365.Ed 366.Pp 367Be sure to fill in the server IP address and change the interface name if 368needed. 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 386The 387.Nm 388utility appeared in 389.Fx 2.0.5 . 390.Pp 391Support for encrypted kernel core dumps and netdump was added in 392.Fx 12.0 . 393.Sh AUTHORS 394The 395.Nm 396manual 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 , 400and countless others. 401.Sh CAVEATS 402To configure encrypted kernel core dumps, the running kernel must have been 403compiled with the 404.Dv EKCD 405option. 406.Pp 407Netdump does not automatically update the configured 408.Ar gateway 409if routing topology changes. 410.Pp 411The size of a compressed dump or a minidump is not a fixed function of RAM 412size. 413Therefore, when at least one of these options is enabled, the 414.Nm 415utility cannot verify that the 416.Ar device 417has sufficient space for a dump. 418.Nm 419is also unable to verify that a configured 420.Xr netdumpd 8 421server has sufficient space for a dump. 422.Pp 423.Fl Z 424requires a kernel compiled with the 425.Dv ZSTDIO 426kernel option. 427Similarly, 428.Fl z 429requires the 430.Dv GZIO 431option. 432.Sh BUGS 433Netdump only supports IPv4 at this time. 434.Sh SECURITY CONSIDERATIONS 435The current encrypted kernel core dump scheme does not provide integrity nor 436authentication. 437That is, the recipient of an encrypted kernel core dump cannot know if they 438received an intact core dump, nor can they verify the provenance of the dump. 439.Pp 440RSA keys smaller than 1024 bits are practical to factor and therefore weak. 441Even 1024 bit keys may not be large enough to ensure privacy for many 442years, so NIST recommends a minimum of 2048 bit RSA keys. 443As a seatbelt, 444.Nm 445prevents users from configuring encrypted kernel dumps with extremely weak RSA 446keys. 447If you do not care for cryptographic privacy guarantees, just use 448.Nm 449without specifying a 450.Fl k Ar pubkey 451option. 452.Pp 453This process is sandboxed using 454.Xr capsicum 4 . 455