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