diff options
Diffstat (limited to 'lib/umberlog.3')
| -rw-r--r-- | lib/umberlog.3 | 211 |
1 files changed, 211 insertions, 0 deletions
diff --git a/lib/umberlog.3 b/lib/umberlog.3 new file mode 100644 index 0000000..ee7be30 --- /dev/null +++ b/lib/umberlog.3 @@ -0,0 +1,211 @@ +.\" umberlog.3 -- CEE-enhanced syslog manual +.\" +.\" Copyright (c) 2012 BalaBit IT Security Ltd. +.\" 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. +.\" +.\" THIS SOFTWARE IS PROVIDED BY BALABIT 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 BALABIT 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. +.\" +.TH UMBERLOG 3 2012-03-22 "libumberlog" "CEE\-enhanced syslog Manual" + +.SH NAME +ul_openlog, ul_syslog, ul_vsyslog, ul_legacy_syslog, +ul_legacy_vsyslog \- send CEE-enhanced messages to the system logger +.br +ul_format, ul_vformat \- format CEE\-enhanced messages, without +sending them to the system logger + +.SH SYNOPSIS +.B #include <umberlog.h> +.sp +.BI "void ul_openlog(const char *" ident ", int " option ", int " facility ); +.br + +.br +.BI "void ul_syslog(int " priority ", const char *" format ", ...);" +.br +.BI "void ul_vsyslog(int " priority ", const char *" format ", va_list " ap ); +.br + +.br +.BI "void ul_legacy_syslog(int " priority ", const char *" format ", ...);" +.br +.BI "void ul_legacy_vsyslog(int " priority ", const char *" format ", va_list " ap ); +.br + +.br +.BI "char *ul_format(int " priority ", const char *" format ", ...);" +.br +.BI "char *ul_vformat(int " priority ", const char *" format ", va_list " ap ); + +.SH DESCRIPTION +.BR ul_openlog (), +(also aliased to +.BR openlog ()) +is a wrapper around the original +.BR openlog () +function, which opens a connection to the system logger for a +program. The updated version adds support for a number of new option +flags, described below. + +.sp +.BR ul_legacy_syslog () +and +.BR ul_legacy_vsyslog () +are both thin layers over the original +.BR syslog () +and +.BR vsyslog () +functions, and the library overrides the original functions with this +two. The only change these functions bring, are that the message they +generate will be a CEE\-enhanced message, with a JSON payload. See +below for an explanation on what this means. + +.sp +.BR ul_syslog () +and +.BR ul_vsyslog () +are two new functions provided by the library, that have similar +interface to the legacy +.BR syslog () +functions, but they can be used to add arbitrary key-value pairs to +the emitted message. After the +.I msg_format +format string, and any other parameters it refers to, there must be a +NULL-terminated list of +.IR key ", " "value format" ", " "format parameters" . +Each of these pairs, constructed from the +.I key +and the +.BR printf (3)-style +.I value format +will be added to the generated message. + +.sp +.BR ul_format () +and +.BR ul_vformat () +do the same as the syslog variants above, except the formatted payload +is not sent to syslog, but returned as a newly allocated string. + +.SH "CEE PAYLOAD" + +All of the improved +.BR syslog () +functions, the legacy and overridden ones and the new ones too turn +the original syslog message into a CEE\-enabled JSON payload, with the +original message put into the +.I msg +field, and any additional fields put into the same structure. + +By default, unless the +.B LOG_UL_NODISCOVER +option flag is set, all of these functions will also add a few +automatically discovered fields into the payload: + +.TP 15 +.I pid +The process ID of the program, as returned by +.BR getpid (). +The value of this is \- by default \- determined at the time of +calling +.BR ul_openlog (), +but if caching is disabled, it will be rechecked every time. +.TP +.IR facility " and " priority +The syslog facility and priority as a text string. +.TP +.I program +The identification set at the time of +.BR ul_openlog (). +.TP +.IR uid " and " gid +The user and group ID of the process, determined at +.BR ul_openlog () +time by default, unless caching is disabled. +.TP +.I host +The name of the originating host, determined at +.BR ul_openlog () +time by default, using +.BR gethostname (). +.TP +.I timestamp +High\-precision timestamp, in textual format. Included by default, but +can be controlled by the +.B LOG_UL_NOTIME +option flag at +.BR ul_openlog () +time. +.PP + +.SH "EXTRA OPTION FLAGS" +The +.I option +argument to +.BR ul_openlog () +is an OR of any of the original +.BR openlog () +flags, and these: +.TP 15 +.B LOG_UL_NODISCOVER +Disable all automatic\-discovery, and only include the +.I message +and any specified +.I key\-value +pairs in the generated message. +.TP +.B LOG_UL_NOCACHE +When automatic discovery is enabled, disable caching certain +properties, that might change between the call to +.BR openlog () +and the +.BR ul_syslog () +invocation. +.TP +.B LOG_UL_NOCACHE_UID +Disable caching the +.IR uid " and " gid +caching when automatic discovery is enabled, but do cache the rest. +.TP +.B LOG_UL_NOTIME +Do not add a high\-precision timestamp to the generated message when +automatic discovery is enabled. +.PP + +.SH EXAMPLES +.nf + + ul_syslog(LOG_NOTICE, "Logged in user: %s", username, + "service", "%s", service, + "auth-method", "%s", auth_method, + "sessionid", "%d", session_id, + NULL); +.fi + +.SH "SEE ALSO" +.BR syslog (1) + +.SH COLOPHON +This page is part of the +.I libumberlog +project, and is available under the same 2-clause BSD license as the +rest of the project. |