351 lines
8.5 KiB
Groff
351 lines
8.5 KiB
Groff
.\" 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.
|
|
.\"
|
|
.\" From: @(#)swapon.8 8.1 (Berkeley) 6/5/93
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd June 13, 2018
|
|
.Dt DUMPON 8
|
|
.Os
|
|
.Sh NAME
|
|
.Nm dumpon
|
|
.Nd "specify a device for crash dumps"
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Op Fl v
|
|
.Op Fl k Ar pubkey
|
|
.Op Fl Z
|
|
.Op Fl z
|
|
.Ar device
|
|
.Nm
|
|
.Op Fl v
|
|
.Op Fl k Ar pubkey
|
|
.Op Fl Z
|
|
.Op Fl z
|
|
.Op Fl g Ar gateway | Li default
|
|
.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 specify a device where the kernel can save a crash
|
|
dump in the case of a panic.
|
|
.Pp
|
|
Calls to
|
|
.Nm
|
|
normally occur from the system multi-user initialization file
|
|
.Pa /etc/rc ,
|
|
controlled by the
|
|
.Dq dumpdev
|
|
and
|
|
.Dq dumpon_flags
|
|
variables in the boot time configuration file
|
|
.Pa /etc/rc.conf .
|
|
.Pp
|
|
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
|
|
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.
|
|
.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.
|
|
.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
|
|
.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 the private key should be moved to a safe place.
|
|
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> call doadump(0)
|
|
.Dl db> reset
|
|
.Pp
|
|
After reboot
|
|
.Xr savecore 8
|
|
should be able to save the core dump in the core directory which is
|
|
.Pa /var/crash
|
|
by default:
|
|
.Pp
|
|
.Dl # savecore /var/crash /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 :
|
|
.Pp
|
|
.Dl # kgdb /boot/kernel/kernel vmcore.#
|
|
.Pp
|
|
or shorter:
|
|
.Pp
|
|
.Dl # kgdb -n #
|
|
.Pp
|
|
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.
|
|
.Sh SEE ALSO
|
|
.Xr gzip 1 ,
|
|
.Xr kgdb 1 ,
|
|
.Xr zstd 1 ,
|
|
.Xr ddb 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 .
|
|
.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
|
|
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.
|