xref: /freebsd/sbin/dumpon/dumpon.8 (revision c66ec88fed842fbaad62c30d510644ceb7bd2d71)
1.\" Copyright (c) 1980, 1991, 1993
2.\"	The Regents of the University of California.  All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\"    notice, this list of conditions and the following disclaimer.
9.\" 2. Redistributions in binary form must reproduce the above copyright
10.\"    notice, this list of conditions and the following disclaimer in the
11.\"    documentation and/or other materials provided with the distribution.
12.\" 3. Neither the name of the University nor the names of its contributors
13.\"    may be used to endorse or promote products derived from this software
14.\"    without specific prior written permission.
15.\"
16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26.\" SUCH DAMAGE.
27.\"
28.\"     From: @(#)swapon.8	8.1 (Berkeley) 6/5/93
29.\" $FreeBSD$
30.\"
31.Dd April 23, 2020
32.Dt DUMPON 8
33.Os
34.Sh NAME
35.Nm dumpon
36.Nd "specify a device for crash dumps"
37.Sh SYNOPSIS
38.Nm
39.Op Fl i Ar index
40.Op Fl r
41.Op Fl v
42.Op Fl C Ar cipher
43.Op Fl k Ar pubkey
44.Op Fl Z
45.Op Fl z
46.Ar device
47.Nm
48.Op Fl i Ar index
49.Op Fl r
50.Op Fl v
51.Op Fl C Ar cipher
52.Op Fl k Ar pubkey
53.Op Fl Z
54.Op Fl z
55.Op Fl g Ar gateway
56.Fl s Ar server
57.Fl c Ar client
58.Ar iface
59.Nm
60.Op Fl v
61.Cm off
62.Nm
63.Op Fl v
64.Fl l
65.Sh DESCRIPTION
66The
67.Nm
68utility is used to configure where the kernel can save a crash dump in the case
69of a panic.
70.Pp
71System administrators should typically configure
72.Nm
73in a persistent fashion using the
74.Xr rc.conf 5
75variables
76.Va dumpdev
77and
78.Va dumpon_flags .
79For more information on this usage, see
80.Xr rc.conf 5 .
81.Pp
82Starting in
83.Fx 13.0 ,
84.Nm
85can configure a series of fallback dump devices.
86For example, an administrator may prefer
87.Xr netdump 4
88by default, but if the
89.Xr netdump 4
90service cannot be reached or some other failure occurs, they might choose a
91local disk dump as a second choice option.
92.Ss General options
93.Bl -tag -width _k_pubkey
94.It Fl i Ar index
95Insert the specified dump configuration into the prioritized fallback dump
96device list at the specified index, starting at zero.
97.Pp
98If
99.Fl i
100is not specified, the configured dump device is appended to the prioritized
101list.
102.It Fl r
103Remove the specified dump device configuration or configurations from the
104fallback dump device list rather than inserting or appending it.
105In contrast,
106.Do
107.Nm
108off
109.Dc
110removes all configured devices.
111Conflicts with
112.Fl i .
113.It Fl k Ar pubkey
114Configure encrypted kernel dumps.
115.Pp
116A random, one-time symmetric key is automatically generated for bulk kernel
117dump encryption every time
118.Nm
119is used.
120The provided
121.Ar pubkey
122is used to encrypt a copy of the symmetric key.
123The encrypted dump contents consist of a standard dump header, the
124pubkey-encrypted symmetric key contents, and the symmetric key encrypted core
125dump contents.
126.Pp
127As a result, only someone with the corresponding private key can decrypt the symmetric key.
128The symmetric key is necessary to decrypt the kernel core.
129The goal of the mechanism is to provide confidentiality.
130.Pp
131The
132.Va pubkey
133file should be a PEM-formatted RSA key of at least 2048 bits.
134.It Fl C Ar cipher
135Select the symmetric algorithm used for encrypted kernel crash dump.
136The default is
137.Dq chacha20
138but
139.Dq aes256-cbc
140is also available.
141(AES256-CBC mode does not work in conjunction with compression.)
142.It Fl l
143List the currently configured dump device(s), or /dev/null if no devices are
144configured.
145.It Fl v
146Enable verbose mode.
147.It Fl Z
148Enable compression (Zstandard).
149.It Fl z
150Enable compression (gzip).
151Only one compression method may be enabled at a time, so
152.Fl z
153is incompatible with
154.Fl Z .
155.Pp
156Zstandard provides superior compression ratio and performance.
157.El
158.Ss Netdump
159.Nm
160may also configure the kernel to dump to a remote
161.Xr netdumpd 8
162server.
163(The
164.Xr netdumpd 8
165server is available in ports.)
166.Xr netdump 4
167eliminates the need to reserve space for crash dumps.
168It is especially useful in diskless environments.
169When
170.Nm
171is used to configure netdump, the
172.Ar device
173(or
174.Ar iface )
175parameter should specify a network interface (e.g.,
176.Va igb1 ) .
177The specified NIC must be up (online) to configure netdump.
178.Pp
179.Xr netdump 4
180specific options include:
181.Bl -tag -width _g_gateway
182.It Fl c Ar client
183The local IP address of the
184.Xr netdump 4
185client.
186.It Fl g Ar gateway
187The first-hop router between
188.Ar client
189and
190.Ar server .
191If the
192.Fl g
193option is not specified and the system has a default route, the default
194router is used as the
195.Xr netdump 4
196gateway.
197If the
198.Fl g
199option is not specified and the system does not have a default route,
200.Ar server
201is assumed to be on the same link as
202.Ar client .
203.It Fl s Ar server
204The IP address of the
205.Xr netdumpd 8
206server.
207.El
208.Pp
209All of these options can be specified in the
210.Xr rc.conf 5
211variable
212.Va dumpon_flags .
213.Ss Minidumps
214The default type of kernel crash dump is the mini crash dump.
215Mini crash dumps hold only memory pages in use by the kernel.
216Alternatively, full memory dumps can be enabled by setting the
217.Va debug.minidump
218.Xr sysctl 8
219variable to 0.
220.Ss Full dumps
221For systems using full memory dumps, the size of the specified dump
222device must be at least the size of physical memory.
223Even though an additional 64 kB header is added to the dump, the BIOS for a
224platform typically holds back some memory, so it is not usually
225necessary to size the dump device larger than the actual amount of RAM
226available in the machine.
227Also, when using full memory dumps, the
228.Nm
229utility will refuse to enable a dump device which is smaller than the
230total amount of physical memory as reported by the
231.Va hw.physmem
232.Xr sysctl 8
233variable.
234.Sh IMPLEMENTATION NOTES
235Because the file system layer is already dead by the time a crash dump
236is taken, it is not possible to send crash dumps directly to a file.
237.Pp
238The
239.Xr loader 8
240variable
241.Va dumpdev
242may be used to enable early kernel core dumps for system panics which occur
243before userspace starts.
244.Sh EXAMPLES
245In order to generate an RSA private key, a user can use the
246.Xr genrsa 1
247tool:
248.Pp
249.Dl # openssl genrsa -out private.pem 4096
250.Pp
251A public key can be extracted from the private key using the
252.Xr rsa 1
253tool:
254.Pp
255.Dl # openssl rsa -in private.pem -out public.pem -pubout
256.Pp
257Once the RSA keys are created in a safe place, the public key may be moved to
258the untrusted netdump client machine.
259Now
260.Pa public.pem
261can be used by
262.Nm
263to configure encrypted kernel crash dumps:
264.Pp
265.Dl # dumpon -k public.pem /dev/ada0s1b
266.Pp
267It is recommended to test if the kernel saves encrypted crash dumps using the
268current configuration.
269The easiest way to do that is to cause a kernel panic using the
270.Xr ddb 4
271debugger:
272.Pp
273.Dl # sysctl debug.kdb.panic=1
274.Pp
275In the debugger the following commands should be typed to write a core dump and
276reboot:
277.Pp
278.Dl db> call doadump(0)
279.Dl db> reset
280.Pp
281After reboot
282.Xr savecore 8
283should be able to save the core dump in the
284.Va Dq dumpdir
285directory, which is
286.Pa /var/crash
287by default:
288.Pp
289.Dl # savecore /dev/ada0s1b
290.Pp
291Three files should be created in the core directory:
292.Pa info.# ,
293.Pa key.#
294and
295.Pa vmcore_encrypted.#
296(where
297.Dq #
298is the number of the last core dump saved by
299.Xr savecore 8 ) .
300The
301.Pa vmcore_encrypted.#
302can be decrypted using the
303.Xr decryptcore 8
304utility:
305.Pp
306.Dl # decryptcore -p private.pem -k key.# -e vmcore_encrypted.# -c vmcore.#
307.Pp
308or shorter:
309.Pp
310.Dl # decryptcore -p private.pem -n #
311.Pp
312The
313.Pa vmcore.#
314can be now examined using
315.Xr kgdb 1 :
316.Pp
317.Dl # kgdb /boot/kernel/kernel vmcore.#
318.Pp
319or shorter:
320.Pp
321.Dl # kgdb -n #
322.Pp
323The core was decrypted properly if
324.Xr kgdb 1
325does not print any errors.
326Note that the live kernel might be at a different path
327which can be examined by looking at the
328.Va kern.bootfile
329.Xr sysctl 8 .
330.Pp
331The
332.Nm
333.Xr rc 8
334script runs early during boot, typically before networking is configured.
335This makes it unsuitable for configuring
336.Xr netdump 4
337when the client address is dynamic.
338To configure
339.Xr netdump 4
340when
341.Xr dhclient 8
342binds to a server,
343.Xr dhclient-script 8
344can be used to run
345.Xr dumpon 8 .
346For example, to automatically configure
347.Xr netdump 4
348on the vtnet0 interface, add the following to
349.Pa /etc/dhclient-exit-hooks .
350.Bd -literal
351case $reason in
352BOUND|REBIND|REBOOT|RENEW)
353	if [ "$interface" != vtnet0 ] || [ -n "$old_ip_address" -a \\
354	     "$old_ip_address" = "$new_ip_address" ]; then
355		break
356	fi
357	if [ -n "$new_routers" ]; then
358		# Take the first router in the list.
359		gateway_flag="-g ${new_routers%% *}"
360	fi
361	# Configure as the highest-priority dump device.
362	dumpon -i 0 -c $new_ip_address -s $server $gateway_flag vtnet0
363	;;
364esac
365.Ed
366.Pp
367Be sure to fill in the server IP address and change the interface name if
368needed.
369.Sh SEE ALSO
370.Xr gzip 1 ,
371.Xr kgdb 1 ,
372.Xr zstd 1 ,
373.Xr ddb 4 ,
374.Xr netdump 4 ,
375.Xr fstab 5 ,
376.Xr rc.conf 5 ,
377.Xr config 8 ,
378.Xr decryptcore 8 ,
379.Xr init 8 ,
380.Xr loader 8 ,
381.Xr rc 8 ,
382.Xr savecore 8 ,
383.Xr swapon 8 ,
384.Xr panic 9
385.Sh HISTORY
386The
387.Nm
388utility appeared in
389.Fx 2.0.5 .
390.Pp
391Support for encrypted kernel core dumps and netdump was added in
392.Fx 12.0 .
393.Sh AUTHORS
394The
395.Nm
396manual page was written by
397.An Mark Johnston Aq Mt markj@FreeBSD.org ,
398.An Conrad Meyer Aq Mt cem@FreeBSD.org ,
399.An Konrad Witaszczyk Aq Mt def@FreeBSD.org ,
400and countless others.
401.Sh CAVEATS
402To configure encrypted kernel core dumps, the running kernel must have been
403compiled with the
404.Dv EKCD
405option.
406.Pp
407Netdump does not automatically update the configured
408.Ar gateway
409if routing topology changes.
410.Pp
411The size of a compressed dump or a minidump is not a fixed function of RAM
412size.
413Therefore, when at least one of these options is enabled, the
414.Nm
415utility cannot verify that the
416.Ar device
417has sufficient space for a dump.
418.Nm
419is also unable to verify that a configured
420.Xr netdumpd 8
421server has sufficient space for a dump.
422.Pp
423.Fl Z
424requires a kernel compiled with the
425.Dv ZSTDIO
426kernel option.
427Similarly,
428.Fl z
429requires the
430.Dv GZIO
431option.
432.Sh BUGS
433Netdump only supports IPv4 at this time.
434.Sh SECURITY CONSIDERATIONS
435The current encrypted kernel core dump scheme does not provide integrity nor
436authentication.
437That is, the recipient of an encrypted kernel core dump cannot know if they
438received an intact core dump, nor can they verify the provenance of the dump.
439.Pp
440RSA keys smaller than 1024 bits are practical to factor and therefore weak.
441Even 1024 bit keys may not be large enough to ensure privacy for many
442years, so NIST recommends a minimum of 2048 bit RSA keys.
443As a seatbelt,
444.Nm
445prevents users from configuring encrypted kernel dumps with extremely weak RSA
446keys.
447If you do not care for cryptographic privacy guarantees, just use
448.Nm
449without specifying a
450.Fl k Ar pubkey
451option.
452.Pp
453This process is sandboxed using
454.Xr capsicum 4 .
455