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