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