Author: cem Date: Fri Oct 26 20:03:59 2018 New Revision: 339785 URL: https://svnweb.freebsd.org/changeset/base/339785
Log: dumpon.8: Significantly revamp page Start with a short summary and cover the options in a standard list style. Organize sections by common focus and prioritize more useful information closer to the top. Flesh out authors, history, caveats, and security considerations sections. Reviewed by: markj, eadler (previous version) Differential Revision: https://reviews.freebsd.org/D17679 Modified: head/sbin/dumpon/dumpon.8 Modified: head/sbin/dumpon/dumpon.8 ============================================================================== --- head/sbin/dumpon/dumpon.8 Fri Oct 26 19:53:59 2018 (r339784) +++ head/sbin/dumpon/dumpon.8 Fri Oct 26 20:03:59 2018 (r339785) @@ -59,27 +59,120 @@ .Sh DESCRIPTION The .Nm -utility is used to specify a device where the kernel can save a crash -dump in the case of a panic. +utility is used to configure where the kernel can save a crash dump in the case +of a panic. .Pp -Calls to +System administrators should typically configure .Nm -normally occur from the system multi-user initialization file -.Pa /etc/rc , -controlled by the -.Dq dumpdev +in a persistent fashion using the +.Xr rc.conf 5 +variables +.Va dumpdev and -.Dq dumpon_flags -variables in the boot time configuration file -.Pa /etc/rc.conf . +.Va dumpon_flags . +For more information on this usage, see +.Xr rc.conf 5 . +.Ss General options +.Bl -tag -width _k_pubkey +.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 1024 bits. +.It Fl l +List the currently configured dump device, or /dev/null if no device is +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 +Optional. +If not specified, it is assumed that the +.Ar server +is on the same link as the +.Ar client . +.Pp +If specified, +.Ar gateway +is the address of the first-hop router between the +.Ar client +and the +.Ar server . +The special value +.Dv Dq default +indicates that the currently configured system default route should be used. +.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. -.Pp +.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 @@ -93,155 +186,18 @@ total amount of physical memory as reported by the .Va hw.physmem .Xr sysctl 8 variable. -.Pp -.Nm -is used to configure a local storage device as the dump device. -With additional parameters, the kernel can instead be configured to -transmit a dump to a remote server using -.Xr netdump 4 . -This eliminates the need to reserve space for saving crash dumps and -is especially useful in diskless environments. -The -.Xr netdump 4 -server address is specified with -.Fl s Ar server , -and the local address is specified with -.Fl c Ar client . -The -.Fl g Ar gateway -parameter may be used to specify a first-hop router to the server, -or to specify that the currently configured default gateway is to -be used. -Note that the -.Xr netdump 4 -configuration is not automatically updated if any network configuration -(e.g., the default route) changes after the -.Nm -invocation. -The name of the interface to be used must be specified as -.Ar iface . -The interface must be up in order to configure -.Xr netdump 4 . -.Pp -The -.Fl k Ar pubkey -flag causes -.Nm -to generate a one-time key for kernel crash dump encryption. -The key will be replaced by a new one when the -.Nm -utility is run again. -The key is encrypted using -.Ar pubkey . -This process is sandboxed using -.Xr capsicum 4 . -Both plain and encrypted keys are sent to the kernel using -.Dv DIOCSKERNELDUMP -.Xr ioctl 2 . -A user can specify the -.Ar pubkey -in the -.Dq dumpon_flags -variable defined in -.Pa /etc/rc.conf -for use with the -.Pa /etc/rc.d/dumpon -.Xr rc 8 -script. -This flag requires a kernel compiled with the -.Dv EKCD -kernel option. -.Pp -The -.Fl z -and -.Fl Z -options configure the kernel to compress the dump before writing it to -the dump device. -This reduces the amount of space required for the dump and accelerates -recovery with -.Xr savecore 8 -since less data needs to be copied from the dump device. -When compression is enabled, the -.Nm -utility will not verify that the dump device is sufficiently large for a full -dump. -The -.Fl z -and -.Fl Z -options cause the dump to be written in -.Xr gzip 1 -and -.Xr zstd 1 -format, respectively. -These flags require a kernel compiled with the -.Dv GZIO -or -.Dv ZSTDIO -kernel options. -.Pp -The -.Fl l -flag causes -.Nm -to print the current dump device or _PATH_DEVNULL ("/dev/null") if no device is -configured. -.Pp -The -.Fl v -flag causes -.Nm -to be verbose about its activity. .Sh IMPLEMENTATION NOTES -Since a -.Xr panic 9 -condition may occur in a situation -where the kernel cannot trust its internal representation -of the state of any given file system, -one of the system swap devices, -and -.Em not -a device containing a file system, -should be used as the dump device. +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 -.Nm -utility operates by opening -.Ar device -and making a -.Dv DIOCSKERNELDUMP -.Xr ioctl 2 -request on it to save kernel crash dumps. -If -.Ar device -is the text string: -.Dq Li off , -.Nm -performs a -.Dv DIOCSKERNELDUMP -.Xr ioctl 2 -on -.Pa /dev/null -and thus instructs the kernel not to save crash dumps. -.Pp -Since -.Nm -cannot be used during kernel initialization, the -.Va dumpdev -variable of .Xr loader 8 -must be used to enable dumps for system panics which occur -during kernel initialization. -.Sh FILES -.Bl -tag -width "/dev/{ada,da}?s?b" -compact -.It Pa /dev/{ada,da}?s?b -standard swap areas -.It Pa /etc/rc.conf -boot-time system configuration -.El +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 +In order to generate an RSA private key, a user can use the .Xr genrsa 1 tool: .Pp @@ -253,7 +209,8 @@ tool: .Pp .Dl # openssl rsa -in private.pem -out public.pem -pubout .Pp -Once the RSA keys are created the private key should be moved to a safe place. +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 @@ -278,21 +235,23 @@ reboot: .Pp After reboot .Xr savecore 8 -should be able to save the core dump in the core directory which is +should be able to save the core dump in the +.Va Dq dumpdir +directory, which is .Pa /var/crash by default: .Pp -.Dl # savecore /var/crash /dev/ada0s1b +.Dl # savecore /dev/ada0s1b .Pp Three files should be created in the core directory: .Pa info.# , .Pa key.# and .Pa vmcore_encrypted.# -where +(where .Dq # is the number of the last core dump saved by -.Xr savecore 8 . +.Xr savecore 8 ) . The .Pa vmcore_encrypted.# can be decrypted using the @@ -320,12 +279,15 @@ The core was decrypted properly if .Xr kgdb 1 does not print any errors. Note that the live kernel might be at a different path -which can be examined by looking at the kern.bootfile sysctl. +which can be examined by looking at the +.Va kern.bootfile +.Xr sysctl 8 . .Sh SEE ALSO .Xr gzip 1 , .Xr kgdb 1 , .Xr zstd 1 , .Xr ddb 4 , +.Xr netdump 4 , .Xr fstab 5 , .Xr rc.conf 5 , .Xr config 8 , @@ -341,22 +303,72 @@ The .Nm utility appeared in .Fx 2.0.5 . -.Sh BUGS -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 +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 ma...@freebsd.org , +.An Conrad Meyer Aq Mt c...@freebsd.org , +.An Konrad Witaszczyk Aq Mt d...@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 It is currently not possible to configure both compression and encryption. The encrypted dump format assumes that the kernel dump size is a multiple of the cipher block size, which may not be true when the dump is compressed. +.Pp +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 weak RSA keys. +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 . _______________________________________________ svn-src-head@freebsd.org mailing list https://lists.freebsd.org/mailman/listinfo/svn-src-head To unsubscribe, send any mail to "svn-src-head-unsubscr...@freebsd.org"
