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 October 26, 2018 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 | Li default 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 143Optional. 144If not specified, it is assumed that the 145.Ar server 146is on the same link as the 147.Ar client . 148.Pp 149If specified, 150.Ar gateway 151is the address of the first-hop router between the 152.Ar client 153and the 154.Ar server . 155The special value 156.Dv Dq default 157indicates that the currently configured system default route should be used. 158.It Fl s Ar server 159The IP address of the 160.Xr netdumpd 8 161server. 162.El 163.Pp 164All of these options can be specified in the 165.Xr rc.conf 5 166variable 167.Va dumpon_flags . 168.Ss Minidumps 169The default type of kernel crash dump is the mini crash dump. 170Mini crash dumps hold only memory pages in use by the kernel. 171Alternatively, full memory dumps can be enabled by setting the 172.Va debug.minidump 173.Xr sysctl 8 174variable to 0. 175.Ss Full dumps 176For systems using full memory dumps, the size of the specified dump 177device must be at least the size of physical memory. 178Even though an additional 64 kB header is added to the dump, the BIOS for a 179platform typically holds back some memory, so it is not usually 180necessary to size the dump device larger than the actual amount of RAM 181available in the machine. 182Also, when using full memory dumps, the 183.Nm 184utility will refuse to enable a dump device which is smaller than the 185total amount of physical memory as reported by the 186.Va hw.physmem 187.Xr sysctl 8 188variable. 189.Sh IMPLEMENTATION NOTES 190Because the file system layer is already dead by the time a crash dump 191is taken, it is not possible to send crash dumps directly to a file. 192.Pp 193The 194.Xr loader 8 195variable 196.Va dumpdev 197may be used to enable early kernel core dumps for system panics which occur 198before userspace starts. 199.Sh EXAMPLES 200In order to generate an RSA private key, a user can use the 201.Xr genrsa 1 202tool: 203.Pp 204.Dl # openssl genrsa -out private.pem 4096 205.Pp 206A public key can be extracted from the private key using the 207.Xr rsa 1 208tool: 209.Pp 210.Dl # openssl rsa -in private.pem -out public.pem -pubout 211.Pp 212Once the RSA keys are created in a safe place, the public key may be moved to 213the untrusted netdump client machine. 214Now 215.Pa public.pem 216can be used by 217.Nm 218to configure encrypted kernel crash dumps: 219.Pp 220.Dl # dumpon -k public.pem /dev/ada0s1b 221.Pp 222It is recommended to test if the kernel saves encrypted crash dumps using the 223current configuration. 224The easiest way to do that is to cause a kernel panic using the 225.Xr ddb 4 226debugger: 227.Pp 228.Dl # sysctl debug.kdb.panic=1 229.Pp 230In the debugger the following commands should be typed to write a core dump and 231reboot: 232.Pp 233.Dl db> call doadump(0) 234.Dl db> reset 235.Pp 236After reboot 237.Xr savecore 8 238should be able to save the core dump in the 239.Va Dq dumpdir 240directory, which is 241.Pa /var/crash 242by default: 243.Pp 244.Dl # savecore /dev/ada0s1b 245.Pp 246Three files should be created in the core directory: 247.Pa info.# , 248.Pa key.# 249and 250.Pa vmcore_encrypted.# 251(where 252.Dq # 253is the number of the last core dump saved by 254.Xr savecore 8 ) . 255The 256.Pa vmcore_encrypted.# 257can be decrypted using the 258.Xr decryptcore 8 259utility: 260.Pp 261.Dl # decryptcore -p private.pem -k key.# -e vmcore_encrypted.# -c vmcore.# 262.Pp 263or shorter: 264.Pp 265.Dl # decryptcore -p private.pem -n # 266.Pp 267The 268.Pa vmcore.# 269can be now examined using 270.Xr kgdb 1 : 271.Pp 272.Dl # kgdb /boot/kernel/kernel vmcore.# 273.Pp 274or shorter: 275.Pp 276.Dl # kgdb -n # 277.Pp 278The core was decrypted properly if 279.Xr kgdb 1 280does not print any errors. 281Note that the live kernel might be at a different path 282which can be examined by looking at the 283.Va kern.bootfile 284.Xr sysctl 8 . 285.Sh SEE ALSO 286.Xr gzip 1 , 287.Xr kgdb 1 , 288.Xr zstd 1 , 289.Xr ddb 4 , 290.Xr netdump 4 , 291.Xr fstab 5 , 292.Xr rc.conf 5 , 293.Xr config 8 , 294.Xr decryptcore 8 , 295.Xr init 8 , 296.Xr loader 8 , 297.Xr rc 8 , 298.Xr savecore 8 , 299.Xr swapon 8 , 300.Xr panic 9 301.Sh HISTORY 302The 303.Nm 304utility appeared in 305.Fx 2.0.5 . 306.Pp 307Support for encrypted kernel core dumps and netdump was added in 308.Fx 12.0 . 309.Sh AUTHORS 310The 311.Nm 312manual page was written by 313.An Mark Johnston Aq Mt markj@FreeBSD.org , 314.An Conrad Meyer Aq Mt cem@FreeBSD.org , 315.An Konrad Witaszczyk Aq Mt def@FreeBSD.org , 316and countless others. 317.Sh CAVEATS 318To configure encrypted kernel core dumps, the running kernel must have been 319compiled with the 320.Dv EKCD 321option. 322.Pp 323Netdump does not automatically update the configured 324.Ar gateway 325if routing topology changes. 326.Pp 327The size of a compressed dump or a minidump is not a fixed function of RAM 328size. 329Therefore, when at least one of these options is enabled, the 330.Nm 331utility cannot verify that the 332.Ar device 333has sufficient space for a dump. 334.Nm 335is also unable to verify that a configured 336.Xr netdumpd 8 337server has sufficient space for a dump. 338.Pp 339.Fl Z 340requires a kernel compiled with the 341.Dv ZSTDIO 342kernel option. 343Similarly, 344.Fl z 345requires the 346.Dv GZIO 347option. 348.Sh BUGS 349It is currently not possible to configure both compression and encryption. 350The encrypted dump format assumes that the kernel dump size is a multiple 351of the cipher block size, which may not be true when the dump is compressed. 352.Pp 353Netdump only supports IPv4 at this time. 354.Sh SECURITY CONSIDERATIONS 355The current encrypted kernel core dump scheme does not provide integrity nor 356authentication. 357That is, the recipient of an encrypted kernel core dump cannot know if they 358received an intact core dump, nor can they verify the provenance of the dump. 359.Pp 360RSA keys smaller than 1024 bits are practical to factor and therefore weak. 361Even 1024 bit keys may not be large enough to ensure privacy for many 362years, so NIST recommends a minimum of 2048 bit RSA keys. 363As a seatbelt, 364.Nm 365prevents users from configuring encrypted kernel dumps with extremely weak RSA 366keys. 367If you do not care for cryptographic privacy guarantees, just use 368.Nm 369without specifying a 370.Fl k Ar pubkey 371option. 372.Pp 373This process is sandboxed using 374.Xr capsicum 4 . 375