syslog-ng v1.6 reference manual

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.

Declaration: internal()

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

source s_local { internal(); };

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

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

The following options can be specified for these divers:

# 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"); };

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.

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.

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. However, the syslog protocol traditionally uses UDP.

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.

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

The udp() and tcp() have the following options:

source s_tcp { 
tcp(ip(127.0.0.1) port(1999) max-connections(10)); 
};
source s_udp { 
udp(); 
};

Usually the kernel presents its messages in a special file (/dev/kmsg on BSDs, /proc/kmsg on Linux), so to read such special files the file() driver is needed. Please note that this driver cannot follow a file like tail -f does. To feed a growing logfile into syslog-ng (e.g.: an HTTP access.log), use a script like this:

#!/bin/sh
tail -f logfile | logger -p local4.info

The file driver has a single required parameter specifying the file to open, and the log_prefix() option.

Declaration:
file(filename);

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

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.

Declaration:
pipe(filename);

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

Solaris uses its STREAMS framework to send messages to the syslogd process. syslog-ng has to be compiled with this driver enabled for sun-streams() to be usable (see ./configure --help).

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. syslog-ng supports this new IPC mechanism via the door() option (see below).

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

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

The file driver is one of the most important destination drivers in syslog-ng. It allows to output messages to the specified file, or to a set of files.

The destination filename may include macros which gets expanded when the message is written, thus a simple file() driver may result in several files to be created. Macros can be included by prefixing the macro name with a '$' sign (without the quotes), just like in Bourne compatible shells.

If the expanded filename refers to a directory which does not exist, it will be created depending on the create_dirs() setting (both global and a per destination option).

destination d_file { file("/var/log/messages" ); };

destination d_file {
file("/var/log/$YEAR.$MONTH.$DAY/messages"
template("$HOUR:$MIN:$SEC $TZ $HOST [$LEVEL] $MSG $MSG\n")
template_escape(no)
);
};

This driver sends messages to a named pipe like /dev/xconsole.

The pipe driver has a single required parameter, specifying the filename of the pipe to open.

Declaration:
pipe(filename);

destination d_pipe { pipe("/dev/xconsole"); };

This driver sends messages to a unix socket in either SOCK_STREAM or SOCK_DGRAM mode.

Both drivers have a single required argument specifying the name of the socket to connect to.

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

destination d_unix_stream { unix-stream("/var/run/logs"); };

This driver sends messages to another host on the local intranet or internet using either UDP or TCP protocol.

Both drivers have a single required argument specifying the destination host address, where messages should be sent, and several optional parameters. Note that this differs from source drivers, where local bind address is implied, and none of the parameters are required.

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

destination d_tcp { 
tcp("10.1.2.3" port(1999); 
localport(999)); 
};

This driver writes messages to the terminal of a logged-in user.

The usertty() driver has a single required argument, specifying a username who should receive a copy of matching messages.

Declaration: usertty(username);

destination d_usertty { usertty("root"); };

This driver executes the specified program with the specified arguments and sends messages to the standard input (stdin) of the child.

The program() driver has a single required parameter, specifying a program name to start. The program is executed with the help of the current shell, so the command may include both file patterns and I/O redirection, they will be processed.

Declaration: program(commandtorun);

destination d_prg { program("/bin/cat >/dev/null"); };

With this option you can specify the idle threshold of the gc. If the number of allocated objects reaches this number and the system is idle (no message arrived within 100msec ), a gc phase starts. Since the system is idle, presumably no messages will be lost if the gc is run. Therefore, this value should be low, but higher than the minimally allocated objects. The minimum number of objects allocated depends on the configuration; exact numbers can be obtained by specifying the -v command line option.

This threshold is used when syslog-ng is busy accepting messages (this means that within 100msec an I/O event occurred). However, to prevent syslog-ng from consuming all the available memory, gc should be run in these cases as well. Set this value high, so that the log bursts do not get interrupted by the gc.