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