Destination drivers

Destination drivers output log messages to somewhere outside syslog-ng: a file or a network socket.

file()

The file driver is one of the most important destination drivers in syslog-ng. It allows you to output messages to the named file, or as you'll see 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 Perl/PHP.

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

Warning: since the state of each created file must be tracked by syslog-ng, it consumes some memory for each file. If no new messages are written to a file within 60 seconds (controlled by the time_reap global option), it's closed, and its state is freed.

Exploiting this, a DoS attack can be mounted against your system. If the number of possible destination files and its needed memory is more than the amount your logserver has.

The most suspicious macro is $PROGRAM, where the possible variations is quite high, so in untrusted environments $PROGRAM usage should be avoided.

Table 3-7. Available options for file()

NameTypeDescriptionDefault
log_fifo_size()number The number of entries in the output fifo. Use global setting.
fsync()yes or no Forces an fsync() call on the destination fd after each write. Note: this may degrade performance seriously 
sync_freq()number The logfile is synced when this number of messages has been written to it. Use global setting.
encrypt()yes or no Encrypt the resulting file. NOTE: this is not implemented as of 1.3.14. Use global setting.
compress()yes or no Compress the resulting logfile using zlib. NOTE: this is not implemented as of 1.3.14. Use global setting.
owner()string Set the owner of the created filename to the one specified. root
group()string Set the group of the created filename to the one specified. root
perm()number The permission mask of the file if it is created by syslog-ng. 0600
create_dirs()yes or no Enable creating non-existing directories. no
dir_perm()number The permission mask of directories created by syslog-ng. Log directories are only created if a file after macro expansion refers to a non-existing directory, and dir creation is enabled using create_dirs(). 0600
dir_owner()string The owner of directories created by syslog-ng. root
dir_group()string The group of directories created by syslog-ng. root
template()string Specifies a template which defines the logformat to be used in this file. Possible macros are the same as with destination file(). a format conforming to the default logfile format.
template_escape()yes or no Turns on escaping ' and " in templated output files. This is useful for generating SQL statements and quoting string contents so that parts of your log message don't get interpreted as commands to the SQL server. yes
remove_if_older()number If set to a value higher than 0, before writing to a file, syslog-ng checks whether this file is older than the specified amount of time (specified in seconds). If so, it removes the existing file and the line to be written is the first line in a new file with the same name. In combination with e.g. the $WEEKDAY macro, this is can be used for simple log rotation, in case not all history need to be kept. Do never remove existing files, but append ( = 0).

pipe()

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

NOTE: you'll need to create this pipe using mkfifo(1).

unix-stream() & unix-dgram()

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]); 
	

udp() & tcp()

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]);
	

usertty()

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, and no optional arguments.

	  Declaration: 
	    usertty(username);
	

program()

This driver fork()'s executes the given program with the given arguments and sends messages down to the stdin of the child.

The program driver has a single required parameter, specifying a program name to start and no options. 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);
	

Note

NOTE: the program is executed once at startup, and kept running until SIGHUP or exit. The reason is to prevent starting up a large number of programs for messages, which would imply an easy DoS.