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 (sinks). A message is entered to syslog-ng in one of its sources, if that message matches the filtering rules it goes out using one of the destinations.

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 required, some of them optional. The required parameters are usually positional, which means that they have to come first. See the unix-stream driver specification above, as it refers to the file /dev/log.

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

NameDescription
internalMessages generated internally in syslog-ng
unix-streamOpens the specified unix socket in SOCK_STREAM mode, and listens for messages.
unix-dgramOpens the specified unix socket in SOCK_DGRAM mode, and listens for messages.
fileOpens the specified file, and reads messages.
pipe, fifoOpens the specified named pipe and reads messages
udpListens on the specified UDP port for messages.
tcpListens on the specified TCP port for messages.
sun-stream, sun-streamsOpens the specified STREAMS device on Solaris systems, and reads messages.

For a complete descriptions on the above drivers, see the reference section.