sbin/dumpon/dumpon.8

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