logo_kerberos.gif

Projects/Trace logging

From K5Wiki
< Projects
Revision as of 13:32, 16 September 2009 by Ghudson (talk | contribs) (Design)

Jump to: navigation, search

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.

Tracing API

Each trace point will have a separate macro; an example invocation for credential acquisition might be:

 TRACE_GET_CREDS(context, in_creds->client, in_creds->server, options)

The header file k5-trace.h (included by k5-int.h) will define the tracing macros in terms of the function krb5int_trace, which has the signature:

 static void krb5int_trace(krb5_context *context, const char *fmt, ...);

Each macro will supply a format string to krb5int_trace and pass in its arguments. krb5int_trace will implement a custom formatter, adapted from the debugging code previously in lib/krb5/os/sendto_kdc.c, to allow stringification of data types such as krb5_principal and krb5_data. Macro expansions will not evaluate arguments if tracing is disabled either at compile time or runtime, so arguments to these macros must not have side-effects.

Vendors can use k5-trace.h as an integration point for tracing systems such as DTrace, but we will not supply any such integrations at this time.

The krb5_context structure will gain the following new fields:

 krb5_trace_callback trace_callback;
 void *trace_callback_data;

In the simple case where trace output is being directed to a file (either via the KRB5_TRACE environment variable or the krb5_set_trace_filename API), trace_callback will be set to a built-in callback function and trace_callback_data will point to the file descriptor.

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}}.

Approvals

Discussion