123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452 |
- .\" Copyright (c) 1980, 1991, 1993
- .\" The Regents of the University of California. All rights reserved.
- .\"
- .\" Redistribution and use in source and binary forms, with or without
- .\" modification, are permitted provided that the following conditions
- .\" are met:
- .\" 1. Redistributions of source code must retain the above copyright
- .\" notice, this list of conditions and the following disclaimer.
- .\" 2. Redistributions in binary form must reproduce the above copyright
- .\" notice, this list of conditions and the following disclaimer in the
- .\" documentation and/or other materials provided with the distribution.
- .\" 3. Neither the name of the University nor the names of its contributors
- .\" may be used to endorse or promote products derived from this software
- .\" without specific prior written permission.
- .\"
- .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
- .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
- .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
- .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
- .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
- .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
- .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
- .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
- .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
- .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
- .\" SUCH DAMAGE.
- .\"
- .Dd April 23, 2020
- .Dt DUMPON 8
- .Os
- .Sh NAME
- .Nm dumpon
- .Nd "specify a device for crash dumps"
- .Sh SYNOPSIS
- .Nm
- .Op Fl i Ar index
- .Op Fl r
- .Op Fl v
- .Op Fl C Ar cipher
- .Op Fl k Ar pubkey
- .Op Fl Z
- .Op Fl z
- .Ar device
- .Nm
- .Op Fl i Ar index
- .Op Fl r
- .Op Fl v
- .Op Fl C Ar cipher
- .Op Fl k Ar pubkey
- .Op Fl Z
- .Op Fl z
- .Op Fl g Ar gateway
- .Fl s Ar server
- .Fl c Ar client
- .Ar iface
- .Nm
- .Op Fl v
- .Cm off
- .Nm
- .Op Fl v
- .Fl l
- .Sh DESCRIPTION
- The
- .Nm
- utility is used to configure where the kernel can save a crash dump in the case
- of a panic.
- .Pp
- System administrators should typically configure
- .Nm
- in a persistent fashion using the
- .Xr rc.conf 5
- variables
- .Va dumpdev
- and
- .Va dumpon_flags .
- For more information on this usage, see
- .Xr rc.conf 5 .
- .Pp
- Starting in
- .Fx 13.0 ,
- .Nm
- can configure a series of fallback dump devices.
- For example, an administrator may prefer
- .Xr netdump 4
- by default, but if the
- .Xr netdump 4
- service cannot be reached or some other failure occurs, they might choose a
- local disk dump as a second choice option.
- .Ss General options
- .Bl -tag -width _k_pubkey
- .It Fl i Ar index
- Insert the specified dump configuration into the prioritized fallback dump
- device list at the specified index, starting at zero.
- .Pp
- If
- .Fl i
- is not specified, the configured dump device is appended to the prioritized
- list.
- .It Fl r
- Remove the specified dump device configuration or configurations from the
- fallback dump device list rather than inserting or appending it.
- In contrast,
- .Do
- .Nm
- off
- .Dc
- removes all configured devices.
- Conflicts with
- .Fl i .
- .It Fl k Ar pubkey
- Configure encrypted kernel dumps.
- .Pp
- A random, one-time symmetric key is automatically generated for bulk kernel
- dump encryption every time
- .Nm
- is used.
- The provided
- .Ar pubkey
- is used to encrypt a copy of the symmetric key.
- The encrypted dump contents consist of a standard dump header, the
- pubkey-encrypted symmetric key contents, and the symmetric key encrypted core
- dump contents.
- .Pp
- As a result, only someone with the corresponding private key can decrypt the symmetric key.
- The symmetric key is necessary to decrypt the kernel core.
- The goal of the mechanism is to provide confidentiality.
- .Pp
- The
- .Va pubkey
- file should be a PEM-formatted RSA key of at least 2048 bits.
- .It Fl C Ar cipher
- Select the symmetric algorithm used for encrypted kernel crash dump.
- The default is
- .Dq chacha20
- but
- .Dq aes256-cbc
- is also available.
- (AES256-CBC mode does not work in conjunction with compression.)
- .It Fl l
- List the currently configured dump device(s), or /dev/null if no devices are
- configured.
- .It Fl v
- Enable verbose mode.
- .It Fl Z
- Enable compression (Zstandard).
- .It Fl z
- Enable compression (gzip).
- Only one compression method may be enabled at a time, so
- .Fl z
- is incompatible with
- .Fl Z .
- .Pp
- Zstandard provides superior compression ratio and performance.
- .El
- .Ss Netdump
- .Nm
- may also configure the kernel to dump to a remote
- .Xr netdumpd 8
- server.
- (The
- .Xr netdumpd 8
- server is available in ports.)
- .Xr netdump 4
- eliminates the need to reserve space for crash dumps.
- It is especially useful in diskless environments.
- When
- .Nm
- is used to configure netdump, the
- .Ar device
- (or
- .Ar iface )
- parameter should specify a network interface (e.g.,
- .Va igb1 ) .
- The specified NIC must be up (online) to configure netdump.
- .Pp
- .Xr netdump 4
- specific options include:
- .Bl -tag -width _g_gateway
- .It Fl c Ar client
- The local IP address of the
- .Xr netdump 4
- client.
- .It Fl g Ar gateway
- The first-hop router between
- .Ar client
- and
- .Ar server .
- If the
- .Fl g
- option is not specified and the system has a default route, the default
- router is used as the
- .Xr netdump 4
- gateway.
- If the
- .Fl g
- option is not specified and the system does not have a default route,
- .Ar server
- is assumed to be on the same link as
- .Ar client .
- .It Fl s Ar server
- The IP address of the
- .Xr netdumpd 8
- server.
- .El
- .Pp
- All of these options can be specified in the
- .Xr rc.conf 5
- variable
- .Va dumpon_flags .
- .Ss Minidumps
- The default type of kernel crash dump is the mini crash dump.
- Mini crash dumps hold only memory pages in use by the kernel.
- Alternatively, full memory dumps can be enabled by setting the
- .Va debug.minidump
- .Xr sysctl 8
- variable to 0.
- .Ss Full dumps
- For systems using full memory dumps, the size of the specified dump
- device must be at least the size of physical memory.
- Even though an additional 64 kB header is added to the dump, the BIOS for a
- platform typically holds back some memory, so it is not usually
- necessary to size the dump device larger than the actual amount of RAM
- available in the machine.
- Also, when using full memory dumps, the
- .Nm
- utility will refuse to enable a dump device which is smaller than the
- total amount of physical memory as reported by the
- .Va hw.physmem
- .Xr sysctl 8
- variable.
- .Sh IMPLEMENTATION NOTES
- Because the file system layer is already dead by the time a crash dump
- is taken, it is not possible to send crash dumps directly to a file.
- .Pp
- The
- .Xr loader 8
- variable
- .Va dumpdev
- may be used to enable early kernel core dumps for system panics which occur
- before userspace starts.
- .Sh EXAMPLES
- In order to generate an RSA private key, a user can use the
- .Xr genrsa 1
- tool:
- .Pp
- .Dl # openssl genrsa -out private.pem 4096
- .Pp
- A public key can be extracted from the private key using the
- .Xr rsa 1
- tool:
- .Pp
- .Dl # openssl rsa -in private.pem -out public.pem -pubout
- .Pp
- Once the RSA keys are created in a safe place, the public key may be moved to
- the untrusted netdump client machine.
- Now
- .Pa public.pem
- can be used by
- .Nm
- to configure encrypted kernel crash dumps:
- .Pp
- .Dl # dumpon -k public.pem /dev/ada0s1b
- .Pp
- It is recommended to test if the kernel saves encrypted crash dumps using the
- current configuration.
- The easiest way to do that is to cause a kernel panic using the
- .Xr ddb 4
- debugger:
- .Pp
- .Dl # sysctl debug.kdb.panic=1
- .Pp
- In the debugger the following commands should be typed to write a core dump and
- reboot:
- .Pp
- .Dl db> dump
- .Dl db> reset
- .Pp
- After reboot
- .Xr savecore 8
- should be able to save the core dump in the
- .Va Dq dumpdir
- directory, which is
- .Pa /var/crash
- by default:
- .Pp
- .Dl # savecore /dev/ada0s1b
- .Pp
- Three files should be created in the core directory:
- .Pa info.# ,
- .Pa key.#
- and
- .Pa vmcore_encrypted.#
- (where
- .Dq #
- is the number of the last core dump saved by
- .Xr savecore 8 ) .
- The
- .Pa vmcore_encrypted.#
- can be decrypted using the
- .Xr decryptcore 8
- utility:
- .Pp
- .Dl # decryptcore -p private.pem -k key.# -e vmcore_encrypted.# -c vmcore.#
- .Pp
- or shorter:
- .Pp
- .Dl # decryptcore -p private.pem -n #
- .Pp
- The
- .Pa vmcore.#
- can be now examined using
- .Xr kgdb 1 Pq Pa ports/devel/gdb :
- .Pp
- .Dl # kgdb /boot/kernel/kernel vmcore.#
- .Pp
- or shorter:
- .Pp
- .Dl # kgdb -n #
- .Pp
- The core was decrypted properly if
- .Xr kgdb 1 Pq Pa ports/devel/gdb
- does not print any errors.
- Note that the live kernel might be at a different path
- which can be examined by looking at the
- .Va kern.bootfile
- .Xr sysctl 8 .
- .Pp
- The
- .Nm
- .Xr rc 8
- script runs early during boot, typically before networking is configured.
- This makes it unsuitable for configuring
- .Xr netdump 4
- when the client address is dynamic.
- To configure
- .Xr netdump 4
- when
- .Xr dhclient 8
- binds to a server,
- .Xr dhclient-script 8
- can be used to run
- .Xr dumpon 8 .
- For example, to automatically configure
- .Xr netdump 4
- on the vtnet0 interface, add the following to
- .Pa /etc/dhclient-exit-hooks .
- .Bd -literal
- case $reason in
- BOUND|REBIND|REBOOT|RENEW)
- if [ "$interface" != vtnet0 ] || [ -n "$old_ip_address" -a \\
- "$old_ip_address" = "$new_ip_address" ]; then
- break
- fi
- if [ -n "$new_routers" ]; then
- # Take the first router in the list.
- gateway_flag="-g ${new_routers%% *}"
- fi
- # Configure as the highest-priority dump device.
- dumpon -i 0 -c $new_ip_address -s $server $gateway_flag vtnet0
- ;;
- esac
- .Ed
- .Pp
- Be sure to fill in the server IP address and change the interface name if
- needed.
- .Sh SEE ALSO
- .Xr gzip 1 ,
- .Xr kgdb 1 Pq Pa ports/devel/gdb ,
- .Xr zstd 1 ,
- .Xr ddb 4 ,
- .Xr netdump 4 ,
- .Xr fstab 5 ,
- .Xr rc.conf 5 ,
- .Xr config 8 ,
- .Xr decryptcore 8 ,
- .Xr init 8 ,
- .Xr loader 8 ,
- .Xr rc 8 ,
- .Xr savecore 8 ,
- .Xr swapon 8 ,
- .Xr panic 9
- .Sh HISTORY
- The
- .Nm
- utility appeared in
- .Fx 2.0.5 .
- .Pp
- Support for encrypted kernel core dumps and netdump was added in
- .Fx 12.0 .
- .Sh AUTHORS
- The
- .Nm
- manual page was written by
- .An Mark Johnston Aq Mt markj@FreeBSD.org ,
- .An Conrad Meyer Aq Mt cem@FreeBSD.org ,
- .An Konrad Witaszczyk Aq Mt def@FreeBSD.org ,
- and countless others.
- .Sh CAVEATS
- To configure encrypted kernel core dumps, the running kernel must have been
- compiled with the
- .Dv EKCD
- option.
- .Pp
- Netdump does not automatically update the configured
- .Ar gateway
- if routing topology changes.
- .Pp
- The size of a compressed dump or a minidump is not a fixed function of RAM
- size.
- Therefore, when at least one of these options is enabled, the
- .Nm
- utility cannot verify that the
- .Ar device
- has sufficient space for a dump.
- .Nm
- is also unable to verify that a configured
- .Xr netdumpd 8
- server has sufficient space for a dump.
- .Pp
- .Fl Z
- requires a kernel compiled with the
- .Dv ZSTDIO
- kernel option.
- Similarly,
- .Fl z
- requires the
- .Dv GZIO
- option.
- .Sh BUGS
- Netdump only supports IPv4 at this time.
- .Sh SECURITY CONSIDERATIONS
- The current encrypted kernel core dump scheme does not provide integrity nor
- authentication.
- That is, the recipient of an encrypted kernel core dump cannot know if they
- received an intact core dump, nor can they verify the provenance of the dump.
- .Pp
- RSA keys smaller than 1024 bits are practical to factor and therefore weak.
- Even 1024 bit keys may not be large enough to ensure privacy for many
- years, so NIST recommends a minimum of 2048 bit RSA keys.
- As a seatbelt,
- .Nm
- prevents users from configuring encrypted kernel dumps with extremely weak RSA
- keys.
- If you do not care for cryptographic privacy guarantees, just use
- .Nm
- without specifying a
- .Fl k Ar pubkey
- option.
- .Pp
- This process is sandboxed using
- .Xr capsicum 4 .
|