Skip Menu |

Subject: Logging from KDC/kadmind plugin modules
Download (untitled) / with headers
text/plain 3.6KiB
KDC and kadmind plugin modules should be able to write log messages
to facilitate operational debugging and transitions. For example,
the PKINIT kdcpreauth module should be able to log whether the client
sent a freshness token, to allow a KDC administrator to determine
when it is practical to require freshness tokens. For this ticket, I
am going to ignore the problem of associating module log information
with core KDC log information about an AS or TGS request, and focus
on being able to write log messages at all.

A module can link against libkadm5srv and call krb5_klog_syslog()
like the KDC and kadmind do. Of the modules in the krb5 source tree,
only securid_sam2 does this, always logging at LOG_INFO severity.
For some modules linking against libkadm5srv is undesirable; for
instance, the PKINIT shared object is both a clpreauth and a
kdcpreauth module, and the clpreauth module shouldn't drag in the
server-side libraries.

krb5kdc and kadmind install a custom com_err handler which causes
com_err() calls to write to the logging device. This handler is
potentially useful because modules have access to com_err() even if
they don't link against libkadm5srv. Within the KDC, com_err() is
invoked in a few places (mostly just at startup) via the kdc_err()
wrapper, which ensures that extended error messages are used when
fetching the error message for the com_err code. Within plugin
modules in the krb5 source tree, the securid_sam2 and OTP modules
make calls to com_err(). securid_sam2 passes a whoami value of
"krb5kdc"; OTP passes a whoami value of "otp". Plugin modules cannot
make extended error messages used for the com_err code as they do not
have access to the krb5_context object registered with the com_err

The current behavior of the custom com_err handler is full of
interesting corners:

* If the first byte of the format has a value between 1 and 8
inclusive, that byte is treated as a severity level. I'm not aware
of any uses of this, and using it would be awkward ("\5format" to log
at warning level).

* It doesn't go through krb5_klog_syslog(); it has its own separate
loop and switch statement to write to the logging outputs.

* For file/device/console/stderr logging, it does not follow the
format of krb5_klog_syslog() at all, so a log might look like:

Dec 25 08:54:56 equal-rites krb5kdc[23873](info): setting up
krb5kdc: setsockopt(9,IPV6_V6ONLY,1) worked
krb5kdc: setsockopt(11,IPV6_V6ONLY,1) worked
Dec 25 08:54:56 equal-rites krb5kdc[23873](info): set up 4

where the first and fourth lines were generated with
krb5_klog_syslog() and the second and third were generated with

* For syslog output, if no severity was given in the format string,
the default severity is used if one was given in the SYSLOG:
specification for the logging spec. (The default severity is
LOG_ERR.) This is the only use of the default severity.
Conceptually, a default severity doesn't make much sense, as log
event severity should be a property of an individual logging call,
not a logging output.

* For syslog output, the whoami value passed to com_err() is ignored
in favor of the value passed to openlog() at krb5_klog_init() time.
For other outputs, the whoami value passed to com_err() is included
in the message.

The PKINIT module currently does no logging via the KDC/kadmind log
framework. It outputs some messages to the trace log, and it also
has an extensive set of debugging output calls which are compiled out
by default. Some of these messages would be appropriate for trace
logging, some for traditional logging, and some are only potentially
interesting for debugging the code without using gdb.
Download (untitled) / with headers
text/plain 1.9KiB
One candidate improvement is to add a logging callback to the
kdcpreauth interface with the same signature as krb5_klog_syslog(),
and phase out the use of com_err() in kdcpreauth modules. This
option does not address other KDC pluggable interfaces like certauth
and kdcpolicy, but perhaps modules for those interfaces won't have a
problem linking against libkadm5srv if they need to log.
krb5_klog_syslog() doesn't have a convenient shorthand for logging
errors like com_err() does; we could add a second callback wrapper
for that, or leave it up to modules to decide what to do about logs
resulting from errors with associated com_err codes.

Another candidate improvement is to clean up the com_err() logging
behavior and use it more consistently in modules. For this line of

* The whoami value should be consistently used or ignored. Ignoring
it is the simplest option, as the logging framework already has a
whoami value given at initialization. The OTP calls to com_err()
would need to be changed to take into account that the whoami
argument ("otp") won't appear in the log message.

* Taking a severity specification in the first byte of the format
string could probably be removed for code cleanliness.

* The "default severity" could probably be removed. The com_err
handler could log at LOG_ERR severity if a non-zero code is given and
LOG_INFO severity if the code is zero. That is somewhat limiting (no
ability to issue LOG_WARN severity messages).

* We could make extended error messsage work by adding a libkadm5srv
interface to set the value of err_context (used by the logging
com_err handler and currently only set at krb5_klog_init() time), and
making the KDC set err_context to the per-realm krb5_context object
for each request. That's not very satisfactory, but it's the only
real option given that com_err() doesn't accept a krb5_context
parameter. (err_context could also be made a thread-local variable,
but that's not an immediate concern.)
Subject: git commit
Download (untitled) / with headers
text/plain 1.1KiB

Improve klog com_err hook

Remove the code to read a severity from the first byte of format, as
it is an unclear interface and likely unused. Also stop using the
configured default severity for syslog devices. Instead, log at error
severity if a code is given, and at informational severity if one is

Pass the formatted message to krb5_klog_syslog() so that it uses the
same format in log files as regular logged messages.

Add krb5_klog_set_context() to allow the context for extended error
messages to be reset, so that KDC plugins can log using the context
object for the realm being served for each request.

Use k5buf for simpler memory management in the hook function.
Author: Greg Hudson <>
Commit: 09cbda11a4f220db1810485123851b4f2d89dd55
Branch: master
doc/plugindev/general.rst | 20 ++++
src/include/adm_proto.h | 1 +
src/lib/kadm5/clnt/libkadm5clnt_mit.exports | 1 +
src/lib/kadm5/logger.c | 150 +++++----------------------
src/lib/kadm5/srv/libkadm5srv_mit.exports | 1 +
5 files changed, 50 insertions(+), 123 deletions(-)
Subject: git commit

Remove logging default severity

The default severity for syslog outputs was only used for com_err()
messages (which are rare so far), and doesn't really make sense;
severity is a property of an individual message, not of a device.
Remove the severity field in a backward-compatible manner.
Author: Greg Hudson <>
Commit: 6ce8fd4cfa2e9b1e92debd204a5b2ddf053cca55
Branch: master
doc/admin/conf_files/kdc_conf.rst | 12 +++-------
src/lib/kadm5/logger.c | 41 +------------------------------------
2 files changed, 5 insertions(+), 48 deletions(-)
Subject: git commit

Set klog com_err context for each KDC request

In setup_server_realm(), set the error context for the klog com_err
hook so that com_err() can retrieve error messages using the per-realm
Author: Greg Hudson <>
Commit: 3e1f1c281f977b253934a641753d09b261c84cdb
Branch: master
src/kdc/main.c | 16 +++++++++-------
1 files changed, 9 insertions(+), 7 deletions(-)
Subject: git commit

Fix type error in klog com_err hook

As a variable argument, won't be automatically cast from
void * to char * when passed to krb5_klog_syslog(), so to be correct
we must do it manually.
Author: Greg Hudson <>
Commit: 5a5be01e888a575b72407088749066213c57284f
Branch: master
src/lib/kadm5/logger.c | 2 +-
1 files changed, 1 insertions(+), 1 deletions(-)