Changeset View
Changeset View
Standalone View
Standalone View
head/sbin/dumpon/dumpon.8
Show First 20 Lines • Show All 53 Lines • ▼ Show 20 Lines | |||||
.Op Fl v | .Op Fl v | ||||
.Cm off | .Cm off | ||||
.Nm | .Nm | ||||
.Op Fl v | .Op Fl v | ||||
.Fl l | .Fl l | ||||
.Sh DESCRIPTION | .Sh DESCRIPTION | ||||
The | The | ||||
.Nm | .Nm | ||||
utility is used to specify a device where the kernel can save a crash | utility is used to configure where the kernel can save a crash dump in the case | ||||
dump in the case of a panic. | of a panic. | ||||
.Pp | .Pp | ||||
Calls to | System administrators should typically configure | ||||
.Nm | .Nm | ||||
normally occur from the system multi-user initialization file | in a persistent fashion using the | ||||
.Pa /etc/rc , | .Xr rc.conf 5 | ||||
controlled by the | variables | ||||
.Dq dumpdev | .Va dumpdev | ||||
and | and | ||||
.Dq dumpon_flags | .Va dumpon_flags . | ||||
variables in the boot time configuration file | For more information on this usage, see | ||||
.Pa /etc/rc.conf . | .Xr rc.conf 5 . | ||||
.Ss General options | |||||
.Bl -tag -width _k_pubkey | |||||
.It Fl k Ar pubkey | |||||
Configure encrypted kernel dumps. | |||||
.Pp | .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. | The default type of kernel crash dump is the mini crash dump. | ||||
Mini crash dumps hold only memory pages in use by the kernel. | Mini crash dumps hold only memory pages in use by the kernel. | ||||
Alternatively, full memory dumps can be enabled by setting the | Alternatively, full memory dumps can be enabled by setting the | ||||
.Va debug.minidump | .Va debug.minidump | ||||
.Xr sysctl 8 | .Xr sysctl 8 | ||||
variable to 0. | variable to 0. | ||||
.Pp | .Ss Full dumps | ||||
For systems using full memory dumps, the size of the specified dump | For systems using full memory dumps, the size of the specified dump | ||||
device must be at least the size of physical memory. | 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 | 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 | platform typically holds back some memory, so it is not usually | ||||
necessary to size the dump device larger than the actual amount of RAM | necessary to size the dump device larger than the actual amount of RAM | ||||
available in the machine. | available in the machine. | ||||
Also, when using full memory dumps, the | Also, when using full memory dumps, the | ||||
.Nm | .Nm | ||||
utility will refuse to enable a dump device which is smaller than the | utility will refuse to enable a dump device which is smaller than the | ||||
total amount of physical memory as reported by the | total amount of physical memory as reported by the | ||||
.Va hw.physmem | .Va hw.physmem | ||||
.Xr sysctl 8 | .Xr sysctl 8 | ||||
variable. | 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 | .Sh IMPLEMENTATION NOTES | ||||
Since a | Because the file system layer is already dead by the time a crash dump | ||||
.Xr panic 9 | is taken, it is not possible to send crash dumps directly to a file. | ||||
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. | |||||
.Pp | .Pp | ||||
The | 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 | .Xr loader 8 | ||||
must be used to enable dumps for system panics which occur | variable | ||||
during kernel initialization. | .Va dumpdev | ||||
.Sh FILES | may be used to enable early kernel core dumps for system panics which occur | ||||
.Bl -tag -width "/dev/{ada,da}?s?b" -compact | before userspace starts. | ||||
.It Pa /dev/{ada,da}?s?b | |||||
standard swap areas | |||||
.It Pa /etc/rc.conf | |||||
boot-time system configuration | |||||
.El | |||||
.Sh EXAMPLES | .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 | .Xr genrsa 1 | ||||
tool: | tool: | ||||
.Pp | .Pp | ||||
.Dl # openssl genrsa -out private.pem 4096 | .Dl # openssl genrsa -out private.pem 4096 | ||||
.Pp | .Pp | ||||
A public key can be extracted from the private key using the | A public key can be extracted from the private key using the | ||||
.Xr rsa 1 | .Xr rsa 1 | ||||
tool: | tool: | ||||
.Pp | .Pp | ||||
.Dl # openssl rsa -in private.pem -out public.pem -pubout | .Dl # openssl rsa -in private.pem -out public.pem -pubout | ||||
.Pp | .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 | Now | ||||
.Pa public.pem | .Pa public.pem | ||||
can be used by | can be used by | ||||
.Nm | .Nm | ||||
to configure encrypted kernel crash dumps: | to configure encrypted kernel crash dumps: | ||||
.Pp | .Pp | ||||
.Dl # dumpon -k public.pem /dev/ada0s1b | .Dl # dumpon -k public.pem /dev/ada0s1b | ||||
.Pp | .Pp | ||||
It is recommended to test if the kernel saves encrypted crash dumps using the | It is recommended to test if the kernel saves encrypted crash dumps using the | ||||
current configuration. | current configuration. | ||||
The easiest way to do that is to cause a kernel panic using the | The easiest way to do that is to cause a kernel panic using the | ||||
.Xr ddb 4 | .Xr ddb 4 | ||||
debugger: | debugger: | ||||
.Pp | .Pp | ||||
.Dl # sysctl debug.kdb.panic=1 | .Dl # sysctl debug.kdb.panic=1 | ||||
.Pp | .Pp | ||||
In the debugger the following commands should be typed to write a core dump and | In the debugger the following commands should be typed to write a core dump and | ||||
reboot: | reboot: | ||||
.Pp | .Pp | ||||
.Dl db> call doadump(0) | .Dl db> call doadump(0) | ||||
.Dl db> reset | .Dl db> reset | ||||
.Pp | .Pp | ||||
After reboot | After reboot | ||||
.Xr savecore 8 | .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 | .Pa /var/crash | ||||
by default: | by default: | ||||
.Pp | .Pp | ||||
.Dl # savecore /var/crash /dev/ada0s1b | .Dl # savecore /dev/ada0s1b | ||||
.Pp | .Pp | ||||
Three files should be created in the core directory: | Three files should be created in the core directory: | ||||
.Pa info.# , | .Pa info.# , | ||||
.Pa key.# | .Pa key.# | ||||
and | and | ||||
.Pa vmcore_encrypted.# | .Pa vmcore_encrypted.# | ||||
where | (where | ||||
.Dq # | .Dq # | ||||
is the number of the last core dump saved by | is the number of the last core dump saved by | ||||
.Xr savecore 8 . | .Xr savecore 8 ) . | ||||
The | The | ||||
.Pa vmcore_encrypted.# | .Pa vmcore_encrypted.# | ||||
can be decrypted using the | can be decrypted using the | ||||
.Xr decryptcore 8 | .Xr decryptcore 8 | ||||
utility: | utility: | ||||
.Pp | .Pp | ||||
.Dl # decryptcore -p private.pem -k key.# -e vmcore_encrypted.# -c vmcore.# | .Dl # decryptcore -p private.pem -k key.# -e vmcore_encrypted.# -c vmcore.# | ||||
.Pp | .Pp | ||||
Show All 11 Lines | |||||
or shorter: | or shorter: | ||||
.Pp | .Pp | ||||
.Dl # kgdb -n # | .Dl # kgdb -n # | ||||
.Pp | .Pp | ||||
The core was decrypted properly if | The core was decrypted properly if | ||||
.Xr kgdb 1 | .Xr kgdb 1 | ||||
does not print any errors. | does not print any errors. | ||||
Note that the live kernel might be at a different path | 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 | .Sh SEE ALSO | ||||
.Xr gzip 1 , | .Xr gzip 1 , | ||||
.Xr kgdb 1 , | .Xr kgdb 1 , | ||||
.Xr zstd 1 , | .Xr zstd 1 , | ||||
.Xr ddb 4 , | .Xr ddb 4 , | ||||
.Xr netdump 4 , | |||||
.Xr fstab 5 , | .Xr fstab 5 , | ||||
.Xr rc.conf 5 , | .Xr rc.conf 5 , | ||||
.Xr config 8 , | .Xr config 8 , | ||||
.Xr decryptcore 8 , | .Xr decryptcore 8 , | ||||
.Xr init 8 , | .Xr init 8 , | ||||
.Xr loader 8 , | .Xr loader 8 , | ||||
.Xr rc 8 , | .Xr rc 8 , | ||||
.Xr savecore 8 , | .Xr savecore 8 , | ||||
.Xr swapon 8 , | .Xr swapon 8 , | ||||
.Xr panic 9 | .Xr panic 9 | ||||
.Sh HISTORY | .Sh HISTORY | ||||
The | The | ||||
.Nm | .Nm | ||||
utility appeared in | utility appeared in | ||||
.Fx 2.0.5 . | .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 | .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 | |||||
It is currently not possible to configure both compression and encryption. | It is currently not possible to configure both compression and encryption. | ||||
The encrypted dump format assumes that the kernel dump size is a multiple | 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. | 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 | .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. | 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 | 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. | years, so NIST recommends a minimum of 2048 bit RSA keys. | ||||
As a seatbelt, | As a seatbelt, | ||||
.Nm | .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 | If you do not care for cryptographic privacy guarantees, just use | ||||
.Nm | .Nm | ||||
without specifying a | without specifying a | ||||
.Fl k Ar pubkey | .Fl k Ar pubkey | ||||
option. | option. | ||||
.Pp | |||||
This process is sandboxed using | |||||
.Xr capsicum 4 . |