« back to all changes in this revision
Viewing changes to doc/sgml/syslog-ng.txt
- browse files at revision 7
- compare with another revision
- download diff
- download tarball
- view history from revision 7
- Committer: Bazaar Package Importer
- Author(s): SZALAY Attila
- Date: 2006-05-25 11:21:50 UTC
- mfrom: (1.1.5 upstream)
- Revision ID: james.westby@ubuntu.com-20060525112150-b18srkxcrz980xi9
Tags: 1.9.11-1
* New upstream version
- Fixed log facility and priority detecting. (Closes: #350120, #350344, #357071, #367256)
* Added bison to Build-Dependency. (Closes: #368765)
- Fixed log facility and priority detecting. (Closes: #350120, #350344, #357071, #367256)
* Added bison to Build-Dependency. (Closes: #368765)
added
removed
doc/sgml/syslog-ng.txt
1
syslog-ng reference manual
2
3
Bal zs Scheidler
4
5
Copyright © 1999-2004 Balázs Scheidler
6
7
This manual is free software; you may redistribute it and/or modify it under
8
the terms of the GNU General Public License as published by the Free Software
9
Foundation; either version 2, or (at your option) any later version.
10
11
This is distributed in the hope that it will be useful, but without any
12
warranty; without even the implied warranty of merchantability or fitness for a
13
particular purpose. See the GNU General Public License for more details.
14
15
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
16
17
Table of Contents
18
1. Introduction to syslog-ng
19
2. Message paths
20
21
Sources
22
Filters
23
Destinations
24
Log paths
25
Options
26
27
3. Reference
28
29
Source drivers
30
31
internal()
32
unix-stream() and unix-dgram()
33
tcp() and udp()
34
file()
35
pipe()
36
sun-streams() driver
37
38
Destination drivers
39
40
file()
41
pipe()
42
unix-stream() & unix-dgram()
43
udp() & tcp()
44
usertty()
45
program()
46
47
Filter functions
48
Options
49
50
4. Performance tuning in syslog-ng
51
52
Setting garbage collector parameters
53
54
gc_idle_threshold()
55
gc_busy_threshold()
56
57
Setting output queue size
58
Setting sync parameter
59
60
List of Tables
61
2-1. Communication method between syslogd and its clients
62
2-2. Available source drivers in syslog-ng
63
2-3. Available destination drivers in syslog-ng
64
2-4. Log statement flags
65
3-1. Available options for unix-stream & unix-dgram
66
3-2. Available options for udp() & tcp()
67
3-3. Available options for file
68
3-4. Available options for pipe
69
3-5. Available options for sun-streams
70
3-6. Available macros in filename expansion
71
3-7. Available options for file()
72
3-8. Available options for pipe()
73
3-9. Available options for unix-stream() & unix-dgram()
74
3-10. Available options for udp() & tcp()
75
3-11. Additional options for tcp()
76
3-12. Available options for usertty()
77
3-13. Available options for program()
78
3-14. Available filter functions in syslog-ng
79
3-15. List of supported global options in syslog-ng
80
81
List of Examples
82
2-1. Source statement on a Linux based operating system
83
2-2. A filter statement finding the messages containing the word deny coming
84
from the host blurp
85
3-1. Using the internal() driver
86
3-2. Using the unix-stream() and unix-dgram() drivers
87
3-3. Using the udp() and tcp() drivers
88
3-4. example script to feed a growing logfile into syslog-ng
89
3-5. Using the file() driver
90
3-6. Using the pipe() driver
91
3-7. Using the sun-streams() driver
92
3-8. Using the file() driver
93
3-9. Using the file() driver with macros in the file name and a template for
94
the message
95
3-10. Using the pipe() driver
96
3-11. Using the unix-stream() driver
97
3-12. Using the tcp() driver
98
3-13. Using the usertty() driver
99
3-14. Using the program() destination driver
100
101
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
102
103
Chapter 1. Introduction to syslog-ng
104
105
One of the most neglected area of Unix is handling system events. Daily checks
106
for system messages is crucial for the security and health conditions of a
107
computer system.
108
109
System logs contain much "noise" - messages which have no importance - and on
110
the contrary important events, which should not be lost in the load of
111
messages. With current tools it's difficult to select which messages we are
112
interested in.
113
114
A message is sent to different destinations based on the assigned facility/
115
priority pair. There are 12+8 (12 real and 8 local) predefined facilities
116
(mail, news, auth etc.), and 8 different priorities (ranging from alert to
117
debug).
118
119
One problem is that there are facilities which are too general (daemon), and
120
these facilities are used by many programs, even if they do not relate each
121
other. It is difficult to find the interesting bits from the enourmous amount
122
of messages.
123
124
A second problem is that there are very few programs which allow setting their
125
"facility code" to log under. It's at best a compile time parameter.
126
127
So using facilities as a means of filtering is not the best way. For it to be a
128
good solution would require runtime option for all applications, which
129
specifies the log facility to log under, and the ability to create new
130
facilities in syslogd. Neither of these are available, and the first is neither
131
feasible.
132
133
One of the design principles of syslog-ng was to make message filtering much
134
more finegrained. syslog-ng is able to filter messages based on the contents of
135
messages in addition to the priority/facility pair. This way only the messages
136
we are really interested in get to a specific destination. Another design
137
principle was to make logforwarding between firewalled segments easier: long
138
hostname format, which makes it easy to find the originating and chain of
139
forwarding hosts even if a log message traverses several computers. And last
140
principle was a clean and powerful configuration file format.
141
142
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
143
144
Chapter 2. Message paths
145
146
In syslog-ng a message path (or message route) consist of one or more sources,
147
one or more filtering rules and one or more destinations. A message is entered
148
to syslog-ng in one of its sources, if that message matches the filtering rules
149
it goes out using the destinations. Note that a message goes to _all_ matching
150
destinations by default, although this behaviour can be changed.
151
152
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
153
154
Sources
155
156
A source is a collection of source drivers, which collect messages using a
157
given method. For instance there's a source driver for AF_UNIX, SOCK_STREAM
158
style sockets, which is used by the Linux syslog() call.
159
160
To declare a source, you'll need to use the source statement in the
161
configuration file with the following syntax:
162
163
source <identifier> { source-driver(params); source-driver(params); ... };
164
165
166
The identifier has to uniquely identify this given source and of course may not
167
clash with any of the reserved words (in case you had a nameclash, simply
168
enclose the identifier in quotation marks)
169
170
You can control exactly which drivers are used to gather log messages, thus
171
you'll have to know how your system and its native syslogd communicate. Here's
172
a introduction to the inner workings of syslogd on some of the platforms I
173
tested:
174
175
Table 2-1. Communication method between syslogd and its clients
176
177
┌──────────┬──────────────────────────────────────────────────────────────────┐
178
│ Platform │ Method │
179
├──────────┼──────────────────────────────────────────────────────────────────┤
180
│Linux │A SOCK_STREAM unix socket named /dev/log │
181
├──────────┼──────────────────────────────────────────────────────────────────┤
182
│BSD │A SOCK_DGRAM unix socket named /var/run/log │
183
│flavors │ │
184
├──────────┼──────────────────────────────────────────────────────────────────┤
185
│Solaris │ │
186
│(2.5 or │An SVR4 style STREAMS device named /dev/log │
187
│below) │ │
188
├──────────┼──────────────────────────────────────────────────────────────────┤
189
│Solaris │In addition to the STREAMS device used in versions below 2.6, uses│
190
│(2.6 or │a new multithreaded IPC method called door. By default the door │
191
│above) │used by syslogd is /etc/.syslog_door │
192
└──────────┴──────────────────────────────────────────────────────────────────┘
193
194
Each possible communication mechanism has the corresponding source driver in
195
syslog-ng. For instance to open a unix socket with SOCK_DGRAM style
196
communication you use the driver unix-dgram, the same with SOCK_STREAM style -
197
as used under Linux - is called unix-stream.
198
199
Example 2-1. Source statement on a Linux based operating system
200
201
source src { unix-stream("/dev/log"); internal(); udp(ip(0.0.0.0) port(514)); };
202
203
204
Each driver may take parameters, some of them are required, others are
205
optional. The required parameters are positional, meaning that they must be
206
specified in a defined order. A unix-stream() driver has a single required
207
argument, the name of the socket to listen to, and several optional parameters,
208
which follow the socket name. Optional arguments can be specified in any order
209
and must have the form option(value).
210
211
Table 2-2. Available source drivers in syslog-ng
212
213
┌────────────────────┬────────────────────────────────────────────────────────┐
214
│ Name │ Description │
215
├────────────────────┼────────────────────────────────────────────────────────┤
216
│internal() │Messages generated internally in syslog-ng │
217
├────────────────────┼────────────────────────────────────────────────────────┤
218
│unix-stream() │Opens the specified unix socket in SOCK_STREAM mode, and│
219
│ │listens for messages. │
220
├────────────────────┼────────────────────────────────────────────────────────┤
221
│unix-dgram() │Opens the specified unix socket in SOCK_DGRAM mode, and │
222
│ │listens for messages. │
223
├────────────────────┼────────────────────────────────────────────────────────┤
224
│file() │Opens the specified file, and reads messages. │
225
├────────────────────┼────────────────────────────────────────────────────────┤
226
│pipe(), fifo │Opens the specified named pipe and reads messages │
227
├────────────────────┼────────────────────────────────────────────────────────┤
228
│udp() │Listens on the specified UDP port for messages. │
229
├────────────────────┼────────────────────────────────────────────────────────┤
230
│tcp() │Listens on the specified TCP port for messages. │
231
├────────────────────┼────────────────────────────────────────────────────────┤
232
│sun-stream(), │Opens the specified STREAMS device on Solaris systems, │
233
│sun-streams() │and reads messages. │
234
└────────────────────┴────────────────────────────────────────────────────────┘
235
236
For a complete descriptions on the above drivers, see Chapter 3
237
238
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
239
240
Filters
241
242
Filters perform log routing inside syslog-ng. You can write a boolean
243
expression using internal functions, which has to evaluate to true for the
244
message to pass.
245
246
Filters have also a uniquely identifying name, so you can refer to filters in
247
your log statements.
248
249
Syntax for the filter statement:
250
251
filter <identifier> { expression; };
252
253
254
An expression may contain parentheses, the boolean operators "and", "or" and
255
"not", and any of the functions listen in Table 3-14.
256
257
Example 2-2. A filter statement finding the messages containing the word deny
258
coming from the host blurp
259
260
filter f_blurp_deny { host("blurp") and match("deny"); };
261
262
263
For a complete description on the above functions, see Chapter 3.
264
265
In earlier revisions of syslog-ng there was a special filter identifier,
266
"DEFAULT", which matched all not-yet-matched messages. This could make your
267
configuration much simpler and easier to manage. This feature was removed in
268
syslog-ng 1.5.x, and a more powerful idea was introduced. For more details
269
consult the Section called Log paths.
270
271
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
272
273
Destinations
274
275
A destination is where log is sent if filtering rules match. Similarly to
276
sources, destinations are comprised of one or more drivers, each of which
277
define how messages are handled. To declare a destination in the configuration
278
file, you'll need a destination statement, whose syntax is as following:
279
280
destination <identifier> { destination-driver(params); destination-driver(params); ... };
281
282
283
Table 2-3. Available destination drivers in syslog-ng
284
285
┌────────────┬────────────────────────────────────────────────────────────────┐
286
│ Name │ Description │
287
├────────────┼────────────────────────────────────────────────────────────────┤
288
│file() │Writes messages to the given file │
289
├────────────┼────────────────────────────────────────────────────────────────┤
290
│fifo(), pipe│Writes messages to the given named pipe │
291
│() │ │
292
├────────────┼────────────────────────────────────────────────────────────────┤
293
│unix-stream │Sends messages to the given unix socket in SOCK_STREAM style │
294
│() │(Linux) │
295
├────────────┼────────────────────────────────────────────────────────────────┤
296
│unix-dgram()│Sends messages to the given unix socket in SOCK_DGRAM style │
297
│ │(BSD) │
298
├────────────┼────────────────────────────────────────────────────────────────┤
299
│udp() │Sends messages to specified host and UDP port │
300
├────────────┼────────────────────────────────────────────────────────────────┤
301
│tcp() │Sends messages to specified host and TCP port │
302
├────────────┼────────────────────────────────────────────────────────────────┤
303
│usertty() │Sends messages to specified user if logged in │
304
├────────────┼────────────────────────────────────────────────────────────────┤
305
│program() │Forks and launches given program, and sends messages to its │
306
│ │standard input. │
307
└────────────┴────────────────────────────────────────────────────────────────┘
308
For detailed list of the supported drivers, see Chapter 3.
309
310
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
311
312
Log paths
313
314
In the previous chapters we learnt how to define sources, filters and
315
destinations. We'll need to connect those components together, which is
316
accomplished by the log statement. The needed syntax is here:
317
318
log { source(s1); source(s2); ...
319
filter(f1); filter(f2); ...
320
destination(d1); destination(d2); ...
321
flags(flag1[, flag2...]); };
322
323
324
Any message coming from any of the listed sources, matching the all the filters
325
are sent to all listed destinations. Log statements are processed in the order
326
they appear in the config file.
327
328
By default all matching log statements are processed, therefore a single log
329
message might be sent to the same destination several times, given that
330
destination is listed on several log statements.
331
332
This default behaviour can be changed by the flags() parameter.
333
334
Table 2-4. Log statement flags
335
336
┌────────┬────────────────────────────────────────────────────────────────────┐
337
│ Flag │ Description │
338
├────────┼────────────────────────────────────────────────────────────────────┤
339
│ │This flag means that the processing of log statements ends here. │
340
│final │Note that this doesn't necessarily mean that matching messages will │
341
│ │be stored once, as they can be matching log statements processed │
342
│ │prior the current one. │
343
├────────┼────────────────────────────────────────────────────────────────────┤
344
│ │This flag makes a log statement 'fallback'. Being a fallback │
345
│fallback│statement means that only messages not matching any 'non-fallback' │
346
│ │log statements will be dispatched. │
347
├────────┼────────────────────────────────────────────────────────────────────┤
348
│catchall│This flag means that the source of the message is ignored, only the │
349
│ │filters are taken into account when matching messages. │
350
└────────┴────────────────────────────────────────────────────────────────────┘
351
352
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
353
354
Options
355
356
There are several options you can specify, which modifies the behaviour of
357
syslog-ng. For an exact list of possible options see the Chapter 3. The general
358
syntax is here:
359
360
options { option1(params); option2(params); ... };
361
362
363
Each option may have parameters, just like in driver specification.
364
365
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
366
367
Chapter 3. Reference
368
369
This chapter documents the drivers and options you may specify in the
370
configuration file.
371
372
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
373
374
Source drivers
375
376
The following drivers may be used in the source statement, as described in the
377
previous chapter.
378
379
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
380
381
internal()
382
383
All internally generated messages "come" from this special source. If you want
384
warnings, errors and notices from syslog-ng itself, you have to include this
385
source in one of your source statements.
386
387
Declaration: internal()
388
389
390
Syslog-ng will issue a warning upon startup, if this driver is not referenced.
391
392
Example 3-1. Using the internal() driver
393
394
source s_local { internal(); };
395
396
397
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
398
399
unix-stream() and unix-dgram()
400
401
These two drivers behave similarly: they open the given AF_UNIX socket, and
402
start listening on them for messages. unix-stream() is primarily used on Linux,
403
and uses SOCK_STREAM semantics (connection oriented, no messages are lost),
404
unix-dgram() is used on BSDs, and uses SOCK_DGRAM semantics, this may result in
405
lost local messages, if the system is overloaded.
406
407
To avoid denial of service attacks when using connection-oriented protocols,
408
the number of simultaneously accepted connections should be limited. This can
409
be achieved using the max-connections() parameter. The default value of this
410
parameter is quite strict, you might have to increase it on a busy system.
411
412
Both unix-stream and unix-dgram has a single required positional argument,
413
specifying the filename of the socket to create, and several optional
414
parameters.
415
416
NOTE: syslogd on Linux originally was using SOCK_STREAM sockets but this was
417
changed in some distributions to SOCK_DGRAM at around 1999. The change was used
418
as a fix to a possible DoS problem, however I do not think it was a proper
419
solution. On Linux you can choose to use whichever you like as syslog clients
420
automatically detect the socket type being used. My original post to bugtraq
421
from 1999 when the change occurred.
422
423
Declaration:
424
unix-stream(filename [options]);
425
unix-dgram(filename [options]);
426
427
428
The following options can be specified:
429
430
Table 3-1. Available options for unix-stream & unix-dgram
431
432
┌───────────────┬──────┬──────────────────────────────────────────────┬───────┐
433
│ Name │ Type │ Description │Default│
434
├───────────────┼──────┼──────────────────────────────────────────────┼───────┤
435
│owner() │string│Set the uid of the socket. │root │
436
├───────────────┼──────┼──────────────────────────────────────────────┼───────┤
437
│group() │string│Set the gid of the socket. Default: root. │root │
438
├───────────────┼──────┼──────────────────────────────────────────────┼───────┤
439
│ │ │Set the permission mask. For octal numbers │ │
440
│perm() │number│prefix the number with '0', e.g. use 0755 for │0666 │
441
│ │ │rwxr-xr-x. │ │
442
├───────────────┼──────┼──────────────────────────────────────────────┼───────┤
443
│ │yes or│Selects whether to keep connections opened │ │
444
│keep-alive() │no │when syslog-ng is restarted, can be used only │yes │
445
│ │ │with unix-stream(). Default: yes. │ │
446
├───────────────┼──────┼──────────────────────────────────────────────┼───────┤
447
│max-connections│ │Limits the number of simultaneously opened │ │
448
│() │number│connections. Can be used only with unix-stream│10 │
449
│ │ │(). │ │
450
└───────────────┴──────┴──────────────────────────────────────────────┴───────┘
451
452
Example 3-2. Using the unix-stream() and unix-dgram() drivers
453
454
# source declaration on Linux
455
source s_stream { unix-stream("/dev/log" max-connections(10)); };
456
457
# source declaration on BSDs
458
source s_dgram { unix-dgram("/var/run/log"); };
459
460
461
462
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
463
464
tcp() and udp()
465
466
These drivers let you receive messages from the network, and as the name of the
467
drivers show, you can use both UDP and TCP as transport.
468
469
UDP is a simple datagram oriented protocol, which provides "best effort
470
service" to transfer messages between hosts. It may lose messages, and no
471
attempt is made to retransmit such lost messages at the protocol level.
472
473
TCP provides connection-oriented service, which basically means a
474
flow-controlled message pipeline. In this pipeline, each message is
475
acknowledged, and retransmission is done for lost packets. Generally it's safer
476
to use TCP, because lost connections can be detected, and no messages get lost,
477
but traditionally the syslog protocol uses UDP.
478
479
None of tcp() and udp() drivers require positional parameters. By default they
480
bind to 0.0.0.0:514, which means that syslog-ng will listen on all available
481
interfaces, port 514. To limit accepted connections to one interface only, use
482
the localip() parameter as described below.
483
484
Note: NOTE: the tcp port 514 is reserved for use with rshell, so you have
485
to pick another port if you intend to use syslog-ng and rshell at the same
486
time.
487
488
Declaration:
489
tcp([options]);
490
udp([options]);
491
492
493
The following options are valid for udp() and tcp()
494
495
Table 3-2. Available options for udp() & tcp()
496
497
┌───────────────┬──────┬──────────────────────────────────────────────┬───────┐
498
│ Name │ Type │ Description │Default│
499
├───────────────┼──────┼──────────────────────────────────────────────┼───────┤
500
│ip() or localip│ │The IP address to bind to. Note that this is │ │
501
│() │string│not the address where messages are accepted │0.0.0.0│
502
│ │ │from. │ │
503
├───────────────┼──────┼──────────────────────────────────────────────┼───────┤
504
│port() or │number│The port number to bind to. │514 │
505
│localport() │ │ │ │
506
├───────────────┼──────┼──────────────────────────────────────────────┼───────┤
507
│ │yes or│Available for tcp() only, and specifies │ │
508
│keep-alive() │no │whether to close connections upon the receival│yes │
509
│ │ │of a SIGHUP signal. │ │
510
├───────────────┼──────┼──────────────────────────────────────────────┼───────┤
511
│tcp-keep-alive │yes or│Available for tcp() only, and specifies │ │
512
│() │no │whether to enable TCP keep alive messages │no │
513
│ │ │using the SO_KEEPALIVE socket option. │ │
514
├───────────────┼──────┼──────────────────────────────────────────────┼───────┤
515
│max-connections│number│Specifies the maximum number of simultaneous │10 │
516
│() │ │connections. │ │
517
└───────────────┴──────┴──────────────────────────────────────────────┴───────┘
518
519
Example 3-3. Using the udp() and tcp() drivers
520
521
source s_tcp { tcp(ip(127.0.0.1) port(1999) max-connections(10)); };
522
source s_udp { udp(); };
523
524
525
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
526
527
file()
528
529
Usually the kernel presents its messages in a special file (/dev/kmsg on BSDs,
530
/proc/kmsg on Linux), so to read such special files, you'll need the file()
531
driver. Please note that you can't use this driver to follow a file like tail
532
-f does. To feed a growing logfile into syslog-ng (HTTP access.log for
533
instance), use a script like this:
534
535
Example 3-4. example script to feed a growing logfile into syslog-ng
536
537
#!/bin/sh
538
tail -f logfile | logger -p local4.info
539
540
541
The file driver has a single required parameter specifying the file to open and
542
the following options:
543
544
Table 3-3. Available options for file
545
546
┌──────────┬──────┬───────────────────────────────────────────────────┬───────┐
547
│ Name │ Type │ Description │Default│
548
├──────────┼──────┼───────────────────────────────────────────────────┼───────┤
549
│log_prefix│ │The string to prepend log messages. Useful for │empty │
550
│() │string│logging kernel messages as it is not prefixed by │string │
551
│ │ │'kernel:' by default │ │
552
└──────────┴──────┴───────────────────────────────────────────────────┴───────┘
553
554
Declaration:
555
file(filename);
556
557
558
Example 3-5. Using the file() driver
559
560
source s_file { file("/proc/kmsg"); };
561
562
563
Note: NOTE: on Linux, historically the klogd daemon was used to read kernel
564
messages and forward them to the syslogd process. klogd preprocessed kernel
565
messages and replaced addresses with symbolic names (from /boot/
566
System.map), but this method of symbol resolving has been deprecated by the
567
ksymoops utility and similar kernel features. For these reasons it is not
568
recommended to use both klogd and syslog-ng at the same time.
569
570
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
571
572
pipe()
573
574
The pipe driver opens a named pipe with the specified name, and listens for
575
messages. It's used as the native message getting protocol on HP-UX.
576
577
The pipe driver has a single required parameter, specifying the filename of the
578
pipe to open, and the following options:
579
580
Table 3-4. Available options for pipe
581
582
┌────────┬──────┬─────────────────────────────────────────────────────┬───────┐
583
│ Name │ Type │ Description │Default│
584
├────────┼──────┼─────────────────────────────────────────────────────┼───────┤
585
│ │ │Specifies input padding. Some operating systems (such│ │
586
│pad_size│number│as HP-UX) pad all messages to block boundary. This │0 │
587
│() │ │option can be used to specify the block size. (HP-UX │ │
588
│ │ │uses 2048 bytes) │ │
589
└────────┴──────┴─────────────────────────────────────────────────────┴───────┘
590
591
Declaration:
592
pipe(filename);
593
594
595
NOTE: you'll need to create this pipe using mkfifo(1).
596
597
Example 3-6. Using the pipe() driver
598
599
source s_pipe { pipe("/dev/log"); };
600
601
602
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
603
604
sun-streams() driver
605
606
Solaris uses its STREAMS API to send messages to the syslogd process. You'll
607
have to compile syslog-ng with this driver compiled in (see ./configure
608
--help).
609
610
Newer versions of Solaris (2.5.1 and above), uses a new IPC in addition to
611
STREAMS, called door to confirm delivery of a message. Syslog-ng supports this
612
new IPC mechanism with the door() option (see below).
613
614
The sun-streams() driver has a single required argument, specifying the STREAMS
615
device to open and a single option.
616
617
Example 3-7. Using the sun-streams() driver
618
619
source s_stream { sun-streams("/dev/log" door("/etc/.syslog_door"); };
620
621
622
Table 3-5. Available options for sun-streams
623
624
┌─────┬──────┬────────────────────────────────────────────────────────┬───────┐
625
│Name │ Type │ Description │Default│
626
├─────┼──────┼────────────────────────────────────────────────────────┼───────┤
627
│door │string│Specifies the filename of a door to open, needed on │none │
628
│() │ │Solaris above 2.5.1. │ │
629
└─────┴──────┴────────────────────────────────────────────────────────┴───────┘
630
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
631
632
Destination drivers
633
634
Destination drivers output log messages to somewhere outside syslog-ng: a file
635
or a network socket.
636
637
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
638
639
file()
640
641
The file driver is one of the most important destination drivers in syslog-ng.
642
It allows you to output messages to the named file, or as you'll see to a set
643
of files.
644
645
The destination filename may include macros which gets expanded when the
646
message is written, thus a simple file() driver may result in several files to
647
be created. Macros can be included by prefixing the macro name with a '$' sign
648
(without the quotes), just like in Perl/PHP.
649
650
If the expanded filename refers to a directory which doesn't exist, it will be
651
created depending on the create_dirs() setting (both global and a per
652
destination option)
653
654
Warning: since the state of each created file must be tracked by syslog-ng, it
655
consumes some memory for each file. If no new messages are written to a file
656
within 60 seconds (controlled by the time_reap global option), it's closed, and
657
its state is freed.
658
659
Exploiting this, a DoS attack can be mounted against your system. If the number
660
of possible destination files and its needed memory is more than the amount
661
your logserver has.
662
663
The most suspicious macro is $PROGRAM, where the possible variations is quite
664
high, so in untrusted environments $PROGRAM usage should be avoided.
665
666
Table 3-6. Available macros in filename expansion
667
668
┌────────┬────────────────────────────────────────────────────────────────────┐
669
│ Name │ Description │
670
├────────┼────────────────────────────────────────────────────────────────────┤
671
│FACILITY│The name of the facility, the message is tagged as coming from. │
672
├────────┼────────────────────────────────────────────────────────────────────┤
673
│PRIORITY│The priority of the message. │
674
│or LEVEL│ │
675
├────────┼────────────────────────────────────────────────────────────────────┤
676
│TAG │The priority and facility encoded as a 2 digit hexadecimal number. │
677
├────────┼────────────────────────────────────────────────────────────────────┤
678
│ │The priority and facility encoded as a 2-3 digit decimal number in │
679
│PRI │the same format this information is encoded in the syslog protocol │
680
│ │(without <>). │
681
├────────┼────────────────────────────────────────────────────────────────────┤
682
│DATE │ │
683
├────────┼────────────────────────────────────────────────────────────────────┤
684
│FULLDATE│ │
685
├────────┼────────────────────────────────────────────────────────────────────┤
686
│ISODATE │ │
687
├────────┼────────────────────────────────────────────────────────────────────┤
688
│ │The year the message was sent. Time expansion macros can either use │
689
│YEAR │the time specified in the log message, e.g. the time the log message│
690
│ │is sent, or the time the message was received by the log server. │
691
│ │This is controlled by the use_time_recvd() option. │
692
├────────┼────────────────────────────────────────────────────────────────────┤
693
│MONTH │The month the message was sent. │
694
├────────┼────────────────────────────────────────────────────────────────────┤
695
│DAY │The day of month the message was sent. │
696
├────────┼────────────────────────────────────────────────────────────────────┤
697
│WEEKDAY │The 3-letter name of the day of week the message was sent, e.g. │
698
│ │'Thu'. │
699
├────────┼────────────────────────────────────────────────────────────────────┤
700
│HOUR │The hour of day the message was sent. │
701
├────────┼────────────────────────────────────────────────────────────────────┤
702
│MIN │The minute the message was sent. │
703
├────────┼────────────────────────────────────────────────────────────────────┤
704
│SEC │The second the message was sent. │
705
├────────┼────────────────────────────────────────────────────────────────────┤
706
│TZOFFSET│The time-zone as hour offset from GMT. e.g. '-0700' │
707
├────────┼────────────────────────────────────────────────────────────────────┤
708
│TZ │The time zone or name or abbreviation. e.g. 'PDT' │
709
├────────┼────────────────────────────────────────────────────────────────────┤
710
│FULLHOST│ │
711
├────────┼────────────────────────────────────────────────────────────────────┤
712
│ │The name of the source host where the message is originated from. If│
713
│HOST │the message traverses several hosts, and chain_hostnames() is on, │
714
│ │the first one is used. │
715
├────────┼────────────────────────────────────────────────────────────────────┤
716
│PROGRAM │The name of the program the message was sent by. │
717
├────────┼────────────────────────────────────────────────────────────────────┤
718
│MSG or │Message contents including the programname and pid. │
719
│MESSAGE │ │
720
├────────┼────────────────────────────────────────────────────────────────────┤
721
│MSGONLY │Message contents without the program name. │
722
└────────┴────────────────────────────────────────────────────────────────────┘
723
724
Table 3-7. Available options for file()
725
726
┌───────────────┬──────┬──────────────────────────────────────────┬───────────┐
727
│ Name │ Type │ Description │ Default │
728
├───────────────┼──────┼──────────────────────────────────────────┼───────────┤
729
│log_fifo_size()│number│The number of entries in the output fifo. │Use global │
730
│ │ │ │setting. │
731
├───────────────┼──────┼──────────────────────────────────────────┼───────────┤
732
│ │yes or│Forces an fsync() call on the destination │ │
733
│fsync() │no │fd after each write. Note: this may │ │
734
│ │ │degrade performance seriously │ │
735
├───────────────┼──────┼──────────────────────────────────────────┼───────────┤
736
│sync_freq() │number│The logfile is synced when this number of │Use global │
737
│ │ │messages has been written to it. │setting. │
738
├───────────────┼──────┼──────────────────────────────────────────┼───────────┤
739
│encrypt() │yes or│Encrypt the resulting file. NOTE: this is │Use global │
740
│ │no │not implemented as of 1.3.14. │setting. │
741
├───────────────┼──────┼──────────────────────────────────────────┼───────────┤
742
│ │yes or│Compress the resulting logfile using zlib.│Use global │
743
│compress() │no │NOTE: this is not implemented as of │setting. │
744
│ │ │1.3.14. │ │
745
├───────────────┼──────┼──────────────────────────────────────────┼───────────┤
746
│owner() │string│Set the owner of the created filename to │root │
747
│ │ │the one specified. │ │
748
├───────────────┼──────┼──────────────────────────────────────────┼───────────┤
749
│group() │string│Set the group of the created filename to │root │
750
│ │ │the one specified. │ │
751
├───────────────┼──────┼──────────────────────────────────────────┼───────────┤
752
│perm() │number│The permission mask of the file if it is │0600 │
753
│ │ │created by syslog-ng. │ │
754
├───────────────┼──────┼──────────────────────────────────────────┼───────────┤
755
│create_dirs() │yes or│Enable creating non-existing directories. │no │
756
│ │no │ │ │
757
├───────────────┼──────┼──────────────────────────────────────────┼───────────┤
758
│ │ │The permission mask of directories created│ │
759
│ │ │by syslog-ng. Log directories are only │ │
760
│dir_perm() │number│created if a file after macro expansion │0600 │
761
│ │ │refers to a non-existing directory, and │ │
762
│ │ │dir creation is enabled using create_dirs │ │
763
│ │ │(). │ │
764
├───────────────┼──────┼──────────────────────────────────────────┼───────────┤
765
│dir_owner() │string│The owner of directories created by │root │
766
│ │ │syslog-ng. │ │
767
├───────────────┼──────┼──────────────────────────────────────────┼───────────┤
768
│dir_group() │string│The group of directories created by │root │
769
│ │ │syslog-ng. │ │
770
├───────────────┼──────┼──────────────────────────────────────────┼───────────┤
771
│ │ │ │a format │
772
│ │ │Specifies a template which defines the │conforming │
773
│template() │string│logformat to be used in this file. │to the │
774
│ │ │Possible macros are the same as with │default │
775
│ │ │destination file(). │logfile │
776
│ │ │ │format. │
777
├───────────────┼──────┼──────────────────────────────────────────┼───────────┤
778
│ │ │Turns on escaping ' and " in templated │ │
779
│ │ │output files. This is useful for │ │
780
│template_escape│yes or│generating SQL statements and quoting │yes │
781
│() │no │string contents so that parts of your log │ │
782
│ │ │message don't get interpreted as commands │ │
783
│ │ │to the SQL server. │ │
784
├───────────────┼──────┼──────────────────────────────────────────┼───────────┤
785
│ │ │If set to a value higher than 0, before │ │
786
│ │ │writing to a file, syslog-ng checks │ │
787
│ │ │whether this file is older than the │Do never │
788
│ │ │specified amount of time (specified in │remove │
789
│remove_if_older│ │seconds). If so, it removes the existing │existing │
790
│() │number│file and the line to be written is the │files, but │
791
│ │ │first line in a new file with the same │append ( = │
792
│ │ │name. In combination with e.g. the │0). │
793
│ │ │$WEEKDAY macro, this is can be used for │ │
794
│ │ │simple log rotation, in case not all │ │
795
│ │ │history need to be kept. │ │
796
└───────────────┴──────┴──────────────────────────────────────────┴───────────┘
797
798
Example 3-8. Using the file() driver
799
800
destination d_file { file("/var/log/messages" ); };
801
802
803
Example 3-9. Using the file() driver with macros in the file name and a
804
template for the message
805
806
destination d_file {
807
file("/var/log/$YEAR.$MONTH.$DAY/messages"
808
template("$HOUR:$MIN:$SEC $TZ $HOST [$LEVEL] $MSG $MSG\n")
809
template_escape(no)
810
);
811
};
812
813
814
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
815
816
pipe()
817
818
This driver sends messages to a named pipe like /dev/xconsole
819
820
The pipe driver has a single required parameter, specifying the filename of the
821
pipe to open.
822
823
Declaration:
824
pipe(filename);
825
826
827
NOTE: you'll need to create this pipe using mkfifo(1).
828
829
Table 3-8. Available options for pipe()
830
831
┌───────────────┬──────┬────────────────────────────────────────┬─────────────┐
832
│ Name │ Type │ Description │ Default │
833
├───────────────┼──────┼────────────────────────────────────────┼─────────────┤
834
│owner() │string│Set the owner of the pipe to the one │root │
835
│ │ │specified. │ │
836
├───────────────┼──────┼────────────────────────────────────────┼─────────────┤
837
│group() │string│Set the group of the pipe to the one │root │
838
│ │ │specified. │ │
839
├───────────────┼──────┼────────────────────────────────────────┼─────────────┤
840
│perm() │number│The permission mask of the pipe. │0600 │
841
├───────────────┼──────┼────────────────────────────────────────┼─────────────┤
842
│ │ │ │a format │
843
│ │ │Specifies a template which defines the │conforming to│
844
│template() │string│logformat to be used. Possible macros │the default │
845
│ │ │are the same as with destination file().│logfile │
846
│ │ │ │format. │
847
├───────────────┼──────┼────────────────────────────────────────┼─────────────┤
848
│ │ │Turns on escaping ' and " in templated │ │
849
│ │ │output files. This is useful for │ │
850
│template_escape│yes or│generating SQL statements and quoting │yes │
851
│() │no │string contents so that parts of your │ │
852
│ │ │log message don't get interpreted as │ │
853
│ │ │commands to the SQL server. │ │
854
└───────────────┴──────┴────────────────────────────────────────┴─────────────┘
855
856
Example 3-10. Using the pipe() driver
857
858
destination d_pipe { pipe("/dev/xconsole"); };
859
860
861
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
862
863
unix-stream() & unix-dgram()
864
865
This driver sends messages to a unix socket in either SOCK_STREAM or SOCK_DGRAM
866
mode.
867
868
Both drivers have a single required argument specifying the name of the socket
869
to connect to.
870
871
Declaration:
872
unix-stream(filename [options]);
873
unix-dgram(filename [options]);
874
875
876
Table 3-9. Available options for unix-stream() & unix-dgram()
877
878
┌───────────────┬──────┬────────────────────────────────────────┬─────────────┐
879
│ Name │ Type │ Description │ Default │
880
├───────────────┼──────┼────────────────────────────────────────┼─────────────┤
881
│ │ │ │a format │
882
│ │ │Specifies a template which defines the │conforming to│
883
│template() │string│logformat to be used. Possible macros │the default │
884
│ │ │are the same as with destination file().│logfile │
885
│ │ │ │format. │
886
├───────────────┼──────┼────────────────────────────────────────┼─────────────┤
887
│ │ │Turns on escaping ' and " in templated │ │
888
│ │ │output files. This is useful for │ │
889
│template_escape│yes or│generating SQL statements and quoting │yes │
890
│() │no │string contents so that parts of your │ │
891
│ │ │log message don't get interpreted as │ │
892
│ │ │commands to the SQL server. │ │
893
└───────────────┴──────┴────────────────────────────────────────┴─────────────┘
894
895
Example 3-11. Using the unix-stream() driver
896
897
destination d_unix_stream { unix-stream("/var/run/logs"); };
898
899
900
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
901
902
udp() & tcp()
903
904
This driver sends messages to another host on the local intranet or internet
905
using either UDP or TCP protocol.
906
907
Both drivers have a single required argument specifying the destination host
908
address, where messages should be sent, and several optional parameters. Note
909
that this differs from source drivers, where local bind address is implied, and
910
none of the parameters are required.
911
912
Declaration:
913
tcp(host [options]);
914
udp(host [options]);
915
916
917
Table 3-10. Available options for udp() & tcp()
918
919
┌───────────────┬──────┬───────────────────────────────────────────┬──────────┐
920
│ Name │ Type │ Description │ Default │
921
├───────────────┼──────┼───────────────────────────────────────────┼──────────┤
922
│localip() │string│The IP address to bind to before connecting│0.0.0.0 │
923
│ │ │to target. │ │
924
├───────────────┼──────┼───────────────────────────────────────────┼──────────┤
925
│localport() │number│The port number to bind to. │0 │
926
├───────────────┼──────┼───────────────────────────────────────────┼──────────┤
927
│port() or │number│The port number to connect to. │514 │
928
│destport() │ │ │ │
929
├───────────────┼──────┼───────────────────────────────────────────┼──────────┤
930
│ │ │ │a format │
931
│ │ │Specifies a template which defines the │conforming│
932
│template() │string│logformat to be used. Possible macros are │to the │
933
│ │ │the same as with destination file(). │default │
934
│ │ │ │logfile │
935
│ │ │ │format. │
936
├───────────────┼──────┼───────────────────────────────────────────┼──────────┤
937
│ │ │Turns on escaping ' and " in templated │ │
938
│template_escape│yes or│output. This is useful for generating SQL │ │
939
│() │no │statements and quoting string contents so │yes │
940
│ │ │that parts of your log message don't get │ │
941
│ │ │interpreted as commands to the SQL server. │ │
942
├───────────────┼──────┼───────────────────────────────────────────┼──────────┤
943
│tcp-keep-alive │yes or│Available for tcp() only, and specifies │ │
944
│() │no │whether to enable TCP keep alive messages │no │
945
│ │ │using the SO_KEEPALIVE socket option. │ │
946
├───────────────┼──────┼───────────────────────────────────────────┼──────────┤
947
│ │ │Enables source address spoofing. This means│ │
948
│ │ │that the host running syslog-ng generates │ │
949
│ │ │UDP packets with the source IP address │ │
950
│ │ │matching the original sender of the │ │
951
│ │ │message. It is useful when you want to │ │
952
│ │ │perform some kind of preprocessing via │ │
953
│spoof_source │yes or│syslog-ng then forward messages to your │no │
954
│ │no │central log management solution with the │ │
955
│ │ │source address of the original sender. This│ │
956
│ │ │option only works for UDP destinations │ │
957
│ │ │though the original message can be received│ │
958
│ │ │by TCP as well. This option is only │ │
959
│ │ │available if syslog-ng was compiled using │ │
960
│ │ │the --enable-spoof-source configure option.│ │
961
└───────────────┴──────┴───────────────────────────────────────────┴──────────┘
962
963
Table 3-11. Additional options for tcp()
964
965
┌────┬──────┬─────────────────────────────────────────────────────────┬───────┐
966
│Name│ Type │ Description │Default│
967
├────┼──────┼─────────────────────────────────────────────────────────┼───────┤
968
│sync│number│The messages are sent to the remote host when this number│0 │
969
│() │ │of messages have been collected. │ │
970
└────┴──────┴─────────────────────────────────────────────────────────┴───────┘
971
972
Example 3-12. Using the tcp() driver
973
974
destination d_tcp { tcp("10.1.2.3" port(1999) localport(999)); };
975
976
977
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
978
979
usertty()
980
981
This driver writes messages to the terminal of a logged-in user.
982
983
The usertty driver has a single required argument, specifying a username who
984
should receive a copy of matching messages, and no optional arguments.
985
986
Declaration:
987
usertty(username);
988
989
990
Table 3-12. Available options for usertty()
991
992
┌───────────────┬──────┬────────────────────────────────────────┬─────────────┐
993
│ Name │ Type │ Description │ Default │
994
├───────────────┼──────┼────────────────────────────────────────┼─────────────┤
995
│ │ │ │a format │
996
│ │ │Specifies a template which defines the │conforming to│
997
│template() │string│logformat to be used. Possible macros │the default │
998
│ │ │are the same as with destination file().│logfile │
999
│ │ │ │format. │
1000
├───────────────┼──────┼────────────────────────────────────────┼─────────────┤
1001
│ │ │Turns on escaping ' and " in templated │ │
1002
│ │ │output. This is useful for generating │ │
1003
│template_escape│yes or│SQL statements and quoting string │yes │
1004
│() │no │contents so that parts of your log │ │
1005
│ │ │message don't get interpreted as │ │
1006
│ │ │commands to the SQL server. │ │
1007
└───────────────┴──────┴────────────────────────────────────────┴─────────────┘
1008
1009
Example 3-13. Using the usertty() driver
1010
1011
destination d_usertty { usertty("root"); };
1012
1013
1014
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
1015
1016
program()
1017
1018
This driver fork()'s executes the given program with the given arguments and
1019
sends messages down to the stdin of the child.
1020
1021
The program driver has a single required parameter, specifying a program name
1022
to start and no options. The program is executed with the help of the current
1023
shell, so the command may include both file patterns and I/O redirection, they
1024
will be processed.
1025
1026
Declaration:
1027
program(commandtorun);
1028
1029
1030
Note: NOTE: the program is executed once at startup, and kept running until
1031
SIGHUP or exit. The reason is to prevent starting up a large number of
1032
programs for messages, which would imply an easy DoS.
1033
1034
Table 3-13. Available options for program()
1035
1036
┌───────────────┬──────┬────────────────────────────────────────┬─────────────┐
1037
│ Name │ Type │ Description │ Default │
1038
├───────────────┼──────┼────────────────────────────────────────┼─────────────┤
1039
│ │ │ │a format │
1040
│ │ │Specifies a template which defines the │conforming to│
1041
│template() │string│logformat to be used. Possible macros │the default │
1042
│ │ │are the same as with destination file().│logfile │
1043
│ │ │ │format. │
1044
├───────────────┼──────┼────────────────────────────────────────┼─────────────┤
1045
│ │ │Turns on escaping ' and " in templated │ │
1046
│ │ │output. This is useful for generating │ │
1047
│template_escape│yes or│SQL statements and quoting string │yes │
1048
│() │no │contents so that parts of your log │ │
1049
│ │ │message don't get interpreted as │ │
1050
│ │ │commands to the SQL server. │ │
1051
└───────────────┴──────┴────────────────────────────────────────┴─────────────┘
1052
1053
Example 3-14. Using the program() destination driver
1054
1055
destination d_prg { program("/bin/cat >/dev/null"); };
1056
1057
1058
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
1059
1060
Filter functions
1061
1062
The following functions may be used in the filter statement, as described in
1063
the previous chapter.
1064
1065
Table 3-14. Available filter functions in syslog-ng
1066
1067
┌─────────┬──────────────┬────────────────────────────────────────────────────┐
1068
│ Name │ Synopsis │ Description │
1069
├─────────┼──────────────┼────────────────────────────────────────────────────┤
1070
│ │facility │Match messages having one of the listed facility │
1071
│facility │(faciliy │code. │
1072
│ │[,facility]) │ │
1073
├─────────┼──────────────┼────────────────────────────────────────────────────┤
1074
│level() │level(pri │ │
1075
│or │[,pri1..pri2 │Match messages based on priority. │
1076
│priority │[,pri3]]) │ │
1077
│() │ │ │
1078
├─────────┼──────────────┼────────────────────────────────────────────────────┤
1079
│program()│program │Match messages by using a regular expression against│
1080
│ │(regexp) │the program name field of log messages │
1081
├─────────┼──────────────┼────────────────────────────────────────────────────┤
1082
│host() │host(regexp) │Match messages by using a regular expression against│
1083
│ │ │the hostname field of log messages. │
1084
├─────────┼──────────────┼────────────────────────────────────────────────────┤
1085
│match() │match(regexp) │Tries to match a regular expression to the message │
1086
│ │ │itself. │
1087
├─────────┼──────────────┼────────────────────────────────────────────────────┤
1088
│filter() │filter │Call another filter rule and evaluate its value │
1089
│ │(filtername) │ │
1090
├─────────┼──────────────┼────────────────────────────────────────────────────┤
1091
│ │netmask(ip/ │Check the sender's IP address whether it is in the │
1092
│netmask()│mask) │specified IP subnet (ip/mask format, ip and mask │
1093
│ │ │both in dot notation) │
1094
└─────────┴──────────────┴────────────────────────────────────────────────────┘
1095
1096
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
1097
1098
Options
1099
1100
The following options can be specified in the options statement, as described
1101
in the previous chapter.
1102
1103
Table 3-15. List of supported global options in syslog-ng
1104
1105
┌───────────────────────┬──────────┬──────────────────────────────────────────┐
1106
│ Name │ Accepted │ Description │
1107
│ │ values │ │
1108
├───────────────────────┼──────────┼──────────────────────────────────────────┤
1109
│time_reopen() │number │The time to wait before a died connection │
1110
│ │ │is reestablished │
1111
├───────────────────────┼──────────┼──────────────────────────────────────────┤
1112
│time_reap() │number │The time to wait before an idle │
1113
│ │ │destination file is closed. │
1114
├───────────────────────┼──────────┼──────────────────────────────────────────┤
1115
│sync() │number │The number of lines buffered before │
1116
│ │ │written to file │
1117
├───────────────────────┼──────────┼──────────────────────────────────────────┤
1118
│mark() │number │The number of seconds between two MARK │
1119
│ │ │lines. NOTE: not implemented yet. │
1120
├───────────────────────┼──────────┼──────────────────────────────────────────┤
1121
│stats() │number │The number of seconds between two STATS. │
1122
├───────────────────────┼──────────┼──────────────────────────────────────────┤
1123
│log_fifo_size() │number │The number of lines fitting to the output │
1124
│ │ │queue │
1125
├───────────────────────┼──────────┼──────────────────────────────────────────┤
1126
│chain_hostnames() │yes or no │Enable or disable the chained hostname │
1127
│ │ │format. │
1128
├───────────────────────┼──────────┼──────────────────────────────────────────┤
1129
│keep_hostname() │yes or no │Enable or disable hostname rewriting. │
1130
├───────────────────────┼──────────┼──────────────────────────────────────────┤
1131
│check_hostname() │yes or no │Enable or disable whether the hostname │
1132
│ │ │contains valid characters. │
1133
├───────────────────────┼──────────┼──────────────────────────────────────────┤
1134
│bad_hostname() │regular │A regexp which matches hostnames which │
1135
│ │expression│should not be taken as such. │
1136
├───────────────────────┼──────────┼──────────────────────────────────────────┤
1137
│create_dirs() │yes or no │Enable or disable directory creation for │
1138
│ │ │destination files. │
1139
├───────────────────────┼──────────┼──────────────────────────────────────────┤
1140
│owner() │userid │. │
1141
├───────────────────────┼──────────┼──────────────────────────────────────────┤
1142
│group() │groupid │. │
1143
├───────────────────────┼──────────┼──────────────────────────────────────────┤
1144
│perm() │permission│. │
1145
│ │value │ │
1146
├───────────────────────┼──────────┼──────────────────────────────────────────┤
1147
│dir_owner() │userid │. │
1148
├───────────────────────┼──────────┼──────────────────────────────────────────┤
1149
│dir_group() │groupid │. │
1150
├───────────────────────┼──────────┼──────────────────────────────────────────┤
1151
│dir_perm() │permission│. │
1152
│ │value │ │
1153
├───────────────────────┼──────────┼──────────────────────────────────────────┤
1154
│use_time_recvd() │yes or no │Use the time a message is received instead│
1155
│ │ │of the one specified in the message. │
1156
├───────────────────────┼──────────┼──────────────────────────────────────────┤
1157
│ │ │Enable or disable DNS usage. syslog-ng │
1158
│ │ │blocks on DNS queries, so enabling DNS may│
1159
│ │ │lead to a Denial of Service attack. To │
1160
│use_dns() │yes or no │prevent DoS, protect your syslog-ng │
1161
│ │ │network endpoint with firewall rules, and │
1162
│ │ │make sure that all hosts, which may get to│
1163
│ │ │syslog-ng is resolvable. │
1164
├───────────────────────┼──────────┼──────────────────────────────────────────┤
1165
│dns_cache() │yes or no │Enable or disable DNS cache usage. │
1166
├───────────────────────┼──────────┼──────────────────────────────────────────┤
1167
│dns_cache_size() │number │Number of hostnames in the DNS cache. │
1168
├───────────────────────┼──────────┼──────────────────────────────────────────┤
1169
│dns_cache_expire() │number │Number of seconds while a successful │
1170
│ │ │lookup is cached. │
1171
├───────────────────────┼──────────┼──────────────────────────────────────────┤
1172
│dns_cache_expire_failed│number │Number of seconds while a failed lookup is│
1173
│() │ │cached. │
1174
├───────────────────────┼──────────┼──────────────────────────────────────────┤
1175
│log_msg_size() │number │Maximum length of message in bytes. │
1176
├───────────────────────┼──────────┼──────────────────────────────────────────┤
1177
│use_fqdn() │yes or no │Add Fully Qualified Domain Name instead of│
1178
│ │ │short hostname. │
1179
├───────────────────────┼──────────┼──────────────────────────────────────────┤
1180
│ │ │Sets the threshold value for the garbage │
1181
│gc_idle_threshold() │number │collector, when syslog-ng is idle. GC │
1182
│ │ │phase starts when the number of allocated │
1183
│ │ │objects reach this number. Default: 100. │
1184
├───────────────────────┼──────────┼──────────────────────────────────────────┤
1185
│ │ │Sets the threshold value for the garbage │
1186
│gc_busy_threshold() │number │collector, when syslog-ng is busy. GC │
1187
│ │ │phase starts when the number of allocated │
1188
│ │ │objects reach this number. Default: 3000. │
1189
└───────────────────────┴──────────┴──────────────────────────────────────────┘
1190
1191
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
1192
1193
Chapter 4. Performance tuning in syslog-ng
1194
1195
There are several settings available you can finetune the behaviour of
1196
syslog-ng. The defaults should be adequate for a single server or workstation
1197
installation, but for a central loghost receiving the logs from multiple
1198
computers it may not be enough.
1199
1200
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
1201
1202
Setting garbage collector parameters
1203
1204
Syslog-ng uses a garbage collector internally, and while the garbage collector
1205
is running it does not accept messages. This may cause problems if some
1206
non-connection oriented transport protocol is used, like unix-dgram() or udp().
1207
There are two settings which control the garbage collection phase:
1208
1209
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
1210
1211
gc_idle_threshold()
1212
1213
With this option you can specify the idle threshold of the gc. If the number of
1214
allocated objects reach this number, and the system is idle (no message arrived
1215
within 100msec), a gc phase starts. Since the system is idle, presumably no
1216
messages will be lost if the gc is ran. Therefore this value should be low, but
1217
higher than the minimally allocated objects. The minimum number of objects
1218
allocated depends on your configuration, but you can get exact numbers by
1219
specifying the -v command line option.
1220
1221
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
1222
1223
gc_busy_threshold()
1224
1225
This threshold is used when syslog-ng is busy accepting messages (this means
1226
that within 100msec an I/O event occured), however to prevent syslog-ng eating
1227
all your memory, gc should be ran in these cases as well. Set this value high,
1228
so that your log bursts don't get interrupted by the gc.
1229
1230
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
1231
1232
Setting output queue size
1233
1234
Syslog-ng always reads its incoming log channels to prevent your running
1235
daemons from blocking. This may result in lost messages if the output queue is
1236
full. It's therefore important to set the output queue size (termed in number
1237
of messages), which you can do globally, or on a per destination basis.
1238
1239
options { log_fifo_size(1000); };
1240
1241
1242
or
1243
1244
destination d_messages { file("/var/log/messages" log_fifo_size(1000)); };
1245
1246
1247
You should set your fifo size to the estimated number of messages in a message
1248
burst. If bursts extend the bandwidth of your destination pipe, syslog-ng can
1249
feed messages into the destination pipe after the burst has collapsed.
1250
1251
Of course syslog-ng cannot widen your network bandwidth, so if your destination
1252
host lives on a noisy network, and your logtraffic extends the bandwidth of
1253
this network, syslog-ng can't do anything. It'll do its best however.
1254
1255
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
1256
1257
Setting sync parameter
1258
1259
The sync parameter doesn't exactly do what you might expect. As you have seen
1260
messages to be sent are buffered in an output queue. The sync parameter
1261
specifies the number of messages held in this buffer before anything is
1262
written.
1263
1264
Note that it doesn't write all buffered messages in one single chunk, it writes
1265
each distinct message with a single write() system call.
1266
Loggerhead is a web-based interface for Breezy
Version: 2.0.1