This chapter documents the drivers and options you may specify in the configuration file.
The following drivers may be used in the source statement, as described in the previous chapter.
All internally generated messages "come" from this special source. If you want warnings, errors and notices from syslog-ng itself, you have to include this source in one of your source statement.
Declaration: internal() |
Syslog-ng will print you a warning, if this driver is not referenced.
Example 3-1. Using the internal() driver
source s_local { internal(); }; |
This two drivers behave similarly: they open the given AF_UNIX socket, and start listening on them for messages. unix-stream() is primarily used on Linux, and uses SOCK_STREAM semantics (connection oriented, no messages are lost), unix-dgram() is used on BSDs, and uses SOCK_DGRAM semantics, this may result in lost local messages, if the system is overloaded.
To avoid denial of service attacks when using connection-oriented protocols, the number of simoultaneously accepted connections should be limited. This can be achieved using the max-connections() parameter.
Declaration: unix-stream(filename [options]); unix-dgram(filename [options]); |
The following options can be specified:
Table 3-1. Available options for unix-stream & unix-dgram
Name | Type | Description | Default |
---|---|---|---|
owner() | string | Set the uid of the socket. | root |
group() | string | Set the gid of the socket. Default: root. | root |
perm() | number | Set the permission mask. For octal numbers prefix the number with '0', e.g. use 0755 for rwxr-xr-x. | 0666 |
keep-alive() | yes or no | Selects whether to keep connections opened when syslog-ng is restarted, can be used only with unix-stream(). Default: yes. | yes |
max-connections() | number | Limits the number of simoultaneously opened connections. Can be used only with unix-stream(). | 10 |
Example 3-2. Using the unix-stream() and unix-dgram() drivers
source s_stream { unix-stream("/dev/log" max-connections(10)); }; source s_dgram { unix-dgram("/var/run/log"); }; |
These drivers let you receive messages from the network, and as the name of the drivers show, you can use both UDP and TCP.
UDP is a simple datagram protocol, which provides "best possible service" to transfer messages between hosts. It may lose messages, and no attempt is made to retransmit such lost messages at the protocol level.
TCP provides connection-oriented service, which basically means flow-controlled message pipeline. In this pipeline, each message is acknowledged, and retransmission is done for each lost packet. Generally it's safer to use TCP, because lost connections can be detected, and no messages get lost, but traditionally syslogd protocol uses UDP.
None of tcp() and udp() drivers require positional parameters. By default they bind to 0.0.0.0:514, which means that syslog-ng will listen on all available interfaces. To limit accepted connections to one interface only, use the localip() parameter as described below.
NOTE: the tcp port 514 is reserved for use with rshell, so you have to pick another port if you intend to use syslog-ng and rshell at the same time.
Declaration: tcp([options]); udp([options]); |
The following options are valid for udp() and tcp()
Table 3-2. Available options for unix-stream & unix-dgram
Name | Type | Description | Default |
---|---|---|---|
ip or localip | string | The IP address to bind to. | 0.0.0.0 |
Example 3-3. Using the udp() and tcp() drivers
source s_tcp { tcp(ip(127.0.0.1) port(1999); max-connections(10)); }; source s_udp { udp(); }; |
Usually the kernel presents its messages in a special file (/dev/kmsg on BSDs, /proc/kmsg on Linux), so to read such special files, you'll need the file() driver. Please note that you can't use this driver to follow a file like tail -f does. To feed a growing logfile into syslog-ng (HTTP access.log for instance), use a script like this:
Example 3-4. example script to feed a growing logfile into syslog-ng
#!/bin/sh tail -f | logger -p local4.info |
NOTE: on Linux, the klogd daemon reads kernel messages, and forwards them to the syslogd process. klogd preprocesses kernel messages and replaces addresses with symbolic names (from /boot/System.map). If you don't want to lose this functionality you'll have to run klogd with syslog-ng as well.
Declaration: file(filename); |
Example 3-5. Using the file() driver
source s_file { file("/proc/kmsg"); }; |
The pipe driver opens a named pipe with the specified name, and listens for messages. It's used as the native message getting protocol on HP-UX.
Declaration: pipe(filename); |
NOTE: you'll need to create this pipe using mkfifo(1).
Example 3-6. Using the pipe() driver
source s_pipe { pipe("/dev/log"); }; |
Solaris uses its STREAMS API to send messages to the syslogd process. You'll have to compile syslog-ng with this driver compiled in (see ./configure --help).
Newer versions of Solaris (2.5.1 and above), in addition to STREAMS uses a new IPC called door to confirm delivery of a message. Syslog-ng supports this new IPC mechanism with the door() option (see below).