1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
|
.\" 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.
|
