Chapter 2. Message paths

Table of Contents
Sources
Filters
Destinations
Log paths
Options

In syslog-ng a message path (or message route) consist of one or more sources, one or more filtering rules and one or more destinations. A message is entered to syslog-ng in one of its sources, if that message matches the filtering rules it goes out using the destinations. Note that a message goes to _all_ matching destinations by default, although this behaviour can be changed.

Sources

A source is a collection of source drivers, which collect messages using a given method. For instance there's a source driver for AF_UNIX, SOCK_STREAM style sockets, which is used by the Linux syslog() call.

To declare a source, you'll need to use the source statement in the configuration file with the following syntax:

	  source <identifier> { source-driver(params); source-driver(params); ... };
	

The identifier has to uniquely identify this given source and of course may not clash with any of the reserved words (in case you had a nameclash, simply enclose the identifier in quotation marks)

You can control exactly which drivers are used to gather log messages, thus you'll have to know how your system and its native syslogd communicate. Here's a introduction to the inner workings of syslogd on some of the platforms I tested:

Table 2-1. Communication method between syslogd and its clients

PlatformMethod
LinuxA SOCK_STREAM unix socket named /dev/log
BSD flavorsA SOCK_DGRAM unix socket named /var/run/log
Solaris (2.5 or below)An SVR4 style STREAMS device named /dev/log
Solaris (2.6 or above) In addition to the STREAMS device used in versions below 2.6, uses a new multithreaded IPC method called door. By default the door used by syslogd is /etc/.syslog_door

Each possible communication mechanism has the corresponding source driver in syslog-ng. For instance to open a unix socket with SOCK_DGRAM style communication you use the driver unix-dgram, the same with SOCK_STREAM style - as used under Linux - is called unix-stream.

Example 2-1. Source statement on a Linux based operating system

	  source src { unix-stream("/dev/log"); internal(); udp(ip(0.0.0.0) port(514)); };
	

Each driver may take parameters, some of them are required, others are optional. The required parameters are positional, meaning that they must be specified in a defined order. A unix-stream() driver has a single required argument, the name of the socket to listen to, and several optional parameters, which follow the socket name. Optional arguments can be specified in any order and must have the form option(value).

Table 2-2. Available source drivers in syslog-ng

NameDescription
internal()Messages generated internally in syslog-ng
unix-stream()Opens the specified unix socket in SOCK_STREAM mode, and listens for messages.
unix-dgram()Opens the specified unix socket in SOCK_DGRAM mode, and listens for messages.
file()Opens the specified file, and reads messages.
pipe(), fifoOpens the specified named pipe and reads messages
udp()Listens on the specified UDP port for messages.
tcp()Listens on the specified TCP port for messages.
sun-stream(), sun-streams()Opens the specified STREAMS device on Solaris systems, and reads messages.

For a complete descriptions on the above drivers, see Chapter 3