From 30676376a578e1ff31862abcb4780b063b0284d0 Mon Sep 17 00:00:00 2001 From: Gergely Nagy Date: Fri, 23 Mar 2012 10:08:16 +0100 Subject: Rename the project to libumberlog Signed-off-by: Gergely Nagy --- lib/Makefile.am | 26 ++-- lib/cee-syslog.c | 377 ------------------------------------------------ lib/cee-syslog.h | 51 ------- lib/libcee-syslog.3 | 211 --------------------------- lib/libcee-syslog.ld | 17 --- lib/libcee-syslog.pc.in | 10 -- lib/libumberlog.ld | 17 +++ lib/libumberlog.pc.in | 10 ++ lib/umberlog.3 | 211 +++++++++++++++++++++++++++ lib/umberlog.c | 376 +++++++++++++++++++++++++++++++++++++++++++++++ lib/umberlog.h | 51 +++++++ 11 files changed, 677 insertions(+), 680 deletions(-) delete mode 100644 lib/cee-syslog.c delete mode 100644 lib/cee-syslog.h delete mode 100644 lib/libcee-syslog.3 delete mode 100644 lib/libcee-syslog.ld delete mode 100644 lib/libcee-syslog.pc.in create mode 100644 lib/libumberlog.ld create mode 100644 lib/libumberlog.pc.in create mode 100644 lib/umberlog.3 create mode 100644 lib/umberlog.c create mode 100644 lib/umberlog.h (limited to 'lib') diff --git a/lib/Makefile.am b/lib/Makefile.am index c32a826..a208bc2 100644 --- a/lib/Makefile.am +++ b/lib/Makefile.am @@ -1,20 +1,18 @@ -LCS_CURRENT = 0 -LCS_REVISION = 0 -LCS_AGE = 0 +LUL_CURRENT = 0 +LUL_REVISION = 0 +LUL_AGE = 0 -lib_LTLIBRARIES = libcee-syslog.la -libcee_syslog_la_LDFLAGS = -Wl,--version-script,${srcdir}/libcee-syslog.ld -libcee_syslog_la_LIBADD = @JSON_LIBS@ -ldl -lrt -libcee_syslog_la_CFLAGS = @JSON_CFLAGS@ +lib_LTLIBRARIES = libumberlog.la +libumberlog_la_LDFLAGS = -Wl,--version-script,${srcdir}/libumberlog.ld +libumberlog_la_LIBADD = @JSON_LIBS@ -ldl -lrt +libumberlog_la_CFLAGS = @JSON_CFLAGS@ -libcee_syslog_la_SOURCES = \ - cee-syslog.c cee-syslog.h +libumberlog_la_SOURCES = umberlog.c umberlog.h -libcee_syslog_includedir = $(includedir)/cee -libcee_syslog_include_HEADERS = \ - cee-syslog.h +libumberlog_includedir = $(includedir) +libumberlog_include_HEADERS = umberlog.h pkgconfigdir = $(libdir)/pkgconfig -pkgconfig_DATA = libcee-syslog.pc +pkgconfig_DATA = libumberlog.pc -man3_MANS = libcee-syslog.3 +man3_MANS = umberlog.3 diff --git a/lib/cee-syslog.c b/lib/cee-syslog.c deleted file mode 100644 index b9d648d..0000000 --- a/lib/cee-syslog.c +++ /dev/null @@ -1,377 +0,0 @@ -/* cee-syslog.c -- CEE-enhanced syslog API. - * - * 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. - */ - -#define _GNU_SOURCE 1 -#define SYSLOG_NAMES 1 - -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include - -#include "cee-syslog.h" - - -#if __USE_FORTIFY_LEVEL > 0 -static void (*old_syslog_chk) (); -#else -static void (*old_syslog) (); -#endif - -static void (*old_openlog) (); -static int (*old_setlogmask) (); - -static void cee_init (void) __attribute__((constructor)); - -static __thread struct -{ - int mask; - int flags; - - int facility; - pid_t pid; - uid_t uid; - gid_t gid; - const char *ident; - char hostname[HOST_NAME_MAX + 1]; -} cee_sys_settings; - -static void -cee_init (void) -{ -#if __USE_FORTIFY_LEVEL > 0 - old_syslog_chk = dlsym (RTLD_NEXT, "__syslog_chk"); -#else - old_syslog = dlsym (RTLD_NEXT, "syslog"); -#endif - old_openlog = dlsym (RTLD_NEXT, "openlog"); - old_setlogmask = dlsym (RTLD_NEXT, "setlogmask"); -} - -void -cee_openlog (const char *ident, int option, int facility) -{ - old_openlog (ident, option, facility); - cee_sys_settings.mask = old_setlogmask (0); - cee_sys_settings.flags = option; - cee_sys_settings.facility = facility; - cee_sys_settings.pid = getpid (); - cee_sys_settings.gid = getgid (); - cee_sys_settings.uid = getuid (); - cee_sys_settings.ident = ident; - - gethostname (cee_sys_settings.hostname, HOST_NAME_MAX); -} - -/** HELPERS **/ -static const char * -_find_facility (void) -{ - int i = 0; - - while (facilitynames[i].c_name != NULL && - facilitynames[i].c_val != cee_sys_settings.facility) - i++; - - if (facilitynames[i].c_val == cee_sys_settings.facility) - return facilitynames[i].c_name; - return ""; -} - -static const char * -_find_prio (int prio) -{ - int i = 0; - - while (prioritynames[i].c_name != NULL && - prioritynames[i].c_val != prio) - i++; - - if (prioritynames[i].c_val == prio) - return prioritynames[i].c_name; - return ""; -} - -static inline pid_t -_find_pid (void) -{ - if (cee_sys_settings.flags & LOG_CEE_NOCACHE) - return getpid (); - else - return cee_sys_settings.pid; -} - -static inline uid_t -_get_uid (void) -{ - if (cee_sys_settings.flags & LOG_CEE_NOCACHE || - cee_sys_settings.flags & LOG_CEE_NOCACHE_UID) - return getuid (); - else - return cee_sys_settings.uid; -} - -static inline uid_t -_get_gid (void) -{ - if (cee_sys_settings.flags & LOG_CEE_NOCACHE || - cee_sys_settings.flags & LOG_CEE_NOCACHE_UID) - return getgid (); - else - return cee_sys_settings.gid; -} - -static inline const char * -_get_hostname (void) -{ - if (cee_sys_settings.flags & LOG_CEE_NOCACHE) - gethostname (cee_sys_settings.hostname, HOST_NAME_MAX); - return cee_sys_settings.hostname; -} - -static struct json_object * -_cee_json_vappend (struct json_object *json, va_list ap) -{ - char *key; - - while ((key = (char *)va_arg (ap, char *)) != NULL) - { - char *fmt = (char *)va_arg (ap, char *); - char *value; - - if (vasprintf (&value, fmt, ap) == -1) - abort (); - json_object_object_add (json, key, json_object_new_string (value)); - free (value); - } - return json; -} - -static struct json_object * -_cee_json_append (struct json_object *json, ...) -{ - va_list ap; - - va_start (ap, json); - _cee_json_vappend (json, ap); - va_end (ap); - - return json; -} - -static inline void -_cee_json_append_timestamp (struct json_object *jo) -{ - struct timespec ts; - struct tm *tm; - char stamp[64], zone[16]; - - clock_gettime (CLOCK_REALTIME, &ts); - - tm = localtime (&ts.tv_sec); - - strftime (stamp, sizeof (stamp), "%FT%T", tm); - strftime (zone, sizeof (zone), "%z", tm); - - _cee_json_append (jo, "timestamp", "%s.%lu%s", - stamp, ts.tv_nsec, zone, - NULL); -} - -static inline void -_cee_discover (struct json_object *jo, int priority) -{ - if (cee_sys_settings.flags & LOG_CEE_NODISCOVER) - return; - - _cee_json_append (jo, - "pid", "%d", _find_pid (), - "facility", "%s", _find_facility (), - "priority", "%s", _find_prio (priority), - "program", "%s", cee_sys_settings.ident, - "uid", "%d", _get_uid (), - "gid", "%d", _get_gid (), - "host", "%s", _get_hostname (), - NULL); - - if (cee_sys_settings.flags & LOG_CEE_NOTIME) - return; - - _cee_json_append_timestamp (jo); -} - -static struct json_object * -_cee_vformat (struct json_object *jo, int format_version, - int priority, const char *msg_format, - va_list ap) -{ - char *value; - - if (vasprintf (&value, msg_format, ap) == -1) - abort (); - json_object_object_add (jo, "msg", json_object_new_string (value)); - free (value); - - if (format_version > 0) - _cee_json_vappend (jo, ap); - - _cee_discover (jo, priority); - - return jo; -} - -static inline const char * -_cee_vformat_str (struct json_object *jo, int format_version, - int priority, const char *msg_format, - va_list ap) -{ - return json_object_to_json_string (_cee_vformat (jo, format_version, - priority, msg_format, - ap)); -} - -/** Public API **/ -char * -cee_format (int priority, const char *msg_format, ...) -{ - char *result; - va_list ap; - - va_start (ap, msg_format); - result = cee_vformat (priority, msg_format, ap); - va_end (ap); - - return result; -} - -char * -cee_vformat (int priority, const char *msg_format, va_list ap) -{ - struct json_object *jo = json_object_new_object (); - char *result; - - result = strdup (_cee_vformat_str (jo, 1, priority, msg_format, ap)); - json_object_put (jo); - return result; -} - -void -cee_syslog (int priority, const char *msg_format, ...) -{ - va_list ap; - - va_start (ap, msg_format); - cee_vsyslog (priority, msg_format, ap); - va_end (ap); -} - -static inline void -_cee_vsyslog (int format_version, int priority, - const char *msg_format, va_list ap) -{ - struct json_object *jo; - - if (!(cee_sys_settings.mask & priority)) - return; - - jo = _cee_vformat (json_object_new_object (), format_version, - priority, msg_format, ap); -#if __USE_FORTIFY_LEVEL > 0 - old_syslog_chk (priority, __USE_FORTIFY_LEVEL - 1, "@cee:%s", - json_object_to_json_string (jo)); -#else - old_syslog (priority, "@cee:%s", json_object_to_json_string (jo)); -#endif - json_object_put (jo); -} - -void -cee_vsyslog (int priority, const char *msg_format, va_list ap) -{ - _cee_vsyslog (1, priority, msg_format, ap); -} - -void -cee_legacy_vsyslog (int priority, const char *msg_format, va_list ap) -{ - _cee_vsyslog (0, priority, msg_format, ap); -} - -void -cee_legacy_syslog (int priority, const char *msg_format, ...) -{ - va_list ap; - - va_start (ap, msg_format); - cee_legacy_vsyslog (priority, msg_format, ap); - va_end (ap); -} - -int -cee_setlogmask (int mask) -{ - if (mask != 0) - cee_sys_settings.mask = mask; - return old_setlogmask (mask); -} - -#if __USE_FORTIFY_LEVEL > 0 -void -__syslog_chk (int __pri, int __flag, __const char *__fmt, ...) -{ - va_list ap; - - va_start (ap, __fmt); - cee_legacy_vsyslog (__pri, __fmt, ap); - va_end (ap); -} - -void -__vsyslog_chk (int __pri, int __flag, __const char *__fmt, va_list ap) -{ - cee_legacy_vsyslog (__pri, __fmt, ap); -} -#endif - -void openlog (const char *ident, int option, int facility) - __attribute__((alias ("cee_openlog"))); - -void syslog (int priority, const char *msg_format, ...) - __attribute__((alias ("cee_legacy_syslog"))); - -void vsyslog (int priority, const char *msg_format, va_list ap) - __attribute__((alias ("cee_legacy_vsyslog"))); - -int setlogmask (int mask) - __attribute__((alias ("cee_setlogmask"))); diff --git a/lib/cee-syslog.h b/lib/cee-syslog.h deleted file mode 100644 index 0725230..0000000 --- a/lib/cee-syslog.h +++ /dev/null @@ -1,51 +0,0 @@ -/* cee-syslog.h -- CEE-enhanced syslog API. - * - * 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. - */ - -#ifndef CEE_SYSLOG_H -#define CEE_SYSLOG_H 1 - -#include -#include - -#define LOG_CEE_NODISCOVER 0x0040 -#define LOG_CEE_NOCACHE 0x0080 -#define LOG_CEE_NOCACHE_UID 0x0100 -#define LOG_CEE_NOTIME 0x0200 - -char *cee_format (int priority, const char *msg_format, ...); -char *cee_vformat (int priority, const char *msg_format, va_list ap); - -void cee_openlog (const char *ident, int option, int facility); -int cee_setlogmask (int mask); - -void cee_syslog (int priority, const char *msg_format, ...); -void cee_vsyslog (int priority, const char *msg_format, va_list ap); - -void cee_legacy_syslog (int priority, const char *msg_format, ...); -void cee_legacy_vsyslog (int priority, const char *msg_format, va_list ap); - -#endif diff --git a/lib/libcee-syslog.3 b/lib/libcee-syslog.3 deleted file mode 100644 index f8e9dd2..0000000 --- a/lib/libcee-syslog.3 +++ /dev/null @@ -1,211 +0,0 @@ -.\" cee-syslog.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 CEE_SYSLOG 3 2012-03-22 "cee\-syslog" "CEE\-enhanced syslog Manual" - -.SH NAME -cee_openlog, cee_syslog, cee_vsyslog, cee_legacy_syslog, -cee_legacy_vsyslog \- send CEE-enhanced messages to the system logger -.br -cee_format, cee_vformat \- format CEE\-enhanced messages, without -sending them to the system logger - -.SH SYNOPSIS -.B #include -.sp -.BI "void cee_openlog(const char *" ident ", int " option ", int " facility ); -.br - -.br -.BI "void cee_syslog(int " priority ", const char *" format ", ...);" -.br -.BI "void cee_vsyslog(int " priority ", const char *" format ", va_list " ap ); -.br - -.br -.BI "void cee_legacy_syslog(int " priority ", const char *" format ", ...);" -.br -.BI "void cee_legacy_vsyslog(int " priority ", const char *" format ", va_list " ap ); -.br - -.br -.BI "char *cee_format(int " priority ", const char *" format ", ...);" -.br -.BI "char *cee_vformat(int " priority ", const char *" format ", va_list " ap ); - -.SH DESCRIPTION -.BR cee_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 cee_legacy_syslog () -and -.BR cee_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 cee_syslog () -and -.BR cee_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 cee_format () -and -.BR cee_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_CEE_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 cee_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 cee_openlog (). -.TP -.IR uid " and " gid -The user and group ID of the process, determined at -.BR cee_openlog () -time by default, unless caching is disabled. -.TP -.I host -The name of the originating host, determined at -.BR cee_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_CEE_NOTIME -option flag at -.BR cee_openlog () -time. -.PP - -.SH "EXTRA OPTION FLAGS" -The -.I option -argument to -.BR cee_openlog () -is an OR of any of the original -.BR openlog () -flags, and these: -.TP 15 -.B LOG_CEE_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_CEE_NOCACHE -When automatic discovery is enabled, disable caching certain -properties, that might change between the call to -.BR openlog () -and the -.BR cee_syslog () -invocation. -.TP -.B LOG_CEE_NOCACHE_UID -Disable caching the -.IR uid " and " gid -caching when automatic discovery is enabled, but do cache the rest. -.TP -.B LOG_CEE_NOTIME -Do not add a high\-precision timestamp to the generated message when -automatic discovery is enabled. -.PP - -.SH EXAMPLES -.nf - - cee_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 libcee\-syslog -project, and is available under the same 2-clause BSD license as the -rest of the project. diff --git a/lib/libcee-syslog.ld b/lib/libcee-syslog.ld deleted file mode 100644 index 8f5d442..0000000 --- a/lib/libcee-syslog.ld +++ /dev/null @@ -1,17 +0,0 @@ -LIBCEE_SYSLOG_0.1.0 { - global: - # Our own symbols - cee_format; - cee_vformat; - cee_syslog; - cee_vsyslog; - cee_legacy_syslog; - cee_legacy_vsyslog; - cee_openlog; - cee_setlogmask; - - local: - # Inherited from elsewhere, but should not be exported - facilitynames; - prioritynames; -}; diff --git a/lib/libcee-syslog.pc.in b/lib/libcee-syslog.pc.in deleted file mode 100644 index 21a09ec..0000000 --- a/lib/libcee-syslog.pc.in +++ /dev/null @@ -1,10 +0,0 @@ -prefix=@prefix@ -exec_prefix=@exec_prefix@ -libdir=@libdir@ -includedir=@includedir@ - -Name: libcee-syslog -Version: @VERSION@ -Description: CEE-enhanced syslog() API -URL: https://github.com/algernon/libcee-syslog -Libs: -L${libdir} -lcee-syslog diff --git a/lib/libumberlog.ld b/lib/libumberlog.ld new file mode 100644 index 0000000..8cd48e7 --- /dev/null +++ b/lib/libumberlog.ld @@ -0,0 +1,17 @@ +LIBUMBERLOG_0.1.0 { + global: + # Our own symbols + ul_format; + ul_vformat; + ul_syslog; + ul_vsyslog; + ul_legacy_syslog; + ul_legacy_vsyslog; + ul_openlog; + ul_setlogmask; + + local: + # Inherited from elsewhere, but should not be exported + facilitynames; + prioritynames; +}; diff --git a/lib/libumberlog.pc.in b/lib/libumberlog.pc.in new file mode 100644 index 0000000..691d1df --- /dev/null +++ b/lib/libumberlog.pc.in @@ -0,0 +1,10 @@ +prefix=@prefix@ +exec_prefix=@exec_prefix@ +libdir=@libdir@ +includedir=@includedir@ + +Name: libumberlog +Version: @VERSION@ +Description: CEE-enhanced syslog() API +URL: https://github.com/algernon/libumberlog +Libs: -L${libdir} -lumberlog 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 +.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. diff --git a/lib/umberlog.c b/lib/umberlog.c new file mode 100644 index 0000000..151b333 --- /dev/null +++ b/lib/umberlog.c @@ -0,0 +1,376 @@ +/* umberlog.c -- CEE-enhanced syslog API. + * + * 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. + */ + +#define _GNU_SOURCE 1 +#define SYSLOG_NAMES 1 + +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include + +#include "umberlog.h" + +#if __USE_FORTIFY_LEVEL > 0 +static void (*old_syslog_chk) (); +#else +static void (*old_syslog) (); +#endif + +static void (*old_openlog) (); +static int (*old_setlogmask) (); + +static void ul_init (void) __attribute__((constructor)); + +static __thread struct +{ + int mask; + int flags; + + int facility; + pid_t pid; + uid_t uid; + gid_t gid; + const char *ident; + char hostname[HOST_NAME_MAX + 1]; +} ul_sys_settings; + +static void +ul_init (void) +{ +#if __USE_FORTIFY_LEVEL > 0 + old_syslog_chk = dlsym (RTLD_NEXT, "__syslog_chk"); +#else + old_syslog = dlsym (RTLD_NEXT, "syslog"); +#endif + old_openlog = dlsym (RTLD_NEXT, "openlog"); + old_setlogmask = dlsym (RTLD_NEXT, "setlogmask"); +} + +void +ul_openlog (const char *ident, int option, int facility) +{ + old_openlog (ident, option, facility); + ul_sys_settings.mask = old_setlogmask (0); + ul_sys_settings.flags = option; + ul_sys_settings.facility = facility; + ul_sys_settings.pid = getpid (); + ul_sys_settings.gid = getgid (); + ul_sys_settings.uid = getuid (); + ul_sys_settings.ident = ident; + + gethostname (ul_sys_settings.hostname, HOST_NAME_MAX); +} + +/** HELPERS **/ +static const char * +_find_facility (void) +{ + int i = 0; + + while (facilitynames[i].c_name != NULL && + facilitynames[i].c_val != ul_sys_settings.facility) + i++; + + if (facilitynames[i].c_val == ul_sys_settings.facility) + return facilitynames[i].c_name; + return ""; +} + +static const char * +_find_prio (int prio) +{ + int i = 0; + + while (prioritynames[i].c_name != NULL && + prioritynames[i].c_val != prio) + i++; + + if (prioritynames[i].c_val == prio) + return prioritynames[i].c_name; + return ""; +} + +static inline pid_t +_find_pid (void) +{ + if (ul_sys_settings.flags & LOG_UL_NOCACHE) + return getpid (); + else + return ul_sys_settings.pid; +} + +static inline uid_t +_get_uid (void) +{ + if (ul_sys_settings.flags & LOG_UL_NOCACHE || + ul_sys_settings.flags & LOG_UL_NOCACHE_UID) + return getuid (); + else + return ul_sys_settings.uid; +} + +static inline uid_t +_get_gid (void) +{ + if (ul_sys_settings.flags & LOG_UL_NOCACHE || + ul_sys_settings.flags & LOG_UL_NOCACHE_UID) + return getgid (); + else + return ul_sys_settings.gid; +} + +static inline const char * +_get_hostname (void) +{ + if (ul_sys_settings.flags & LOG_UL_NOCACHE) + gethostname (ul_sys_settings.hostname, HOST_NAME_MAX); + return ul_sys_settings.hostname; +} + +static struct json_object * +_ul_json_vappend (struct json_object *json, va_list ap) +{ + char *key; + + while ((key = (char *)va_arg (ap, char *)) != NULL) + { + char *fmt = (char *)va_arg (ap, char *); + char *value; + + if (vasprintf (&value, fmt, ap) == -1) + abort (); + json_object_object_add (json, key, json_object_new_string (value)); + free (value); + } + return json; +} + +static struct json_object * +_ul_json_append (struct json_object *json, ...) +{ + va_list ap; + + va_start (ap, json); + _ul_json_vappend (json, ap); + va_end (ap); + + return json; +} + +static inline void +_ul_json_append_timestamp (struct json_object *jo) +{ + struct timespec ts; + struct tm *tm; + char stamp[64], zone[16]; + + clock_gettime (CLOCK_REALTIME, &ts); + + tm = localtime (&ts.tv_sec); + + strftime (stamp, sizeof (stamp), "%FT%T", tm); + strftime (zone, sizeof (zone), "%z", tm); + + _ul_json_append (jo, "timestamp", "%s.%lu%s", + stamp, ts.tv_nsec, zone, + NULL); +} + +static inline void +_ul_discover (struct json_object *jo, int priority) +{ + if (ul_sys_settings.flags & LOG_UL_NODISCOVER) + return; + + _ul_json_append (jo, + "pid", "%d", _find_pid (), + "facility", "%s", _find_facility (), + "priority", "%s", _find_prio (priority), + "program", "%s", ul_sys_settings.ident, + "uid", "%d", _get_uid (), + "gid", "%d", _get_gid (), + "host", "%s", _get_hostname (), + NULL); + + if (ul_sys_settings.flags & LOG_UL_NOTIME) + return; + + _ul_json_append_timestamp (jo); +} + +static struct json_object * +_ul_vformat (struct json_object *jo, int format_version, + int priority, const char *msg_format, + va_list ap) +{ + char *value; + + if (vasprintf (&value, msg_format, ap) == -1) + abort (); + json_object_object_add (jo, "msg", json_object_new_string (value)); + free (value); + + if (format_version > 0) + _ul_json_vappend (jo, ap); + + _ul_discover (jo, priority); + + return jo; +} + +static inline const char * +_ul_vformat_str (struct json_object *jo, int format_version, + int priority, const char *msg_format, + va_list ap) +{ + return json_object_to_json_string (_ul_vformat (jo, format_version, + priority, msg_format, + ap)); +} + +/** Public API **/ +char * +ul_format (int priority, const char *msg_format, ...) +{ + char *result; + va_list ap; + + va_start (ap, msg_format); + result = ul_vformat (priority, msg_format, ap); + va_end (ap); + + return result; +} + +char * +ul_vformat (int priority, const char *msg_format, va_list ap) +{ + struct json_object *jo = json_object_new_object (); + char *result; + + result = strdup (_ul_vformat_str (jo, 1, priority, msg_format, ap)); + json_object_put (jo); + return result; +} + +void +ul_syslog (int priority, const char *msg_format, ...) +{ + va_list ap; + + va_start (ap, msg_format); + ul_vsyslog (priority, msg_format, ap); + va_end (ap); +} + +static inline void +_ul_vsyslog (int format_version, int priority, + const char *msg_format, va_list ap) +{ + struct json_object *jo; + + if (!(ul_sys_settings.mask & priority)) + return; + + jo = _ul_vformat (json_object_new_object (), format_version, + priority, msg_format, ap); +#if __USE_FORTIFY_LEVEL > 0 + old_syslog_chk (priority, __USE_FORTIFY_LEVEL - 1, "@cee:%s", + json_object_to_json_string (jo)); +#else + old_syslog (priority, "@cee:%s", json_object_to_json_string (jo)); +#endif + json_object_put (jo); +} + +void +ul_vsyslog (int priority, const char *msg_format, va_list ap) +{ + _ul_vsyslog (1, priority, msg_format, ap); +} + +void +ul_legacy_vsyslog (int priority, const char *msg_format, va_list ap) +{ + _ul_vsyslog (0, priority, msg_format, ap); +} + +void +ul_legacy_syslog (int priority, const char *msg_format, ...) +{ + va_list ap; + + va_start (ap, msg_format); + ul_legacy_vsyslog (priority, msg_format, ap); + va_end (ap); +} + +int +ul_setlogmask (int mask) +{ + if (mask != 0) + ul_sys_settings.mask = mask; + return old_setlogmask (mask); +} + +#if __USE_FORTIFY_LEVEL > 0 +void +__syslog_chk (int __pri, int __flag, __const char *__fmt, ...) +{ + va_list ap; + + va_start (ap, __fmt); + ul_legacy_vsyslog (__pri, __fmt, ap); + va_end (ap); +} + +void +__vsyslog_chk (int __pri, int __flag, __const char *__fmt, va_list ap) +{ + ul_legacy_vsyslog (__pri, __fmt, ap); +} +#endif + +void openlog (const char *ident, int option, int facility) + __attribute__((alias ("ul_openlog"))); + +void syslog (int priority, const char *msg_format, ...) + __attribute__((alias ("ul_legacy_syslog"))); + +void vsyslog (int priority, const char *msg_format, va_list ap) + __attribute__((alias ("ul_legacy_vsyslog"))); + +int setlogmask (int mask) + __attribute__((alias ("ul_setlogmask"))); diff --git a/lib/umberlog.h b/lib/umberlog.h new file mode 100644 index 0000000..f91fe67 --- /dev/null +++ b/lib/umberlog.h @@ -0,0 +1,51 @@ +/* umberlog.h -- CEE-enhanced syslog API. + * + * 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. + */ + +#ifndef UMBERLOG_H +#define UMBERLOG_H 1 + +#include +#include + +#define LOG_UL_NODISCOVER 0x0040 +#define LOG_UL_NOCACHE 0x0080 +#define LOG_UL_NOCACHE_UID 0x0100 +#define LOG_UL_NOTIME 0x0200 + +char *ul_format (int priority, const char *msg_format, ...); +char *ul_vformat (int priority, const char *msg_format, va_list ap); + +void ul_openlog (const char *ident, int option, int facility); +int ul_setlogmask (int mask); + +void ul_syslog (int priority, const char *msg_format, ...); +void ul_vsyslog (int priority, const char *msg_format, va_list ap); + +void ul_legacy_syslog (int priority, const char *msg_format, ...); +void ul_legacy_vsyslog (int priority, const char *msg_format, va_list ap); + +#endif -- cgit From 632e1a5d657a1ebdc15fc0571ccd958a27e838cc Mon Sep 17 00:00:00 2001 From: Gergely Nagy Date: Fri, 23 Mar 2012 10:47:10 +0100 Subject: Convert the manual page from roff to rst. The advantage of ReStructuredText is that this allows converting the same source into different formats, such as HTML. Signed-off-by: Gergely Nagy --- lib/Makefile.am | 2 - lib/umberlog.3 | 211 ------------------------------------------------------- lib/umberlog.rst | 139 ++++++++++++++++++++++++++++++++++++ 3 files changed, 139 insertions(+), 213 deletions(-) delete mode 100644 lib/umberlog.3 create mode 100644 lib/umberlog.rst (limited to 'lib') diff --git a/lib/Makefile.am b/lib/Makefile.am index a208bc2..030ae4e 100644 --- a/lib/Makefile.am +++ b/lib/Makefile.am @@ -14,5 +14,3 @@ libumberlog_include_HEADERS = umberlog.h pkgconfigdir = $(libdir)/pkgconfig pkgconfig_DATA = libumberlog.pc - -man3_MANS = umberlog.3 diff --git a/lib/umberlog.3 b/lib/umberlog.3 deleted file mode 100644 index ee7be30..0000000 --- a/lib/umberlog.3 +++ /dev/null @@ -1,211 +0,0 @@ -.\" 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 -.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. diff --git a/lib/umberlog.rst b/lib/umberlog.rst new file mode 100644 index 0000000..036341b --- /dev/null +++ b/lib/umberlog.rst @@ -0,0 +1,139 @@ +======== +umberlog +======== + +-------------------------------------- +CEE-enhanced syslog message generation +-------------------------------------- + +:Author: Gergely Nagy +:Date: 2012-03-23 +:Manual section: 1 +:Manual group: CEE-enhanced syslog Manual + +SYNOPSIS +======== + +:: + + #include + + void ul_openlog (const char *ident, int option, int facility); + + void ul_syslog (int priority, const char *format, ....); + void ul_vsyslog (int priority, const char *format, va_list ap); + + void ul_legacy_syslog (int priority, const char *format, ...); + void ul_legacy_vsyslog (int priority, const char *format, va_list ap); + + void ul_format (int priority, const char *format, ...); + void ul_vformat (int priority, const char *format, va_list ap); + +DESCRIPTION +=========== + +**ul_openlog()** (also aliased to **openlog()**) is a wrapper around +the original **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. + +**ul_legacy_syslog()** and **ul_legacy_vsyslog()** are both thin +layers over the original **syslog()** and **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. + +_syslog()** and **ul_vsyslog()** are two new functions provided by the +library, that have similar interface to the legacy **syslog()** +functions, but they can be used to add arbitrary key-value pairs to +the emitted message. After the *msg_format* format string, and any +other parameters it refers to, there must be a NULL-terminated list of +*key*, *value format*, *format parameters*. Each of these pairs, +constructed from the *key* and the **printf(3)**-style *value format* +will be added to the generated message. + +**ul_format()** and **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. + +CEE PAYLOAD +=========== + +All of the improved **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 *msg* +field, and any additional fields put into the same structure. + +By default, unless the **LOG_UL_NODISCOVER** option flag is set, all +of these functions will also add a few automatically discovered fields +into the payload: + +*pid* + The process ID of the program, as returned by **getpid()** The value + of this is - by default - determined at the time of calling + **ul_openlog()**, but if caching is disabled, it will be rechecked + every time. + +*facility*, *priority* + The syslog facility and priority as a text string. + +*program* + The identification set at the time of **ul_openlog()**. + +*uid*, *gid* + The user and group ID of the process, determined at **ul_openlog()** + time by default, unless caching is disabled. + +*host* + The name of the originating host, determined at **ul_openlog()** + time by default, using **gethostname()**. + +*timestamp* + High-precision timestamp, in textual format. Included by default, + but can be controlled by the **LOG_UL_NOTIME** option flag at + **ul_openlog()** time. + +EXTRA OPTION FLAGS +================== + +The *option* argument to **ul_openlog()** is an OR of any of the +original **openlog()** flags, and these: + +LOG_UL_NODISCOVER + Disable all automatic discovery, and only include the *message*, + and any specified *key-value* pairs in the generated message. + +LOG_UL_NOCACHE + When automatic discovery is enabled, disable caching certain + properties, that might change between the call to **openlog()** and + the **ul_syslog()** invocation. + +LOG_UL_NOCACHE_UID + Disable the *uid* and *gid* caching when automatic discovery is + enabled, but do cache the rest. + +LOG_UL_NOTIME + Do not add a high-precision timestamp to the generated message when + automatic discovery is enabled. + +EXAMPLES +======== + +:: + + ul_syslog(LOG_NOTICE, "Logged in user: %s", username, + "service", "%s", service, + "auth-method", "%s", auth_method, + "sessionid", "%d", session_id, + NULL); + +SEE ALSO +======== +**syslog(1)** + +COPYRIGHT +========= + +This page is part of the *libumberlog* project, and is available under +the same 2-clause BSD license as the rest of the project. -- cgit