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