svn commit: r341338 - head/share/man/man4

[Bruce Evans]

On Fri, 30 Nov 2018, Edward Tomasz Napierala wrote:

> Log:
>  Say in plain text what the 'debug' keymap action usually is.
>
>  MFC after:	2 weeks
>  Sponsored by:	DARPA, AFRL
>
> Modified:
>  head/share/man/man4/ddb.4
>
> Modified: head/share/man/man4/ddb.4
> ==============================================================================
> --- head/share/man/man4/ddb.4	Fri Nov 30 11:42:19 2018	(r341337)
> +++ head/share/man/man4/ddb.4	Fri Nov 30 11:44:16 2018	(r341338)
> @@ -108,7 +108,7 @@ If linked into the running kernel,
> it can be invoked locally with the
> .Ql debug
> .Xr keymap 5
> -action, or by setting setting the
> +action, usually mapped to Ctrl+Alt+Esc, or by setting setting the
> .Dv debug.kdb.enter
> sysctl to 1.
> The debugger is also invoked on kernel

Actually, it is usually mapped to Ctl-PrintScreen.  Ctl-Alt-Esc is a harder
to type alternative for this.  There is 1 more alias in syscons us.iso.kbd
and 4 more aliases in syscons us.iso.acc.kbd.  vt complicates things.  It
removes ".iso" from the file names and changes 1 unrelated entry in
us.iso.kbd.  It changes many unrelated entries in us.iso.acc.kbd, but all
changes seem to be to replace decimal constants by hex constants and mangle
the formatting.

There are many undocumented complications for enabling these keys.  Some
are:

- the config option BREAK_TO_DEBUGGER for enabling entry to kdb on serial
   line breaks is conflated with entering kdb with a breakpoint instruction
   and used to initialize the similarly conflated sysctl variable
   kdb_break_to_debugger.  Entering kdb on a serial line break is usually
   unwanted since it gives kdb entries when you unplug the cable or turn
   the other end off.  So if you have a serial console, this option should
   rarely be used the sysctl variabled should rarely be enabled.

   ddb.4 documents BREAK_TO_DEBUGGER and clearly says that it is (only) for
   serial lines and gives slightly different reasons for not using it, and
   documents kdb.break_to_debugger, but doesn't know about about the
   conflation or the kdb sysctls or the following complications.

- the sysctl variable controls entry to kdb using kdb_break() from all
   console drivers, so it should have to be enabled for the keys documented
   above to work, but it should be disabled for serial consoles.

   This is complicated by the conflation.  The "break" in kdb_break()
   means more like "break in to" than either "serial line break" or
   "breakpoint instruction".  sio and uart use this function for serial
   line breaks.  syscons uses this for the keys documented above.  But
   vt doesn't use this.

- the sysctl variable gives a layer of security for the keys documented
   above.  syscons gives 4 more layers of security.  That's 4 too many
   layers.  sio and uart don't add any layers.  vt doesn't use this layer,
   and adds its own layers.

   Details of the layers for syscons:
   - kdb entry keys can be disabled by omitting them from the
     keymap
   - IIRC, loading of keymaps is not privileged, so you will need some
     restrictions on accesses to syscons devices to secure the previous
     layer
   - config option SC_DISABLE_KDBKEY
   - sysctl variable enable_kdbkey which defaults to the inverse of the
     config option, or enabled if the config option is not set.

   Details of the layers for vt:
   - 2 layers for the keymap as for syscons
   - sysctl variable vt_kbd_debug.  The sysctl name has the vt_ prefix
     separate.  kbd_debug corresponds to the sysctl name enable_kdbkey.
     Both names are bad:
     - they are different (after removing the prefix)
     - no sc_ prefix in variable name for syscons
     - "kdb" for syscons looks like "kbd" which is a bad abbreviation for
       "keyboard" (should be "kb")
     - "kbd" for vt.  This might actually mean "keyboard".  Then "debug"
       is a verbose spelling of the "d" in "kdb", and "kdb" is not mentioned.

   The vt method is better, and I plan to change sysctl to use the same
   method as a first step in fixing the conflation.  The security restrictions
   should be per-device since you might have some secure consoles and some
   insecure consoles.  The separate security layers already give this for
   syscons and vt, but it is more needed for multiple serial consoles.

Everything except the kdb sysctl defaults to enabled, so it is easy to enable
entry to kdb via the keys documented above.  Disabling all entries to kdb
via keys involves understanding smaller mazes of security-related options
and sysctls:

- ALT_BREAK_TO_DEBUGGER option and kdb_alt_break_to_debugger sysctl.  This
   was originally only an alternative to serial line BREAK_TO_DEBUGGER.
   Its conflation with serial line breaks was smaller, but it now allows
   panics and reboots so it is even more misnamed than BREAK_TO_DEBUGGER.
   Separate security flags are needed for the different features in it.
   ddb.5 documents all this.

- in syscons, the enable_kdbkey sysctl is used for allowing the
   ALT_BREAK_TO_DEBUGGER sequences too.

- in vt, there are no extra controls on ALT_BREAK_TO_DEBUGGER sequences.
   This is the same as for sio and uart.

Bruce