Projects/Trace logging

An announcement has been sent to krbdev@mit.edu starting a review of this project. That review will conclude on 2009-09-18.

Comments can be sent to krbdev@mit.edu.

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 must be possible to turn on tracing for some processes and not others.
• It must be possible to enable tracing for a program with no special application support for tracing.
• It must be possible to enable and disable tracing dynamically within a running process. It is acceptable, though not desirable, for this functionality to require application support.
• 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.
• Trace points must be symbolically distinct, and not distinguished only by a text string. (This is important for integration with vendor-supported tracing systems such as DTrace.)

User Interface

Tracing can be enabled by setting the KRB5_TRACE environment variable to a filename. This will not work for secure contexts.

Tracing can be controlled by the application using either of the following APIs:

 /* This structure may be extended to contain more fields in the future. */
 struct krb5_trace_info {
     const char *message; 
 };
 typedef void (*krb5_trace_callback)(krb5_context context, struct krb5_trace_info *info, void *cb_data);
 krb5_error_code krb5_set_trace_filename(krb5_context context, const char *filename);
 krb5_error_code krb5_set_trace_callback(krb5_context context, krb5_trace_callback fn, void *cb_data);

When the context is destroyed, the trace callback (if set) will be called with a NULL info structure to allow destruction of cb_data. If both APIs are used, the callback takes priority over the filename. Either callback can be invoked with NULL to disable tracing.

To disable tracing at compile time, the builder will specify --disable-tracing to configure. In this case, the aforementioned APIs will still exist, but will generate no trace messages.

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.

Review

This section documents the review of the project according to Project policy. It is divided into multiple sections. First, approvals should be listed. To list an approval type

#~~~~

on its own line. The next section is for summarizing discussion, which should take place on krbdev@mit.edu. Provide links to the archive at http://mailman.mit.edu/pipermail/krbdev/ if appropriate. Blocking objections can be noted with {{project-block}}.