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