Difference between revisions of "Projects/Trace logging"
(→Selecting Trace Information) |
(→Implementation concerns) |
||
| Line 17: | Line 17: | ||
To disable tracing at compile time, the builder will specify --disable-tracing to configure. |
To disable tracing at compile time, the builder will specify --disable-tracing to configure. |
||
| − | ==Implementation concerns== |
||
| + | ==Design== |
||
| − | The biggest decision here is whether trace calls require a context. If so: |
||
| + | The programmer interface will be through k5trace(), which has the following signature: |
||
| − | * Thread safety is easier (a log file handle can be cached in the context). |
||
| + | void k5trace(krb5_context context, const char *fmt, ...) |
||
| − | * The mechanism can be disabled for setuid programs via krb5_init_secure_context. |
||
| − | * A macro can elide the function calls when trace logging is not enabled, saving a few cycles. |
||
| − | * APIs could be provided to turn tracing on and off, or direct different contexts to different files. (However, API control of tracing is not a requirement.) |
||
| − | If not: |
||
| + | 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. |
||
| − | * Code which does not have a context available can be traced. |
||
| + | 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. |
||
| − | * Cached information must be global, and therefore locked, probably with some kind of cheat to minimize the performance impact when disabled. |
||
| + | |||
| − | * Trace calls become less verbose. |
||
| + | 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. |
||
| − | * The implementation can live in libkrb5support instead of libkrb5. |
||
| − | * The facility might be more friendly to plugin code living in our tree. |
||
Revision as of 21: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
The programmer interface will be through 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.
