diff options
Diffstat (limited to 'third_party/heimdal/lib/krb5/krb5_openlog.3')
| -rw-r--r-- | third_party/heimdal/lib/krb5/krb5_openlog.3 | 305 |
1 files changed, 305 insertions, 0 deletions
diff --git a/third_party/heimdal/lib/krb5/krb5_openlog.3 b/third_party/heimdal/lib/krb5/krb5_openlog.3 new file mode 100644 index 0000000..09de9d0 --- /dev/null +++ b/third_party/heimdal/lib/krb5/krb5_openlog.3 @@ -0,0 +1,305 @@ +.\" Copyright (c) 1997, 1999, 2001 - 2002 Kungliga Tekniska Högskolan +.\" (Royal Institute of Technology, Stockholm, Sweden). +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" 3. Neither the name of the Institute nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $Id$ +.Dd August 6, 1997 +.Dt KRB5_OPENLOG 3 +.Os HEIMDAL +.Sh NAME +.Nm krb5_initlog , +.Nm krb5_openlog , +.Nm krb5_closelog , +.Nm krb5_addlog_dest , +.Nm krb5_addlog_func , +.Nm krb5_log , +.Nm krb5_vlog , +.Nm krb5_log_msg , +.Nm krb5_vlog_msg +.Nd Heimdal logging functions +.Sh LIBRARY +Kerberos 5 Library (libkrb5, -lkrb5) +.Sh SYNOPSIS +.In krb5.h +.Ft "typedef void" +.Fn "\*(lp*krb5_log_log_func_t\*(rp" "const char *time" "const char *message" "void *data" +.Ft "typedef void" +.Fn "\*(lp*krb5_log_close_func_t\*(rp" "void *data" +.Ft krb5_error_code +.Fn krb5_addlog_dest "krb5_context context" "krb5_log_facility *facility" "const char *destination" +.Ft krb5_error_code +.Fn krb5_addlog_func "krb5_context context" "krb5_log_facility *facility" "int min" "int max" "krb5_log_log_func_t log" "krb5_log_close_func_t close" "void *data" +.Ft krb5_error_code +.Fn krb5_closelog "krb5_context context" "krb5_log_facility *facility" +.Ft krb5_error_code +.Fn krb5_initlog "krb5_context context" "const char *program" "krb5_log_facility **facility" +.Ft krb5_error_code +.Fn krb5_log "krb5_context context" "krb5_log_facility *facility" "int level" "const char *format" "..." +.Ft krb5_error_code +.Fn krb5_log_msg "krb5_context context" "krb5_log_facility *facility" "char **reply" "int level" "const char *format" "..." +.Ft krb5_error_code +.Fn krb5_openlog "krb5_context context" "const char *program" "krb5_log_facility **facility" +.Ft krb5_error_code +.Fn krb5_vlog "krb5_context context" "krb5_log_facility *facility" "int level" "const char *format" "va_list arglist" +.Ft krb5_error_code +.Fn krb5_vlog_msg "krb5_context context" "krb5_log_facility *facility" "char **reply" "int level" "const char *format" "va_list arglist" +.Sh DESCRIPTION +These functions logs messages to one or more destinations. +.Pp +The +.Fn krb5_openlog +function creates a logging +.Fa facility , +that is used to log messages. A facility consists of one or more +destinations (which can be files or syslog or some other device). The +.Fa program +parameter should be the generic name of the program that is doing the +logging. This name is used to lookup which destinations to use. This +information is contained in the +.Li logging +section of the +.Pa krb5.conf +configuration file. If no entry is found for +.Fa program , +the entry for +.Li default +is used, or if that is missing too, +.Li SYSLOG +will be used as destination. +.Pp +To close a logging facility, use the +.Fn krb5_closelog +function. +.Pp +To log a message to a facility use one of the functions +.Fn krb5_log , +.Fn krb5_log_msg , +.Fn krb5_vlog , +or +.Fn krb5_vlog_msg . +The functions ending in +.Li _msg +return in +.Fa reply +a pointer to the message that just got logged. This string is allocated, +and should be freed with +.Fn free . +The +.Fa format +is a standard +.Fn printf +style format string (but see the BUGS section). +.Pp +If you want better control of where things gets logged, you can instead of using +.Fn krb5_openlog +call +.Fn krb5_initlog , +which just initializes a facility, but doesn't define any actual logging +destinations. You can then add destinations with the +.Fn krb5_addlog_dest +and +.Fn krb5_addlog_func +functions. The first of these takes a string specifying a logging +destination, and adds this to the facility. If you want to do some +non-standard logging you can use the +.Fn krb5_addlog_func +function, which takes a function to use when logging. +The +.Fa log +function is called for each message with +.Fa time +being a string specifying the current time, and +.Fa message +the message to log. +.Fa close +is called when the facility is closed. You can pass application specific data in the +.Fa data +parameter. The +.Fa min +and +.Fa max +parameter are the same as in a destination (defined below). To specify a +max of infinity, pass -1. +.Pp +.Fn krb5_openlog +calls +.Fn krb5_initlog +and then calls +.Fn krb5_addlog_dest +for each destination found. +.Ss Destinations +The defined destinations (as specified in +.Pa krb5.conf ) +follows: +.Bl -tag -width "xxx" -offset indent +.It Li STDERR +This logs to the program's stderr. +.It Li EFILE: Ns Pa /file +Log to the specified file if it exists, otherwise do nothing. +All writes will be appended to the end of the file and the file +will be re-opened for each new write. +Non-existence of the file is cached for 1 second which reduces +the potential performance impact significantly. +This is useful for defining a trace file which can be enabled +without restarting a server. +.It Li FILE: Ns Pa /file +Log to the specified file. +All writes will be appended to the end of the file and the file +will be re-opened for each new write. +.It Li FILE= Ns Pa /file +On the first write, this form will +.Xr truncate 2 +the file and then append all subsequent messages whilst keeping the +file descriptor open. +This form is mainly for compatibility with MIT libkrb5. +.It Li DEVICE= Ns Pa /device +This logs to the specified device, at present this is the same as +.Li FILE:/device . +.It Li CONSOLE +Log to the console, this is the same as +.Li DEVICE=/dev/console . +.It Li SYSLOG Ns Op :priority Ns Op :facility +Send messages to the syslog system, using priority, and facility. To +get the name for one of these, you take the name of the macro passed +to +.Xr syslog 3 , +and remove the leading +.Li LOG_ +.No ( Li LOG_NOTICE +becomes +.Li NOTICE ) . +The default values (as well as the values used for unrecognised +values), are +.Li ERR , +and +.Li AUTH , +respectively. See +.Xr syslog 3 +for a list of priorities and facilities. +.El +.Pp +Each destination may optionally be prepended with a range of logging +levels, specified as +.Li min-max/ . +If the +.Fa level +parameter to +.Fn krb5_log +is within this range (inclusive) the message gets logged to this +destination, otherwise not. Either of the min and max valued may be +omitted, in this case min is assumed to be 0, and max is assumed to +be 3. +If you don't include a dash, both min and max get set to the +specified value. +.Pp +The paths specified are subject to token expansion. +For the purposes of logging, the most interesting token +expansion is +.ar %{strftime:<string>} +which calls +.Xr strftime 3 +on +.Ar <string> +with the localised current time of day. +.Ss Levels +Each log message has a level as follows: +.Bl -tag -width "xxx" -offset indent +.It 0 +Critical conditions. +This is a condition that should be corrected immediately, such as a +corrupted Kerberos database. +.It 1 +Errors. +These are errors that occur in the normal processing of requests. +.It 2 +Warning messages. +On the KDC, this includes malformed requests and requests that +are out of policy. +.It 3 +Informational messages. +.It 4-6 +Debugging messages with increasing obscurity as the level rises. +.It 7 +Tracing messages. +These messages may be high volume and are likely to impact +performance significantly. +Notably, tracing messages may be emitted whilst locks are held. +.El +.Sh EXAMPLES +.Bd -literal -offset indent +[logging] + kdc = 0/FILE:/var/log/kdc.log + kdc = 1-/SYSLOG:INFO:USER + default = STDERR +.Ed +.Pp +This will log all messages from the +.Nm kdc +program with level 0 to +.Pa /var/log/kdc.log , +other messages will be logged to syslog with priority +.Li LOG_INFO , +and facility +.Li LOG_USER . +.Bd -literal -offset indent +[logging] + kdc = FILE:/var/log/kdc-%{strftime:%Y%m%d%H} + kdc = 4-/EFILE:/tmp/kdc-trace +.Ed +.Pp +This will log all messages from the +.Nm kdc +program with level 0 to 3 (inclusively) to a file whose +name is generated using +.Xr strftime 3 . +As the file is +.Xr open 2 ed +each time a log message is written, this can be used to write +automatically rotating log files. +All of the KDC debugging messages will be written into +.Pa /tmp/kdc-trace +but only if it exists. +.Sh SEE ALSO +.Xr syslog 3 , +.Xr krb5.conf 5 +.Sh BUGS +These functions use +.Fn asprintf +to format the message. If your operating system does not have a working +.Fn asprintf , +a replacement will be used. At present this replacement does not handle +some correct conversion specifications (like floating point numbers). Until +this is fixed, the use of these conversions should be avoided. +.Pp +If logging is done to the syslog facility, these functions might not be +thread-safe, depending on the implementation of +.Fn openlog , +and +.Fn syslog . |