Changeset View
Standalone View
sbin/dumpon/dumpon.8
Context not available. | |||||
.Sh SYNOPSIS | .Sh SYNOPSIS | ||||
.Nm | .Nm | ||||
.Op Fl v | .Op Fl v | ||||
.Op Fl k Ar public_key | |||||
emaste: Should this be `public_key_file`, `key_file` or something similar? The current form is… | |||||
.Ar special_file | .Ar special_file | ||||
.Nm | .Nm | ||||
.Op Fl v | .Op Fl v | ||||
Context not available. | |||||
.Pa /etc/rc , | .Pa /etc/rc , | ||||
controlled by the | controlled by the | ||||
.Dq dumpdev | .Dq dumpdev | ||||
variable in the boot time configuration file | and | ||||
.Dq dumppubkey | |||||
variables in the boot time configuration file | |||||
.Pa /etc/rc.conf . | .Pa /etc/rc.conf . | ||||
.Pp | .Pp | ||||
The default type of kernel crash dump is the mini crash dump. | The default type of kernel crash dump is the mini crash dump. | ||||
Context not available. | |||||
variable. | variable. | ||||
.Pp | .Pp | ||||
The | The | ||||
.Op Fl k Ar public_key | |||||
flag causes | |||||
.Nm | |||||
to generate a one-time key for kernel crash dump encryption. | |||||
Done Inline Actionss/an/a/ (yes, the English rules are really odd here, but "one" starts with the "w" sound which is a consonant, so it uses "a" even though the spelling starts with a vowel. My understanding is that it is the initial sound, not the spelling that dictates "a" vs "an".) jhb: s/an/a/ (yes, the English rules are really odd here, but "one" starts with the "w" sound which… | |||||
emasteUnsubmitted Done Inline ActionsCan we clarify one-time here? One kernel crash? One boot? emaste: Can we clarify //one-time// here? One kernel crash? One boot? | |||||
The key is encrypted using | |||||
.Ar public_key . | |||||
This process is sandboxed using | |||||
.Xr capsicum 4 . | |||||
Both plain and encrypted keys are sent to the kernel using | |||||
Done Inline Actionss/send/sent/ jhb: s/send/sent/ | |||||
.Dv DIOCSKERNELDUMP | |||||
.Xr ioctl 2 . | |||||
A user can specify the | |||||
.Ar public_key | |||||
in the | |||||
.Dq dumppubkey | |||||
variable defined in | |||||
.Pa /etc/rc.conf | |||||
for use with the | |||||
.Pa /etc/rc.d/dumpon | |||||
.Xr rc 8 | |||||
script. | |||||
Done Inline ActionsI would consider adding a few articles to this sentence: A user can specify the .Ar public_key in the .Dq dumppubkey variable defined in .Pa /etc/rc.conf for use with the .Pa /etc/rc.d/dumpon .Xr rc 8 script. jhb: I would consider adding a few articles to this sentence:
```
A user can specify the
.Ar… | |||||
This flag requires a kernel compiled with the | |||||
Done Inline ActionsPossibly reword as: This option requires a kernel compiled with the .Dv EKCD kernel option. jhb: Possibly reword as:
```
This option requires a kernel compiled with the
.Dv EKCD
kernel option. | |||||
.Dv EKCD | |||||
kernel option. | |||||
.Pp | |||||
The | |||||
.Fl l | .Fl l | ||||
flag causes | flag causes | ||||
.Nm | .Nm | ||||
Context not available. | |||||
.It Pa /etc/rc.conf | .It Pa /etc/rc.conf | ||||
boot-time system configuration | boot-time system configuration | ||||
.El | .El | ||||
Done Inline ActionsI would add either "a" or "the" before user. jhb: I would add either "a" or "the" before user. | |||||
.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 | |||||
emasteUnsubmitted Not Done Inline ActionsThis .Xr seems misplaced now? followed by Otherwise a core dump may be triggered from the .Xr ddb 4 debugger: but I think @jhb was suggesting just dropping the ddb instructions altogether. emaste: This `.Xr` seems misplaced now?
What about just "...is to use the special debugging sysctl… | |||||
defAuthorUnsubmitted Not Done Inline ActionsA user wouldn't have to call doadump if it has ddb enabled in rc.conf and kdb.enter.panic contains 'call doadump; reset' in ddb.conf. def: A user wouldn't have to call doadump if it has ddb enabled in rc.conf and kdb.enter.panic… | |||||
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: | |||||
Done Inline ActionsI am a leery of recommending users to do this. This can overwrite data in swap. I would instead suggest telling users to just do 'sysctl debug.kdb.panic=1' to generate a panic and then inspect the core dump on reboot. jhb: I am a leery of recommending users to do this. This can overwrite data in swap. I would… | |||||
Done Inline ActionsGood point. Thanks! def: Good point. Thanks! | |||||
.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 # | |||||
Done Inline ActionsHmmm, reading this, have you thought at all about the /usr/sbin/crashinfo script or the existing 'kgdb -n X' functionality? I would suggest that savecore default to writing the encrypted vmcore to /var/crash/vmcore_encrypted.X by default instead of /var/crash/vmcore.X. You could then have decryptcore default to a destination of 'vmcore.X' so one could just do "decryptcore <keyfile> vmcore_encrtyped.X" and strip "_encrypted" from the source to generate a default destination name. This will then allow 'kgdb -n' to work. This would make your sample steps simpler: sysctl kern.kdb.panic=1 <reboot> decryptcore <keyfile> /var/crash/vmcore_encrypted.# kgdb -n # This would also let you check for an encrypted vmcore at the start of crashinfo and bail jhb: Hmmm, reading this, have you thought at all about the /usr/sbin/crashinfo script or the… | |||||
Done Inline ActionsI like that idea. pjd: I like that idea. | |||||
Done Inline ActionsI changed decryptcore to provide the following options: def: I changed decryptcore to provide the following options:
decryptcore [-Lv] -p privatekey -k key… | |||||
.Pp | |||||
The | |||||
.Pa vmcore.# | |||||
can be now examined using | |||||
.Xr kgdb 1 : | |||||
.Pp | |||||
.Dl # kgdb /usr/obj/sys/GENERIC/kernel.debug vmcore.# | |||||
.Pp | |||||
or shorter: | |||||
.Pp | |||||
.Dl # kgdb -n # /usr/obj/sys/GENERIC/kernel.debug | |||||
.Pp | |||||
The core was decrypted properly if | |||||
.Xr kgdb 1 | |||||
does not print any errors. | |||||
.Sh SEE ALSO | .Sh SEE ALSO | ||||
.Xr kgdb 1 , | |||||
.Xr ddb 4 , | |||||
.Xr fstab 5 , | .Xr fstab 5 , | ||||
.Xr rc.conf 5 , | .Xr rc.conf 5 , | ||||
.Xr config 8 , | .Xr config 8 , | ||||
.Xr init 8 , | .Xr init 8 , | ||||
.Xr loader 8 , | .Xr loader 8 , | ||||
.Xr rc 8 , | .Xr rc 8 , | ||||
.Xr decryptcore 8 , | |||||
.Xr savecore 8 , | .Xr savecore 8 , | ||||
.Xr swapon 8 , | .Xr swapon 8 , | ||||
.Xr panic 9 | .Xr panic 9 | ||||
Context not available. |
Should this be public_key_file, key_file or something similar? The current form is confusing to me in the context of the "one-time key" description below.