diff options
Diffstat (limited to 'lib/libcee-syslog.3')
| -rw-r--r-- | lib/libcee-syslog.3 | 211 |
1 files changed, 0 insertions, 211 deletions
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 <cee/cee\-syslog.h> -.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. |