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
This commit is contained in:
cem
parent
798d375cc0
commit
e2f06585c6
@ -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 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.
|
||||
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 .
|
||||
|
||||
Loading…
Reference in New Issue
Block a user