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