Chapter 3. Reference

Table of Contents
Source drivers
Destination drivers
Filter functions
Options

This chapter documents the drivers and options you may specify in the configuration file.

Source drivers

The following drivers may be used in the source statement, as described in the previous chapter.

internal()

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(); };
	  

unix-stream() and unix-dgram()

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

NameTypeDescriptionDefault
owner()stringSet the uid of the socket.root
group()stringSet the gid of the socket. Default: root.root
perm()numberSet the permission mask. For octal numbers prefix the number with '0', e.g. use 0755 for rwxr-xr-x.0666
keep-alive()yes or noSelects whether to keep connections opened when syslog-ng is restarted, can be used only with unix-stream(). Default: yes.yes
max-connections()numberLimits 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"); };
	  

tcp() and udp()

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

NameTypeDescriptionDefault
ip or localipstringThe 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(); };
	  

file()

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. Of course using this driver you are not limited to special files, you can as well read a continuosly growing simple file, and syslog-ng will "follow" appended lines, just like tail -f does.

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-4. Using the file() driver

	    source s_file { file("/proc/kmsg"); };
	  

pipe()

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-5. Using the pipe() driver

	    source s_pipe { pipe("/dev/log"); };
	  

sun-streams() driver

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).