Difference between revisions of "Projects/Trace logging"

Revision as of 20:18, 11 September 2009

Background

Multiple users of Kerberos have expressed a desire for logging to assist in the diagnosis of configuration failures. As a secondary benefit, such a facility may also be useful for debugging work by Kerberos developers. Requirements include:

• It is sufficient to be able to be able to log to a file specified by an environment variable.
• It is important that it be possible to enable trace logging in a standard build, such as the one shipped by the operating system vendor, because it is generally not possible to substitute specially compiled code in a customer deployment.
• The facility must not compromise the security of setuid programs by allowing the invoking user to leak information or write log files using elevated privileges.
• The facility must have a minimal impact on performance when not enabled.
• It should be possible to explicitly disable the facility at compile-time for embedded deployments or kernel code.

User Interface

To turn on tracing, the user will set the KRB5_TRACE variable to a filename. This will not work for secure contexts.

To disable tracing at compile time, the builder will specify --disable-tracing to configure.

Design

Trace logging will be done with k5trace(), which has the following signature:

 void k5trace(krb5_context context, const char *fmt, ...)

Tracing calls will use a custom formatter, adapted from the debugging code previously in lib/krb5/os/sendto_kdc.c, to facilitate the display of principal names, krb5_data structures, and the like.

For performance reasons, k5trace() will be a macro (if variadic macros are supported by the compiler) or inline function which only calls the true back-end function krb5int_trace() when tracing is enabled in the context. If a macro is used, k5trace arguments will not be evaluated unless tracing is enabled, minimizing the runtime footprint.

The krb5_context structure will gain a new field trace_fd, which will have the value -1 if tracing is not enabled. The function krb5int_init_trace will initialize trace_fd if KRB5_TRACE is defined in the environment.