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 February 13, 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 public_key_file 41.Op Fl z 42.Op Fl Z 43.Ar special_file 44.Nm 45.Op Fl v 46.Cm off 47.Nm 48.Op Fl v 49.Fl l 50.Sh DESCRIPTION 51The 52.Nm 53utility is used to specify a device where the kernel can save a crash 54dump in the case of a panic. 55.Pp 56Calls to 57.Nm 58normally occur from the system multi-user initialization file 59.Pa /etc/rc , 60controlled by the 61.Dq dumpdev 62and 63.Dq dumppubkey 64variables in the boot time configuration file 65.Pa /etc/rc.conf . 66.Pp 67The default type of kernel crash dump is the mini crash dump. 68Mini crash dumps hold only memory pages in use by the kernel. 69Alternatively, full memory dumps can be enabled by setting the 70.Va debug.minidump 71.Xr sysctl 8 72variable to 0. 73.Pp 74For systems using full memory dumps, the size of the specified dump 75device must be at 76least the size of physical memory. 77Even though an additional 64 kB header is added to the dump, the BIOS for a 78platform typically holds back some memory, so it is not usually 79necessary to size the dump device larger than the actual amount of RAM 80available in the machine. 81Also, when using full memory dumps, the 82.Nm 83utility will refuse to enable a dump device which is smaller than the 84total amount of physical memory as reported by the 85.Va hw.physmem 86.Xr sysctl 8 87variable. 88.Pp 89The 90.Op Fl k Ar public_key_file 91flag causes 92.Nm 93to generate a one-time key for kernel crash dump encryption. 94The key will be replaced by a new one when the 95.Nm 96utility is run again. 97The key is encrypted using 98.Ar public_key_file . 99This process is sandboxed using 100.Xr capsicum 4 . 101Both plain and encrypted keys are sent to the kernel using 102.Dv DIOCSKERNELDUMP 103.Xr ioctl 2 . 104A user can specify the 105.Ar public_key_file 106in the 107.Dq dumppubkey 108variable defined in 109.Pa /etc/rc.conf 110for use with the 111.Pa /etc/rc.d/dumpon 112.Xr rc 8 113script. 114This flag requires a kernel compiled with the 115.Dv EKCD 116kernel option. 117.Pp 118The 119.Fl z 120and 121.Fl Z 122options configure the kernel to compress the dump before writing it to 123the dump device. 124This reduces the amount of space required for the dump and accelerates 125recovery with 126.Xr savecore 8 127since less data needs to be copied from the dump device. 128When compression is enabled, the 129.Nm 130utility will not verify that the dump device is sufficiently large for a full 131dump. 132The 133.Fl z 134and 135.Fl Z 136options cause the dump to be written in 137.Xr gzip 1 138and 139.Xr zstd 1 140format, respectively. 141These flags require a kernel compiled with the 142.Dv GZIO 143or 144.Dv ZSTDIO 145kernel options. 146.Pp 147.Pp 148The 149.Fl l 150flag causes 151.Nm 152to print the current dump device or _PATH_DEVNULL ("/dev/null") if no device is 153configured. 154.Pp 155The 156.Fl v 157flag causes 158.Nm 159to be verbose about its activity. 160.Sh IMPLEMENTATION NOTES 161Since a 162.Xr panic 9 163condition may occur in a situation 164where the kernel cannot trust its internal representation 165of the state of any given file system, 166one of the system swap devices, 167and 168.Em not 169a device containing a file system, 170should be used as the dump device. 171.Pp 172The 173.Nm 174utility operates by opening 175.Ar special_file 176and making a 177.Dv DIOCSKERNELDUMP 178.Xr ioctl 2 179request on it to save kernel crash dumps. 180If 181.Ar special_file 182is the text string: 183.Dq Li off , 184.Nm 185performs a 186.Dv DIOCSKERNELDUMP 187.Xr ioctl 2 188on 189.Pa /dev/null 190and thus instructs the kernel not to save crash dumps. 191.Pp 192Since 193.Nm 194cannot be used during kernel initialization, the 195.Va dumpdev 196variable of 197.Xr loader 8 198must be used to enable dumps for system panics which occur 199during kernel initialization. 200.Sh FILES 201.Bl -tag -width "/dev/{ada,da}?s?b" -compact 202.It Pa /dev/{ada,da}?s?b 203standard swap areas 204.It Pa /etc/rc.conf 205boot-time system configuration 206.El 207.Sh EXAMPLES 208In order to generate an RSA private key a user can use the 209.Xr genrsa 1 210tool: 211.Pp 212.Dl # openssl genrsa -out private.pem 4096 213.Pp 214A public key can be extracted from the private key using the 215.Xr rsa 1 216tool: 217.Pp 218.Dl # openssl rsa -in private.pem -out public.pem -pubout 219.Pp 220Once the RSA keys are created the private key should be moved to a safe place. 221Now 222.Pa public.pem 223can be used by 224.Nm 225to configure encrypted kernel crash dumps: 226.Pp 227.Dl # dumpon -k public.pem /dev/ada0s1b 228.Pp 229It is recommended to test if the kernel saves encrypted crash dumps using the 230current configuration. 231The easiest way to do that is to cause a kernel panic using the 232.Xr ddb 4 233debugger: 234.Pp 235.Dl # sysctl debug.kdb.panic=1 236.Pp 237In the debugger the following commands should be typed to write a core dump and 238reboot: 239.Pp 240.Dl db> call doadump(0) 241.Dl db> reset 242.Pp 243After reboot 244.Xr savecore 8 245should be able to save the core dump in the core directory which is 246.Pa /var/crash 247by default: 248.Pp 249.Dl # savecore /var/crash /dev/ada0s1b 250.Pp 251Three files should be created in the core directory: 252.Pa info.# , 253.Pa key.# 254and 255.Pa vmcore_encrypted.# 256where 257.Dq # 258is the number of the last core dump saved by 259.Xr savecore 8 . 260The 261.Pa vmcore_encrypted.# 262can be decrypted using the 263.Xr decryptcore 8 264utility: 265.Pp 266.Dl # decryptcore -p private.pem -k key.# -e vmcore_encrypted.# -c vmcore.# 267.Pp 268or shorter: 269.Pp 270.Dl # decryptcore -p private.pem -n # 271.Pp 272The 273.Pa vmcore.# 274can be now examined using 275.Xr kgdb 1 : 276.Pp 277.Dl # kgdb /usr/obj/sys/GENERIC/kernel.debug vmcore.# 278.Pp 279or shorter: 280.Pp 281.Dl # kgdb -n # /usr/obj/sys/GENERIC/kernel.debug 282.Pp 283The core was decrypted properly if 284.Xr kgdb 1 285does not print any errors. 286.Sh SEE ALSO 287.Xr gzip 1 , 288.Xr kgdb 1 , 289.Xr zstd 1 , 290.Xr ddb 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.Sh BUGS 307Because the file system layer is already dead by the time a crash dump 308is taken, it is not possible to send crash dumps directly to a file. 309.Pp 310It is currently not possible to configure both compression and encryption. 311The encrypted dump format assumes that the kernel dump size is a multiple 312of the cipher block size, which may not be true when the dump is compressed. 313