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