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

	  Declaration: internal()
	

Syslog-ng will issue a warning upon startup, if this driver is not referenced.

Example 3-1. Using the internal() driver

	    source s_local { internal(); };
	  

unix-stream() and unix-dgram()

These 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 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 has a single required positional argument, specifying the filename of the socket to create, and several optional parameters.

NOTE: syslogd on Linux originally was using SOCK_STREAM sockets but this was changed in some distributions to SOCK_DGRAM at around 1999. The change was used as a fix to a possible DoS problem, however I do not think it was a proper solution. On Linux you can choose to use whichever you like as syslog clients automatically detect the socket type being used. My original post to bugtraq from 1999 when the change occurred.

	  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 simultaneously opened connections. Can be used only with unix-stream().10

Example 3-2. 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 BSDs
	    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 as transport.

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 to retransmit such lost messages at the protocol level.

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's safer to use TCP, because lost connections can be detected, and no messages get lost, but traditionally the syslog 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, port 514. To limit accepted connections to one interface only, use the localip() parameter as described below.

Note

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 udp() & tcp()

NameTypeDescriptionDefault
ip() or localip()string The IP address to bind to. Note that this is not the address where messages are accepted from. 0.0.0.0
port() or localport()numberThe port number to bind to.514
keep-alive()yes or no Available for tcp() only, and specifies whether to close connections upon the receival of a SIGHUP signal. yes
tcp-keep-alive()yes or no Available for tcp() only, and specifies whether to enable TCP keep alive messages using the SO_KEEPALIVE socket option. no
max-connections()numberSpecifies the maximum number of simultaneous connections.10

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. 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 logfile | logger -p local4.info
	    

The file driver has a single required parameter specifying the file to open and the following options:

Table 3-3. Available options for file

NameTypeDescriptionDefault
log_prefix()string The string to prepend log messages. Useful for logging kernel messages as it is not prefixed by 'kernel:' by default empty string
	  Declaration:
	    file(filename);
	

Example 3-5. Using the file() driver

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

Note

NOTE: on Linux, historically the klogd daemon was used to read kernel messages and forward them to the syslogd process. klogd preprocessed kernel messages and replaced addresses with symbolic names (from /boot/System.map), but this method of symbol resolving has been deprecated by the ksymoops utility and similar kernel features. For these reasons it is not recommended to use both klogd and syslog-ng at the same time.

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.

The pipe driver has a single required parameter, specifying the filename of the pipe to open, and the following options:

Table 3-4. Available options for pipe

NameTypeDescriptionDefault
pad_size()number Specifies input padding. Some operating systems (such as HP-UX) pad all messages to block boundary. This option can be used to specify the block size. (HP-UX uses 2048 bytes) 0
	  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"); };
	  

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), uses a new IPC in addition to STREAMS, called door to confirm delivery of a message. Syslog-ng supports this new IPC mechanism with the door() option (see below).

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

Example 3-7. Using the sun-streams() driver

	      source s_stream { sun-streams("/dev/log" door("/etc/.syslog_door"); };
	    

Table 3-5. Available options for sun-streams

NameTypeDescriptionDefault
door()string Specifies the filename of a door to open, needed on Solaris above 2.5.1. none