Skip Menu |
 

Subject: Debug output hooks need to be added to support Windows Help Desk
The old windows krb4 library provided debug output which could be used
by Help Desks to debug misbehaviors. The lack of this functionality in
the krb5 libraries is a serious problem.

If there is time it would be good to add some debugging to the krb5
libraries at critical points such as kdc name resolution; send to kdc;
and the cache ticket retrieval functions.
I am proposing the following api:

krb5_error krb5_get_debug(krb5_context ctx, uint32 *debug_mask)
krb5_error krb5_set_debug(krb5_context ctx, uint32 debug_mask)

A mask is used to allow different qualities of debugging messages to be
generated. At first we will probably define a small number of types.
Perhaps

KRB5_DEBUG_NONE 0x0
KRB5_DEBUG_TGS 0x1
KRB5_DEBUG_AP 0x2
KRB5_DEBUG_ALL 0xFFFFFFFF

The debugging mode will be stored within the krb5_context.

The initial value of the debugging mode will be read from the profile:
[libdefaults]
debug_mask = 3
debug_log = FILE:<path>

The actual debug statements themselves will be of the form

krb5int_debug_message(krb5_context ctx, char * fmt, ...)

Each platform will define its own implementation of
krb5int_debug_message() as needed. The Windows version will behave
similar to the existing Krb4 interface. The Unix version could either
write messages to a log file, to stderr, or to the syslog() api.
Download (untitled) / with headers
text/plain 3.3KiB
From Ken:

The list below was originally entitled "some thoughts on logging", and I
was going to work on it a bit more before sending it, but since Jeff has
brought it up....

I agree with Sam that 32 flags might not be enough. I think we could
use an array and an offset into it, with each flag being the offset, not
a mask. Initially, it probably would only have one element, but we
might expand it quickly. libkrb5-tgs, libkrb5-as, libkrb5-ap, kdc-tgs,
kdc-as, kdb, kdb-db2, kdb-mysql, krb524, krb4-tgs, krb4-as, krb4-ap,
libkrb5-sendto, crypto, fake-getaddrinfo, gsssapi, pty, I'm sure we
could come up with other cases where we want to debug only one aspect of
the code.

The syslog approach of having a "level" orthogonal to the "facility"
seems useful. We could send serious problems (e.g., keytab format
errors) to syslog by default, leave informational and debugging messages
off unless requested. Might we want another separate flag for whether
or not hex dumps should be logged?

I think I'd like to have the option of a textual form for specifying the
parts of code for which debugging is enabled. Numeric is okay, but if
we do only numeric, we should at least make sure to support a hex
option, and support more than 32 flags. (Arbitrary hex string to fill
an array of unsigned char?)

Some other random thoughts:

* A printf-like function that is Kerberos-aware would be handy. I did
something like that for sendto_kdc, with %E for krb5_error_code
(displays as numeric and text), %m for an errno value (like syslog, but
passed in instead of global), %F for select file descriptor set (a
structure I set up in that code, in/out/except fd sets plus timeout),
%s/%d/%p like printf but without widths, %t for struct timeval, %A for
struct addrinfo, %D for krb5_data (raw dump). Add more, like principal
name display etc.

* compile-time checking for the debug calls would be nice, but
conflicts with the above

* "dump out this block in hex and ascii"; I've written that some 3 or 4
times now. For non-ascii dumps, probably want two forms, one for short
byte strings, all in one line, maybe without spaces, and another for big
blocks, with line breaks and maybe offsets and such.

* should be able to compile in by default, leaving it disabled (but we
currently dump the enctype list in KDC requests?)

* logging for administrative reporting and debugging are not the same
thing, though they can probably use some of the same code. (Perhaps we
should log enctype lists separately from other data in KDC requests?)

* switching between stderr and syslog and log file is a nice option;
select through config file?

* log file name and line number, maybe function name as well if
available; try to do it through macros so as to require much less typing
to instrument code; could be as easy as #define HERE
__FILE__,__LINE__,__func__/NULL

* annotate lots of error returns in libraries, especially when multiple
causes are possible

* be able to switch on and off logging for various parts of the code
(crypto, kdc, libkrb5, gss, maybe finer control?). maybe multiple flag
variables, maybe multiple bits in a vector. Probably test at call site
via macro or inline function?

* log "e-text" field in "generic error" case

* short name for convenience, even if via macro, since we'll be typing
it a lot, and calling it with long strings that don't look good when
they wrap