Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
DUMPON(8)		FreeBSD	System Manager's Manual		     DUMPON(8)

NAME
     dumpon -- specify a device	for crash dumps

SYNOPSIS
     dumpon [-v] [-k pubkey] [-Z] [-z] device
     dumpon [-v] [-k pubkey] [-Z] [-z] [-g gateway] -s server -c client	iface
     dumpon [-v] off
     dumpon [-v] -l

DESCRIPTION
     The dumpon	utility	is used	to configure where the kernel can save a crash
     dump in the case of a panic.

     System administrators should typically configure dumpon in	a persistent
     fashion using the rc.conf(5) variables dumpdev and	dumpon_flags.  For
     more information on this usage, see rc.conf(5).

   General options
     -k	pubkey	Configure encrypted kernel dumps.

		A random, one-time symmetric key is automatically generated
		for bulk kernel	dump encryption	every time dumpon is used.
		The provided 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.

		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.

		The pubkey file	should be a PEM-formatted RSA key of at	least
		1024 bits.

     -l		List the currently configured dump device, or /dev/null	if no
		device is configured.

     -v		Enable verbose mode.

     -Z		Enable compression (Zstandard).

     -z		Enable compression (gzip).  Only one compression method	may be
		enabled	at a time, so -z is incompatible with -Z.

		Zstandard provides superior compression	ratio and performance.

   Netdump
     dumpon may	also configure the kernel to dump to a remote netdumpd(8)
     server.  (The netdumpd(8) server is available in ports.)  netdump(4)
     eliminates	the need to reserve space for crash dumps.  It is especially
     useful in diskless	environments.  When dumpon is used to configure	net-
     dump, the device (or iface) parameter should specify a network interface
     (e.g., igb1).  The	specified NIC must be up (online) to configure net-
     dump.

     netdump(4)	specific options include:

     -c	client	 The local IP address of the netdump(4)	client.

     -g	gateway	 The first-hop router between client and server.  If the -g
		 option	is not specified and the system	has a default route,
		 the default router is used as the netdump(4) gateway.	If the
		 -g option is not specified and	the system does	not have a
		 default route,	server is assumed to be	on the same link as
		 client.

     -s	server	 The IP	address	of the netdumpd(8) server.

     All of these options can be specified in the rc.conf(5) variable
     dumpon_flags.

   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	debug.minidump sysctl(8) vari-
     able to 0.

   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 dumpon utility will
     refuse to enable a	dump device which is smaller than the total amount of
     physical memory as	reported by the	hw.physmem sysctl(8) variable.

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.

     The loader(8) variable dumpdev may	be used	to enable early	kernel core
     dumps for system panics which occur before	userspace starts.

EXAMPLES
     In	order to generate an RSA private key, a	user can use the genrsa(1)
     tool:

	   # openssl genrsa -out private.pem 4096

     A public key can be extracted from	the private key	using the rsa(1) tool:

	   # openssl rsa -in private.pem -out public.pem -pubout

     Once the RSA keys are created in a	safe place, the	public key may be
     moved to the untrusted netdump client machine.  Now public.pem can	be
     used by dumpon to configure encrypted kernel crash	dumps:

	   # dumpon -k public.pem /dev/ada0s1b

     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 ker-
     nel panic using the ddb(4)	debugger:

	   # sysctl debug.kdb.panic=1

     In	the debugger the following commands should be typed to write a core
     dump and reboot:

	   db> call doadump(0)
	   db> reset

     After reboot savecore(8) should be	able to	save the core dump in the
     ``dumpdir'' directory, which is /var/crash	by default:

	   # savecore /dev/ada0s1b

     Three files should	be created in the core directory: info.#, key.#	and
     vmcore_encrypted.#	(where ``#'' is	the number of the last core dump saved
     by	savecore(8)).  The vmcore_encrypted.# can be decrypted using the
     decryptcore(8) utility:

	   # decryptcore -p private.pem	-k key.# -e vmcore_encrypted.# -c
	   vmcore.#

     or	shorter:

	   # decryptcore -p private.pem	-n #

     The vmcore.# can be now examined using kgdb(1):

	   # kgdb /boot/kernel/kernel vmcore.#

     or	shorter:

	   # kgdb -n #

     The core was decrypted properly if	kgdb(1)	does not print any errors.
     Note that the live	kernel might be	at a different path which can be exam-
     ined by looking at	the kern.bootfile sysctl(8).

SEE ALSO
     gzip(1), kgdb(1), zstd(1),	ddb(4),	netdump(4), fstab(5), rc.conf(5),
     config(8),	decryptcore(8),	init(8), loader(8), rc(8), savecore(8),
     swapon(8),	panic(9)

HISTORY
     The dumpon	utility	appeared in FreeBSD 2.0.5.

     Support for encrypted kernel core dumps and netdump was added in
     FreeBSD 12.0.

AUTHORS
     The dumpon	manual page was	written	by Mark	Johnston <markj@FreeBSD.org>,
     Conrad Meyer <cem@FreeBSD.org>,
     Konrad Witaszczyk <def@FreeBSD.org>, and countless	others.

CAVEATS
     To	configure encrypted kernel core	dumps, the running kernel must have
     been compiled with	the EKCD option.

     Netdump does not automatically update the configured gateway if routing
     topology changes.

     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
     dumpon utility cannot verify that the device has sufficient space for a
     dump.  dumpon is also unable to verify that a configured netdumpd(8)
     server has	sufficient space for a dump.

     -Z	requires a kernel compiled with	the ZSTDIO kernel option.  Similarly,
     -z	requires the GZIO option.

BUGS
     It	is currently not possible to configure both compression	and encryp-
     tion.  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.

FreeBSD	Ports 11.2	       November	17, 2018	    FreeBSD Ports 11.2

NAME | SYNOPSIS | DESCRIPTION | IMPLEMENTATION NOTES | EXAMPLES | SEE ALSO | HISTORY | AUTHORS | CAVEATS | BUGS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=dumpon&sektion=8&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help