syslog-ng reference manual
Prev | Chapter 3. Reference | Next

# 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-6. Available macros in filename expansion

Name | Description
--- | ---
FACILITY | The name of the facility, the message is tagged as coming from.
PRIORITY or LEVEL | The priority of the message.
TAG | The priority and facility encoded as a 2 digit hexadecimal number.
DATE |
FULLDATE |
ISODATE |
YEAR | The year the message was sent. Time expansion macros can either use the time specified in the log message, e.g. the time the log message is sent, or the time the message was received by the log server. This is controlled by the use_time_recvd() option.
MONTH | The month the message was sent.
DAY | The day of month the message was sent.
WEEKDAY | The 3-letter name of the day of week the message was sent, e.g. 'Thu'.
HOUR | The hour of day the message was sent.
MIN | The minute the message was sent.
SEC | The second the message was sent.
TZOFFSET | The time-zone as hour offset from GMT. e.g. '-0700'
TZ | The time zone or name or abbreviation. e.g. 'PDT'
FULLHOST |
HOST | The name of the source host where the message is originated from. If the message traverses several hosts, and chain_hostnames() is on, the first one is used.
PROGRAM | The name of the program the message was sent by.
MSG or MESSAGE | Message contents including the programname and pid.
MSGONLY | Message contents without the program name.

Table 3-7. Available options for file()

Name | Type | Description | Default
--- | --- | --- | ---
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).

Example 3-8. Using the file() driver

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

Example 3-9. Using the file() driver with macros in the file name and a template for the message

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

## 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).

Table 3-8. Available options for pipe()

Name | Type | Description | Default
--- | --- | --- | ---
owner() | string | Set the owner of the pipe to the one specified. | root
group() | string | Set the group of the pipe to the one specified. | root
perm() | number | The permission mask of the pipe. | 0600
template() | string | Specifies a template which defines the logformat to be used. 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

Example 3-10. Using the pipe() driver

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

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

Table 3-9. Available options for unix-stream() & unix-dgram()

Name | Type | Description | Default
--- | --- | --- | ---
template() | string | Specifies a template which defines the logformat to be used. 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

Example 3-11. Using the unix-stream() driver

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

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

Table 3-10. Available options for udp() & tcp()

Name | Type | Description | Default
--- | --- | --- | ---
localip() | string | The IP address to bind to before connecting to target. | 0.0.0.0
localport() | number | The port number to bind to. | 0
port() or destport() | number | The port number to connect to. | 514
template() | string | Specifies a template which defines the logformat to be used. 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. 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
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
spoof_source | yes or no | Enables source address spoofing. This means that the host running syslog-ng generates UDP packets with the source IP address matching the original sender of the message. It is useful when you want to perform some kind of preprocessing via syslog-ng then forward messages to your central log management solution with the source address of the original sender. This option only works for UDP destinations though the original message can be received by TCP as well. This option is only available if syslog-ng was compiled using the --enable-spoof-source configure option. | no

Table 3-11. Additional options for tcp()

Name | Type | Description | Default
--- | --- | --- | ---
sync() | number | The messages are sent to the remote host when this number of messages have been collected. | 0

Example 3-12. Using the tcp() driver

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

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

Table 3-12. Available options for usertty()

Name | Type | Description | Default
--- | --- | --- | ---
template() | string | Specifies a template which defines the logformat to be used. 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. 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

Example 3-13. Using the usertty() driver

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

## 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: 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.

Table 3-13. Available options for program()

Name | Type | Description | Default
--- | --- | --- | ---
template() | string | Specifies a template which defines the logformat to be used. 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. 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

Example 3-14. Using the program() destination driver

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

Prev | Home | Next
Reference | Up | Filter functions