The syslog-ng Administrator Guide

Some parameters affecting message parsing are common for all sources:

The kernel usually sends log messages to a special file (/dev/kmsg on BSDs, /proc/kmsg on Linux). The file() driver reads log messages from such files. The syslog-ng application can periodically check the file for new log messages if the follow_freq() option is set.

The syslog-ng application notices if a file is renamed or replaced with a new file, so it can correctly follow the file even if logrotation is used. When syslog-ng is restarted, it records the position of the last sent log message, and continues to send messages from this position after the restart.

The file driver has a single required parameter specifying the file to open, and has only the common source specific options as specified in Table 9.1, “Common options for source drivers”.

Declaration:
file(filename);

	Example 9.1. Using the file() driver
	source s_file { file("/proc/kmsg" log_prefix("kernel: ")); };

	Note
	On Linux, the klogd daemon can be used in addition to syslog-ng to read kernel messages and forward them to syslog-ng. klogd used to preprocess kernel messages to resolve symbols etc., but as this is deprecated by ksymoops there is really no point in running both klogd and syslog-ng in parallel. Also note that running two processes reading /proc/kmsg at the same time might result in dead-locks.

	Example 9.2. Tailing files
	The following source checks the access.log file every second for new messages. source s_tail { file("/var/log/apache/access.log" follow_freq(1) flags(no-parse)); };

All internally generated messages "come" from this special source. To collect warnings, errors and notices from syslog-ng itself, include this source in one of your source statements.

internal()

The syslog-ng application will issue a warning upon startup if this driver is not referenced.

	Example 9.3. Using the internal() driver
	source s_local { internal(); };

Log statistics;
dropped='tcp(AF_INET(192.168.10.1:514))=6439',
processed='center(received)=234413',
processed='destination(d_tcp)=234413',
processed='destination(d_local)=234413',
processed='source(s_local)=234413'

The pipe driver opens a named pipe with the specified name and listens for messages. It is used as the native message delivery protocol on HP-UX.

The pipe driver has a single required parameter, specifying the filename of the pipe to open. It has only the common source specific options as specified in Table 9.1, “Common options for source drivers”.

Pipe is very similar to the file() driver, but there are a few differences, for example pipe() opens its argument in read-write mode, therefore it is not recommended to be used on special files like /proc/kmsg.

	Warning
	It is not recommended to use pipe() on anything else than real pipes.

Declaration:
pipe(filename);

	Note
	You have to create this pipe using mkfifo(1).

	Example 9.4. Using the pipe() driver
	source s_pipe { pipe("/dev/log" pad_size(2048)); };

Solaris uses its STREAMS framework to send messages to the syslogd process.

Newer versions of Solaris (2.5.1 and above), use a new IPC in addition to STREAMS, called door to confirm the delivery of a message. The syslog-ng application supports this new IPC mechanism via the door() option (see below).

	Note
	The sun-streams() driver must be enabled when the syslog-ng application is compiled (see ./configure --help).

The sun-streams() driver has a single required argument specifying the STREAMS device to open, and the door() option.

	Example 9.5. Using the sun-streams() driver
	source s_stream { sun-streams("/dev/log" door("/etc/.syslog_door"); };

These drivers enable to receive messages from the network. As the name of the drivers implies, both UDP and TCP can be used to transport messages. The tcp6() and udp6() use the IPv6 network protocol.

UDP is a simple datagram oriented protocol, which provides "best effort service" to transfer messages between hosts. It may lose messages, and no attempt is made at the protocol level to retransmit such lost messages. The syslog protocol traditionally uses UDP.

TCP provides connection-oriented service, which basically means a flow-controlled message pipeline. In this pipeline each message is acknowledged, and retransmission is done for lost packets. Generally it is safer to use TCP, because lost connections can be detected, and no messages get lost, assuming that the TCP connection does not break. When a TCP connection is broken the 'in-transit' messages that were sent by syslog-ng but not yet received on the other side are lost. (Basically these messages are still sitting in the socket buffer of the sending host and syslog-ng has no information about the fate of these messages).

The tcp() and udp() drivers do not require any positional parameters. By default they bind to 0.0.0.0:514, which means that syslog-ng will listen on all available interfaces, port 514. To limit accepted connections to only one interface, use the localip() parameter as described below.

	Note
	The tcp port 514 is reserved for use with rshell, so select a different port if syslog-ng and rshell is used at the same time.

If you specify a multicast bind address to udp() and udp6(), syslog-ng will automatically join the necessary multicast group. TCP does not support multicasting.

The syslog-ng Premium Edition application supports TLS (Transport Layer Security, also known as SSL) for the tcp() and tcp6() drivers. See the TLS-specific options below and Section 3.9, “Encrypting log messages with TLS” for details.

Declaration:
  tcp([options]);
  udp([options]);

The following options are valid for tcp(), tcp6(), udp(), and udp6()

	Example 9.6. Using the udp() and tcp() drivers
	# TCP source with the maximum number of simultaneous connections limited. source s_tcp { tcp(ip(127.0.0.1) port(1999) max-connections(10)); }; # TCP source with TLS enabled source s_tcp { tcp(ip(127.0.0.1) port(1999) tls(peer-verify('required-trusted' key_file('/etc/syslog-ng/syslog-ng.key') cert_file('/etc/syslog-ng/syslog-ng.crt')))); }; # UDP source with defaults. source s_udp { udp(); };

These two drivers behave similarly: they open the given AF_UNIX socket and start listening on it for messages. unix-stream() is primarily used on Linux and uses SOCK_STREAM semantics (connection oriented, no messages are lost); while 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 simultaneously accepted connections should be limited. This can be achieved using the max-connections() parameter. The default value of this parameter is quite strict, you might have to increase it on a busy system.

Both unix-stream and unix-dgram have a single required positional argument, specifying the filename of the socket to create, and several optional parameters.

	Note
	syslogd on Linux originally used SOCK_STREAM sockets, but some distributions switched to SOCK_DGRAM around 1999 to fix a possible DoS problem. On Linux you can choose to use whichever driver you like as syslog clients automatically detect the socket type being used.

The difference between the unix-stream and unix-dgram drivers is similar to the difference between the TCP and UDP network protocols. Use the following guidelines to select which driver to use in a particular situation:

Choose unix-stream if you would choose TCP (stream) instead of UDP (datagram). The unix-stream driver offers the following features:

Choose unix-dgram if you would choose TCP (stream) over UDP (datagram). The unix-dgram driver offers the following features:

However, the client does not notice if a message is lost when using the unix-dgram driver.

Declaration: 
unix-stream(filename [options]);
unix-dgram(filename [options]);

The following options can be specified for these divers:

	Example 9.7. Using the unix-stream() and unix-dgram() drivers
	# source declaration on Linux source s_stream { unix-stream("/dev/log" max-connections(10)); }; # source declaration on BSD source s_dgram { unix-dgram("/var/run/log"); };