The syslog-ng 3.0 Administrator Guide

Document version: Tenth
Release date: January 8, 2010
Latest version available at the BalaBit Documentation Page

8.1. Source drivers

8.1.1. internal()

All messages generated internally by syslog-ng use this special source. To collect warnings, errors and notices from syslog-ng itself, include this source in one of your source statements.

[Note] Note

Internal messages always use the local timezone of the host.

internal()

This driver does not have any parameters.

[Example] Example 8.1. Using the internal() driver 
source s_local { internal(); };

8.1.2. file()

Collects log messages from plain-text files. The file driver has a single required parameter specifying the file to open.

Declaration:
    file(filename);

In syslog-ng PE, the filename (but not the pathname) may include wildcard characters (e.g., *). Note that when using wildcards in filenames, always set how often syslog-ng should check the file for new messages using the follow_freq() parameter.

When using wildcards, syslog-ng PE monitors every matching file, and can receive new log messages from any of the files. However, monitoring (polling) many files (i.e., more than ten) has a significant overhead and may affect performance. On Linux this overhead is not so significant, because syslog-ng PE uses the inotify feature of the kernel.

[Note] Note

If the message does not have a proper syslog header, syslog-ng treats messages received from files as sent by the kern facility. Use the default-facility and default-priority options in the source definition to assign a different facility if needed.

The file() driver has the following options:

Name Type Default Description
default-facility() facility string kern This parameter assigns a facility value to the messages received from the file source, if the message does not specify one.
default-priority() priority string   This parameter assigns an emergency level to the messages received from the file source, if the message does not specify one.
file filename with path   The file to read messages from. Note that only syslog-ng PE supports wildcards in the filename (but not in the pathname). To monitor the subdirectories as well, use the recursive option.
encoding() string   Specifies the characterset (encoding, e.g., UTF-8) of messages using the legacy BSD-syslog protocol. To list the available character sets on a host, execute the iconv -l command.
flags() empty-lines, kernel, no-multi-line, no-parse, store-legacy-msghdr, syslog-protocol, validate-utf8 empty set

Specifies the log parsing options of the source.

Use the empty-lines flag to keep the empty lines of the messages. By default, syslog-ng removes empty lines automatically.

The kernel flag makes the source default to the LOG_KERN | LOG_CRIT priority if not specified otherwise.

The no-multi-line flag disables line-breaking in the messages; the entire message is converted to a single line.

By default, syslog-ng parses incoming messages as syslog messages. If a source does not send properly formatted messages, use the no-parse flag to disable message parsing for the source. As a result, syslog-ng will generate a new syslog header and put the entire incoming message into the MSG part of the syslog message.

The no-parse flag completely disables syslog message parsing and processes the complete line as the message part of a syslog message. Other information (timestamp, host, etc.) is added automatically. This flag is useful for parsing files not complying to the syslog format.

If the store-legacy-msghdr flag is enabled, syslog-ng stores the original incoming header of the log message. This is useful of the original format of a non-syslog-compliant message must be retained (syslog-ng automatically corrects minor header errors, e.g., adds a whitespace before msg in the following message: Jan 22 10:06:11 host program:msg). Note that store-legacy-msghdr should be enabled when receiving messages from syslog-ng Agent for Windows clients that use the Snare-compatible mode.

The syslog-protocol flag specifies that incoming messages are expected to be formatted according to the new IETF syslog protocol standard. Note that this flag is not needed for the syslog driver.

The validate-utf8 flag enables encoding-verification for messages formatted according to the new IETF syslog standard (see Section 2.18.2, “IETF-syslog messages” for details). If the BOM character is missing, but the message is otherwise UTF-8 compliant, syslog-ng automatically adds the BOM character to the message.
follow_freq() number 1 Indicates that the source should be checked periodically instead of being polled. This is useful for files which always indicate readability, even though no new lines were appended. If this value is higher than zero, syslog-ng will not attempt to use poll() on the file, but checks whether the file changed every time the follow_freq() interval (in seconds) has elapsed. Floating-point numbers (e.g., 1.5) can be used as well.
keep_timestamp() yes or no yes Specifies whether syslog-ng should accept the timestamp received from the sending application or client. If disabled, the time of reception will be used instead. This option can be specified globally, and per-source as well. The local setting of the source overrides the global option if available.
log_fetch_limit() number The value specified by the global log_fetch_limit() option, which defaults to 10. The maximum number of messages fetched from a source during a single poll loop. The destination queues might fill up before flow-control could stop reading if log_fetch_limit() is too high.
log_iw_size() number 100 The size of the initial window, this value is used during flow control.
log_msg_size() number Use the global log_msg_size() option, which defaults to 8192. Specifies the maximum length of incoming log messages. Uses the value of the global option if not specified.
log_prefix() (DEPRECATED) string   A string added to the beginning of every log message. It can be used to add an arbitrary string to any log source, though it is most commonly used for adding kernel: to the kernel messages on Linux. NOTE: This option is deprecated. Use program_override() instead.
optional() yes or no   Instruct syslog-ng to ignore the error if a specific source cannot be initialized. No other attempts to initialize the source will be made until the configuration is reloaded. This option currently applies to the pipe(), unix-dgram, and unix-stream drivers.
pad_size() number 0 Specifies input padding. Some operating systems (such as HP-UX) pad all 0 messages to block boundary. This option can be used to specify the block size. (HP-UX uses 2048 bytes). Syslog-ng will pad reads from the associated device to the number of bytes set in pad_size(). Mostly used on HP-UX where /dev/log is a named pipe and every write is padded to 2048 bytes.
program_override string   Replaces the $PROGRAM part of the message with the parameter string. For example, to mark every message coming from the kernel, include the program_override("kernel") option in the source containing /proc/kmsg. NOTE: This option replaces the deprecated log_prefix() option.
recursive yes or no no When enabled, syslog-ng PE monitors every subdirectory of the directory set in the path of the file parameter, and reads log messages from files with the set filename. The recursive option can be used together with wildcards in the filename.
time_zone() timezone in the form +/-HH:MM   The default timezone for messages read from the source. Applies only if no timezone is specified within the message itself.

Table 8.1. Options of the file() sources


[Example] Example 8.2. Using the file() driver 
source s_file { file("/var/log/messages"};
[Example] Example 8.3. Tailing files

The following source checks the access.log file every second for new messages.

source s_tail { file("/var/log/apache/access.log" 
                    follow_freq(1) flags(no-parse)); };
[Example] Example 8.4. Using wildcards in the filename

The following example monitors every file with the .log extension in the /var/application directory for log messages. Note that only syslog-ng PE supports wildcards in the file and pathnames.

source s_file { file("/var/application/*.log" follow_freq(1)};
[Example] Example 8.5. Monitoring multiple directories

The following example reads files having the .log extension from the /var/application/ directory and its subdirectories. Note that only syslog-ng PE supports recursive directory handling and wildcards in the file and pathnames.

source s_file_subdirectories { file("/var/application/*.log"
                    recursive(yes) 
                    follow_freq(1) 
                    log_fetch_limit(100)
                    );};

8.1.3. pipe()

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

As of syslog-ng Open Source Edition 3.0.2, pipes are created automatically. In earlier versions, you had to create the pipe using the mkfifo(1) command.

The pipe driver has the following options:

Name Type Default Description
flags() empty-lines, kernel, no-multi-line, no-parse, store-legacy-msghdr, syslog-protocol, validate-utf8 empty set

Specifies the log parsing options of the source.

Use the empty-lines flag to keep the empty lines of the messages. By default, syslog-ng removes empty lines automatically.

The kernel flag makes the source default to the LOG_KERN | LOG_CRIT priority if not specified otherwise.

The no-multi-line flag disables line-breaking in the messages; the entire message is converted to a single line.

By default, syslog-ng parses incoming messages as syslog messages. If a source does not send properly formatted messages, use the no-parse flag to disable message parsing for the source. As a result, syslog-ng will generate a new syslog header and put the entire incoming message into the MSG part of the syslog message.

The no-parse flag completely disables syslog message parsing and processes the complete line as the message part of a syslog message. Other information (timestamp, host, etc.) is added automatically. This flag is useful for parsing files not complying to the syslog format.

If the store-legacy-msghdr flag is enabled, syslog-ng stores the original incoming header of the log message. This is useful of the original format of a non-syslog-compliant message must be retained (syslog-ng automatically corrects minor header errors, e.g., adds a whitespace before msg in the following message: Jan 22 10:06:11 host program:msg). Note that store-legacy-msghdr should be enabled when receiving messages from syslog-ng Agent for Windows clients that use the Snare-compatible mode.

The syslog-protocol flag specifies that incoming messages are expected to be formatted according to the new IETF syslog protocol standard. Note that this flag is not needed for the syslog driver.

The validate-utf8 flag enables encoding-verification for messages formatted according to the new IETF syslog standard (see Section 2.18.2, “IETF-syslog messages” for details). If the BOM character is missing, but the message is otherwise UTF-8 compliant, syslog-ng automatically adds the BOM character to the message.
follow_freq() number 1 Indicates that the source should be checked periodically instead of being polled. This is useful for files which always indicate readability, even though no new lines were appended. If this value is higher than zero, syslog-ng will not attempt to use poll() on the file, but checks whether the file changed every time the follow_freq() interval (in seconds) has elapsed. Floating-point numbers (e.g., 1.5) can be used as well.
keep_timestamp() yes or no yes Specifies whether syslog-ng should accept the timestamp received from the sending application or client. If disabled, the time of reception will be used instead. This option can be specified globally, and per-source as well. The local setting of the source overrides the global option if available.
log_fetch_limit() number The value specified by the global log_fetch_limit() option, which defaults to 10. The maximum number of messages fetched from a source during a single poll loop. The destination queues might fill up before flow-control could stop reading if log_fetch_limit() is too high.
log_iw_size() number 100 The size of the initial window, this value is used during flow control.
log_msg_size() number Use the global log_msg_size() option, which defaults to 8192. Specifies the maximum length of incoming log messages. Uses the value of the global option if not specified.
log_prefix() (DEPRECATED) string   A string added to the beginning of every log message. It can be used to add an arbitrary string to any log source, though it is most commonly used for adding kernel: to the kernel messages on Linux. NOTE: This option is deprecated. Use program_override() instead.
optional() yes or no   Instruct syslog-ng to ignore the error if a specific source cannot be initialized. No other attempts to initialize the source will be made until the configuration is reloaded. This option currently applies to the pipe(), unix-dgram, and unix-stream drivers.
pad_size() number 0 Specifies input padding. Some operating systems (such as HP-UX) pad all 0 messages to block boundary. This option can be used to specify the block size. (HP-UX uses 2048 bytes). Syslog-ng will pad reads from the associated device to the number of bytes set in pad_size(). Mostly used on HP-UX where /dev/log is a named pipe and every write is padded to 2048 bytes.
pipe filename with path   The filename of the pipe to read messages from.
program_override string   Replaces the $PROGRAM part of the message with the parameter string. For example, to mark every message coming from the kernel, include the program_override("kernel") option in the source containing /proc/kmsg. NOTE: This option replaces the deprecated log_prefix() option.
time_zone() timezone in the form +/-HH:MM   The default timezone for messages read from the source. Applies only if no timezone is specified within the message itself.

Table 8.2. Options of the pipe() sources


[Example] Example 8.6. Using the pipe() driver 
source s_pipe { pipe("/dev/pipe" pad_size(2048)); };

8.1.4. program()

The program driver starts an external application and reads messages from the standard output (stdout) of the application. It is mainly useful to receive log messages from daemons that accept incoming messages and convert them to log messages.

The program driver has a single required parameter, specifying the name of the application to start.

Declaration:
    program(filename);
[Note] Note

The program is restarted automatically if it exits.

The program driver has the following options:

Name Type Default Description
flags() empty-lines, kernel, no-multi-line, no-parse, store-legacy-msghdr, syslog-protocol, validate-utf8 empty set

Specifies the log parsing options of the source.

Use the empty-lines flag to keep the empty lines of the messages. By default, syslog-ng removes empty lines automatically.

The kernel flag makes the source default to the LOG_KERN | LOG_CRIT priority if not specified otherwise.

The no-multi-line flag disables line-breaking in the messages; the entire message is converted to a single line.

By default, syslog-ng parses incoming messages as syslog messages. If a source does not send properly formatted messages, use the no-parse flag to disable message parsing for the source. As a result, syslog-ng will generate a new syslog header and put the entire incoming message into the MSG part of the syslog message.

The no-parse flag completely disables syslog message parsing and processes the complete line as the message part of a syslog message. Other information (timestamp, host, etc.) is added automatically. This flag is useful for parsing files not complying to the syslog format.

If the store-legacy-msghdr flag is enabled, syslog-ng stores the original incoming header of the log message. This is useful of the original format of a non-syslog-compliant message must be retained (syslog-ng automatically corrects minor header errors, e.g., adds a whitespace before msg in the following message: Jan 22 10:06:11 host program:msg). Note that store-legacy-msghdr should be enabled when receiving messages from syslog-ng Agent for Windows clients that use the Snare-compatible mode.

The syslog-protocol flag specifies that incoming messages are expected to be formatted according to the new IETF syslog protocol standard. Note that this flag is not needed for the syslog driver.

The validate-utf8 flag enables encoding-verification for messages formatted according to the new IETF syslog standard (see Section 2.18.2, “IETF-syslog messages” for details). If the BOM character is missing, but the message is otherwise UTF-8 compliant, syslog-ng automatically adds the BOM character to the message.
follow_freq() number 1 Indicates that the source should be checked periodically instead of being polled. This is useful for files which always indicate readability, even though no new lines were appended. If this value is higher than zero, syslog-ng will not attempt to use poll() on the file, but checks whether the file changed every time the follow_freq() interval (in seconds) has elapsed. Floating-point numbers (e.g., 1.5) can be used as well.
keep_timestamp() yes or no yes Specifies whether syslog-ng should accept the timestamp received from the sending application or client. If disabled, the time of reception will be used instead. This option can be specified globally, and per-source as well. The local setting of the source overrides the global option if available.
log_fetch_limit() number The value specified by the global log_fetch_limit() option, which defaults to 10. The maximum number of messages fetched from a source during a single poll loop. The destination queues might fill up before flow-control could stop reading if log_fetch_limit() is too high.
log_iw_size() number 100 The size of the initial window, this value is used during flow control.
log_msg_size() number Use the global log_msg_size() option, which defaults to 8192. Specifies the maximum length of incoming log messages. Uses the value of the global option if not specified.
log_prefix() (DEPRECATED) string   A string added to the beginning of every log message. It can be used to add an arbitrary string to any log source, though it is most commonly used for adding kernel: to the kernel messages on Linux. NOTE: This option is deprecated. Use program_override() instead.
optional() yes or no   Instruct syslog-ng to ignore the error if a specific source cannot be initialized. No other attempts to initialize the source will be made until the configuration is reloaded. This option currently applies to the pipe(), unix-dgram, and unix-stream drivers.
pad_size() number 0 Specifies input padding. Some operating systems (such as HP-UX) pad all 0 messages to block boundary. This option can be used to specify the block size. (HP-UX uses 2048 bytes). Syslog-ng will pad reads from the associated device to the number of bytes set in pad_size(). Mostly used on HP-UX where /dev/log is a named pipe and every write is padded to 2048 bytes.
program filename with path   The name of the application to start and read messages from.
program_override string   Replaces the $PROGRAM part of the message with the parameter string. For example, to mark every message coming from the kernel, include the program_override("kernel") option in the source containing /proc/kmsg. NOTE: This option replaces the deprecated log_prefix() option.
time_zone() timezone in the form +/-HH:MM   The default timezone for messages read from the source. Applies only if no timezone is specified within the message itself.

Table 8.3. Options of the program() source


[Example] Example 8.7. Using the program() driver 
source s_program { program("/etc/init.d/mydaemon"); };

8.1.5. sun-streams() driver

Solaris uses its STREAMS framework to send messages to the syslogd process.

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

[Note] Note

The sun-streams() driver must be enabled when the syslog-ng application is compiled (see ./configure --help).

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

Declaration:
    sun-streams(name_of_the_streams_device door(filename_of_the_door));
Name Type Default Description
door() string none Specifies the filename of a door to open, needed on Solaris above 2.5.1.
flags() empty-lines, kernel, no-multi-line, no-parse, store-legacy-msghdr, syslog-protocol, validate-utf8 empty set

Specifies the log parsing options of the source.

Use the empty-lines flag to keep the empty lines of the messages. By default, syslog-ng removes empty lines automatically.

The kernel flag makes the source default to the LOG_KERN | LOG_CRIT priority if not specified otherwise.

The no-multi-line flag disables line-breaking in the messages; the entire message is converted to a single line.

By default, syslog-ng parses incoming messages as syslog messages. If a source does not send properly formatted messages, use the no-parse flag to disable message parsing for the source. As a result, syslog-ng will generate a new syslog header and put the entire incoming message into the MSG part of the syslog message.

The no-parse flag completely disables syslog message parsing and processes the complete line as the message part of a syslog message. Other information (timestamp, host, etc.) is added automatically. This flag is useful for parsing files not complying to the syslog format.

If the store-legacy-msghdr flag is enabled, syslog-ng stores the original incoming header of the log message. This is useful of the original format of a non-syslog-compliant message must be retained (syslog-ng automatically corrects minor header errors, e.g., adds a whitespace before msg in the following message: Jan 22 10:06:11 host program:msg). Note that store-legacy-msghdr should be enabled when receiving messages from syslog-ng Agent for Windows clients that use the Snare-compatible mode.

The syslog-protocol flag specifies that incoming messages are expected to be formatted according to the new IETF syslog protocol standard. Note that this flag is not needed for the syslog driver.

The validate-utf8 flag enables encoding-verification for messages formatted according to the new IETF syslog standard (see Section 2.18.2, “IETF-syslog messages” for details). If the BOM character is missing, but the message is otherwise UTF-8 compliant, syslog-ng automatically adds the BOM character to the message.
follow_freq() number 1 Indicates that the source should be checked periodically instead of being polled. This is useful for files which always indicate readability, even though no new lines were appended. If this value is higher than zero, syslog-ng will not attempt to use poll() on the file, but checks whether the file changed every time the follow_freq() interval (in seconds) has elapsed. Floating-point numbers (e.g., 1.5) can be used as well.
keep_timestamp() yes or no yes Specifies whether syslog-ng should accept the timestamp received from the sending application or client. If disabled, the time of reception will be used instead. This option can be specified globally, and per-source as well. The local setting of the source overrides the global option if available.
log_fetch_limit() number The value specified by the global log_fetch_limit() option, which defaults to 10. The maximum number of messages fetched from a source during a single poll loop. The destination queues might fill up before flow-control could stop reading if log_fetch_limit() is too high.
log_iw_size() number 100 The size of the initial window, this value is used during flow control.
log_msg_size() number Use the global log_msg_size() option, which defaults to 8192. Specifies the maximum length of incoming log messages. Uses the value of the global option if not specified.
log_prefix() (DEPRECATED) string   A string added to the beginning of every log message. It can be used to add an arbitrary string to any log source, though it is most commonly used for adding kernel: to the kernel messages on Linux. NOTE: This option is deprecated. Use program_override() instead.
optional() yes or no   Instruct syslog-ng to ignore the error if a specific source cannot be initialized. No other attempts to initialize the source will be made until the configuration is reloaded. This option currently applies to the pipe(), unix-dgram, and unix-stream drivers.
pad_size() number 0 Specifies input padding. Some operating systems (such as HP-UX) pad all 0 messages to block boundary. This option can be used to specify the block size. (HP-UX uses 2048 bytes). Syslog-ng will pad reads from the associated device to the number of bytes set in pad_size(). Mostly used on HP-UX where /dev/log is a named pipe and every write is padded to 2048 bytes.
program_override string   Replaces the $PROGRAM part of the message with the parameter string. For example, to mark every message coming from the kernel, include the program_override("kernel") option in the source containing /proc/kmsg. NOTE: This option replaces the deprecated log_prefix() option.
time_zone() timezone in the form +/-HH:MM   The default timezone for messages read from the source. Applies only if no timezone is specified within the message itself.

Table 8.4. Options for sun-streams


[Example] Example 8.8. Using the sun-streams() driver 
source s_stream { sun-streams("/dev/log" door("/etc/.syslog_door")); };

8.1.6. syslog()

This driver enables to receive messages from the network using the new standard syslog protocol and message format (see Section 2.18.2, “IETF-syslog messages” for details about the protocol). UDP, TCP, and TLS-encrypted TCP can all be used to transport the messages.

Declaration:
    syslog(ip() port() transport() options());
Name Type Default Description
flags() empty-lines, kernel, no-multi-line, no-parse, store-legacy-msghdr, syslog-protocol, validate-utf8 empty set

Specifies the log parsing options of the source.

Use the empty-lines flag to keep the empty lines of the messages. By default, syslog-ng removes empty lines automatically.

The kernel flag makes the source default to the LOG_KERN | LOG_CRIT priority if not specified otherwise.

The no-multi-line flag disables line-breaking in the messages; the entire message is converted to a single line.

By default, syslog-ng parses incoming messages as syslog messages. If a source does not send properly formatted messages, use the no-parse flag to disable message parsing for the source. As a result, syslog-ng will generate a new syslog header and put the entire incoming message into the MSG part of the syslog message.

The no-parse flag completely disables syslog message parsing and processes the complete line as the message part of a syslog message. Other information (timestamp, host, etc.) is added automatically. This flag is useful for parsing files not complying to the syslog format.

If the store-legacy-msghdr flag is enabled, syslog-ng stores the original incoming header of the log message. This is useful of the original format of a non-syslog-compliant message must be retained (syslog-ng automatically corrects minor header errors, e.g., adds a whitespace before msg in the following message: Jan 22 10:06:11 host program:msg). Note that store-legacy-msghdr should be enabled when receiving messages from syslog-ng Agent for Windows clients that use the Snare-compatible mode.

The syslog-protocol flag specifies that incoming messages are expected to be formatted according to the new IETF syslog protocol standard. Note that this flag is not needed for the syslog driver.

The validate-utf8 flag enables encoding-verification for messages formatted according to the new IETF syslog standard (see Section 2.18.2, “IETF-syslog messages” for details). If the BOM character is missing, but the message is otherwise UTF-8 compliant, syslog-ng automatically adds the BOM character to the message.
follow_freq() number 1 Indicates that the source should be checked periodically instead of being polled. This is useful for files which always indicate readability, even though no new lines were appended. If this value is higher than zero, syslog-ng will not attempt to use poll() on the file, but checks whether the file changed every time the follow_freq() interval (in seconds) has elapsed. Floating-point numbers (e.g., 1.5) can be used as well.
host_override() string   Replaces the $HOST part of the message with the parameter string.
ip() or localip() string 0.0.0.0 The IP address to bind to. Note that this is not the address where messages are accepted from.
ip_tos() number 0 Specifies the Type-of-Service value of outgoing packets.
ip_ttl() number 0 Specifies the Time-To-Live value of outgoing packets.
keep-alive() yes or no yes Specifies whether connections to sources should be closed when syslog-ng is restarted (upon the receipt of a SIGHUP signal). Note that this applies to the server (source) side of the syslog-ng connections, client-side (destination) connections are always reopened after receiving a HUP signal unless the keep-alive option is enabled for the destination.
keep_hostname() yes or no no Enable or disable hostname rewriting. Enable this option to use hostname-related macros. This option can be specified globally, and per-source as well. The local setting of the source overrides the global option if available. When relaying messages, enable this option on the syslog-ng server and also on every relay, otherwise syslog-ng will treat incoming messages as if they were sent by the last relay.
keep_timestamp() yes or no yes Specifies whether syslog-ng should accept the timestamp received from the sending application or client. If disabled, the time of reception will be used instead. This option can be specified globally, and per-source as well. The local setting of the source overrides the global option if available.
log_fetch_limit() number The value specified by the global log_fetch_limit() option, which defaults to 10. The maximum number of messages fetched from a source during a single poll loop. The destination queues might fill up before flow-control could stop reading if log_fetch_limit() is too high.
log_iw_size() number 100 The size of the initial window, this value is used during flow control.
log_msg_size() number Use the global log_msg_size() option, which defaults to 8192. Specifies the maximum length of incoming log messages. Uses the value of the global option if not specified.
log_prefix() (DEPRECATED) string   A string added to the beginning of every log message. It can be used to add an arbitrary string to any log source, though it is most commonly used for adding kernel: to the kernel messages on Linux. NOTE: This option is deprecated. Use program_override() instead.
max-connections() number 10 Specifies the maximum number of simultaneous connections.
optional() yes or no   Instruct syslog-ng to ignore the error if a specific source cannot be initialized. No other attempts to initialize the source will be made until the configuration is reloaded. This option currently applies to the pipe(), unix-dgram, and unix-stream drivers.
pad_size() number 0 Specifies input padding. Some operating systems (such as HP-UX) pad all 0 messages to block boundary. This option can be used to specify the block size. (HP-UX uses 2048 bytes). Syslog-ng will pad reads from the associated device to the number of bytes set in pad_size(). Mostly used on HP-UX where /dev/log is a named pipe and every write is padded to 2048 bytes.
port() or localport() number 514 The port number to bind to.
program_override string   Replaces the $PROGRAM part of the message with the parameter string. For example, to mark every message coming from the kernel, include the program_override("kernel") option in the source containing /proc/kmsg. NOTE: This option replaces the deprecated log_prefix() option.
so_broadcast() yes or no no This option controls the SO_BROADCAST socket option required to make syslog-ng send messages to a broadcast address. See the socket(7) manual page for details.
so_rcvbuf() number 0 Specifies the size of the socket receive buffer in bytes. See the socket(7) manual page for details.
so_sndbuf() number 0 Specifies the size of the socket send buffer in bytes. See the socket(7) manual page for details.
so_broadcast() yes or no no This option controls the SO_BROADCAST socket option required to make syslog-ng send messages to a broadcast address. See the socket(7) manual page for details.
so_keepalive() yes or no no Enables keep-alive messages, keeping the socket open. This only effects TCP and UNIX-stream sockets. See the socket(7) manual page for details.
tcp-keep-alive() yes or no no This is an obsolete alias of the so_keepalive() option.
time_zone() timezone in the form +/-HH:MM   The default timezone for messages read from the source. Applies only if no timezone is specified within the message itself.
transport udp, tcp, or tls tcp Specifies the protocol used to receive messages from the source.
tls() tls options n/a This option sets various TLS specific options like key/certificate files and trusted CA locations and can only be used with the tcp transport protocols. See Section 8.10, “TLS options” for more information.
use_dns() yes, no, persist_only yes Enable or disable DNS usage. The

persist_only

option attempts to resolve hostnames locally from file (e.g., from /etc/hosts). syslog-ng blocks on DNS queries, so enabling DNS may lead to a Denial of Service attack. To prevent DoS, protect your syslog-ng network endpoint with firewall rules, and make sure that all hosts which may get to syslog-ng are resolvable. This option can be specified globally, and per-source as well. The local setting of the source overrides the global option if available.
use_fqdn() yes or no no Add Fully Qualified Domain Name instead of short hostname. This option can be specified globally, and per-source as well. The local setting of the source overrides the global option if available.

Table 8.5. Options for syslog() sources


[Example] Example 8.9. Using the syslog() driver

TCP source listening on the localhost on port 1999.

source s_syslog { syslog(ip(127.0.0.1) port(1999) transport("tcp")); };

UDP source with defaults.

source s_udp { syslog( transport("udp")); };

Encrypted source where the client is also authenticated. See Section 8.10, “TLS options” for details on the encryption settings.

source s_syslog_tls{ syslog(
                    ip(10.100.20.40)
                    transport("tls")
                    tls(
                    peer-verify(required-trusted)
                    ca_dir('/opt/syslog-ng/etc/syslog-ng/keys/ca.d/')
                    key_file('/opt/syslog-ng/etc/syslog-ng/keys/server_privatekey.pem')
                    cert_file('/opt/syslog-ng/etc/syslog-ng/keys/server_certificate.pem')
                    )
                    );};

8.1.7. tcp(), tcp6(), udp() and udp6()

The tcp(), tcp6(), udp(), udp6() drivers can receive messages from the network using the TCP and UDP networking protocols. The tcp6() and udp6() drivers use the IPv6 network protocol, while tcp() and udp() use IPv4.

The tcp() and udp() drivers do not have any required 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.

[Note] Note

The tcp port 514 is reserved for use with rshell, so select a different port if syslog-ng and rshell is used at the same time.

If you specify a multicast bind address to udp() and udp6(), syslog-ng will automatically join the necessary multicast group. TCP does not support multicasting.

The syslog-ng Premium Edition application supports TLS (Transport Layer Security, also known as SSL) for the tcp() and tcp6() drivers. See the TLS-specific options below and Section 3.13, “Encrypting log messages with TLS” for details.

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

The following options are valid for tcp(), tcp6(), udp(), and udp6() drivers:

Name Type Default Description
encoding() string   Specifies the characterset (encoding, e.g., UTF-8) of messages using the legacy BSD-syslog protocol. To list the available character sets on a host, execute the iconv -l command.
flags() empty-lines, kernel, no-multi-line, no-parse, store-legacy-msghdr, syslog-protocol, validate-utf8 empty set

Specifies the log parsing options of the source.

Use the empty-lines flag to keep the empty lines of the messages. By default, syslog-ng removes empty lines automatically.

The kernel flag makes the source default to the LOG_KERN | LOG_CRIT priority if not specified otherwise.

The no-multi-line flag disables line-breaking in the messages; the entire message is converted to a single line.

By default, syslog-ng parses incoming messages as syslog messages. If a source does not send properly formatted messages, use the no-parse flag to disable message parsing for the source. As a result, syslog-ng will generate a new syslog header and put the entire incoming message into the MSG part of the syslog message.

The no-parse flag completely disables syslog message parsing and processes the complete line as the message part of a syslog message. Other information (timestamp, host, etc.) is added automatically. This flag is useful for parsing files not complying to the syslog format.

If the store-legacy-msghdr flag is enabled, syslog-ng stores the original incoming header of the log message. This is useful of the original format of a non-syslog-compliant message must be retained (syslog-ng automatically corrects minor header errors, e.g., adds a whitespace before msg in the following message: Jan 22 10:06:11 host program:msg). Note that store-legacy-msghdr should be enabled when receiving messages from syslog-ng Agent for Windows clients that use the Snare-compatible mode.

The syslog-protocol flag specifies that incoming messages are expected to be formatted according to the new IETF syslog protocol standard. Note that this flag is not needed for the syslog driver.

The validate-utf8 flag enables encoding-verification for messages formatted according to the new IETF syslog standard (see Section 2.18.2, “IETF-syslog messages” for details). If the BOM character is missing, but the message is otherwise UTF-8 compliant, syslog-ng automatically adds the BOM character to the message.
follow_freq() number 1 Indicates that the source should be checked periodically instead of being polled. This is useful for files which always indicate readability, even though no new lines were appended. If this value is higher than zero, syslog-ng will not attempt to use poll() on the file, but checks whether the file changed every time the follow_freq() interval (in seconds) has elapsed. Floating-point numbers (e.g., 1.5) can be used as well.
host_override() string   Replaces the $HOST part of the message with the parameter string.
ip() or localip() string 0.0.0.0 The IP address to bind to. Note that this is not the address where messages are accepted from.
ip_tos() number 0 Specifies the Type-of-Service value of outgoing packets.
ip_ttl() number 0 Specifies the Time-To-Live value of outgoing packets.
keep-alive() yes or no yes Specifies whether connections to sources should be closed when syslog-ng is restarted (upon the receipt of a SIGHUP signal). Note that this applies to the server (source) side of the syslog-ng connections, client-side (destination) connections are always reopened after receiving a HUP signal unless the keep-alive option is enabled for the destination.
keep_hostname() yes or no no Enable or disable hostname rewriting. Enable this option to use hostname-related macros. This option can be specified globally, and per-source as well. The local setting of the source overrides the global option if available. When relaying messages, enable this option on the syslog-ng server and also on every relay, otherwise syslog-ng will treat incoming messages as if they were sent by the last relay.
keep_timestamp() yes or no yes Specifies whether syslog-ng should accept the timestamp received from the sending application or client. If disabled, the time of reception will be used instead. This option can be specified globally, and per-source as well. The local setting of the source overrides the global option if available.
log_fetch_limit() number The value specified by the global log_fetch_limit() option, which defaults to 10. The maximum number of messages fetched from a source during a single poll loop. The destination queues might fill up before flow-control could stop reading if log_fetch_limit() is too high.
log_iw_size() number 100 The size of the initial window, this value is used during flow control.
log_msg_size() number Use the global log_msg_size() option, which defaults to 8192. Specifies the maximum length of incoming log messages. Uses the value of the global option if not specified.
log_prefix() (DEPRECATED) string   A string added to the beginning of every log message. It can be used to add an arbitrary string to any log source, though it is most commonly used for adding kernel: to the kernel messages on Linux. NOTE: This option is deprecated. Use program_override() instead.
max-connections() number 10 Specifies the maximum number of simultaneous connections.
optional() yes or no   Instruct syslog-ng to ignore the error if a specific source cannot be initialized. No other attempts to initialize the source will be made until the configuration is reloaded. This option currently applies to the pipe(), unix-dgram, and unix-stream drivers.
pad_size() number 0 Specifies input padding. Some operating systems (such as HP-UX) pad all 0 messages to block boundary. This option can be used to specify the block size. (HP-UX uses 2048 bytes). Syslog-ng will pad reads from the associated device to the number of bytes set in pad_size(). Mostly used on HP-UX where /dev/log is a named pipe and every write is padded to 2048 bytes.
port() or localport() number 514 The port number to bind to.
program_override string   Replaces the $PROGRAM part of the message with the parameter string. For example, to mark every message coming from the kernel, include the program_override("kernel") option in the source containing /proc/kmsg. NOTE: This option replaces the deprecated log_prefix() option.
so_broadcast() yes or no no This option controls the SO_BROADCAST socket option required to make syslog-ng send messages to a broadcast address. See the socket(7) manual page for details.
so_keepalive() yes or no no Enables keep-alive messages, keeping the socket open. This only effects TCP and UNIX-stream sockets. See the socket(7) manual page for details.
so_rcvbuf() number 0 Specifies the size of the socket receive buffer in bytes. See the socket(7) manual page for details.
so_sndbuf() number 0 Specifies the size of the socket send buffer in bytes. See the socket(7) manual page for details.
tcp-keep-alive() yes or no no This is an obsolete alias of the so_keepalive() option.
time_zone() timezone in the form +/-HH:MM   The default timezone for messages read from the source. Applies only if no timezone is specified within the message itself.
tls() tls options n/a This option sets various TLS specific options like key/certificate files and trusted CA locations and can only be used with the tcp transport protocols. See Section 8.10, “TLS options” for more information.
use_dns() yes, no, persist_only yes Enable or disable DNS usage. The

persist_only

option attempts to resolve hostnames locally from file (e.g., from /etc/hosts). syslog-ng blocks on DNS queries, so enabling DNS may lead to a Denial of Service attack. To prevent DoS, protect your syslog-ng network endpoint with firewall rules, and make sure that all hosts which may get to syslog-ng are resolvable. This option can be specified globally, and per-source as well. The local setting of the source overrides the global option if available.
use_fqdn() yes or no no Add Fully Qualified Domain Name instead of short hostname. This option can be specified globally, and per-source as well. The local setting of the source overrides the global option if available.

Table 8.6. Options for tcp, tcp6, udp, and udp6 drivers


[Example] Example 8.10. Using the udp() and tcp() drivers

A simple udp() source with default settings.

source s_udp { udp(); };# An UDP source with default settings.

A TCP source listening on the localhost interface, with a limited number of connections allowed.

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

A TCP source listening on a TLS-encrypted channel.

source s_tcp { tcp(ip(127.0.0.1) port(1999) 
                   tls(peer-verify('required-trusted') 
                       key_file('/opt/syslog-ng/etc/syslog-ng/syslog-ng.key') 
                   cert_file('/opt/syslog-ng/etc/syslog-ng/syslog-ng.crt'))); 
};

A TCP source listening for messages using the IETF-syslog message format. Note that for transferring IETF-syslog messages, generally you are recommended to use the syslog() driver on both the client and the server, as it uses both the IETF-syslog message format and the protocol. See Section 3.3.5, “Collecting messages using the IETF syslog protocol” for details.

source s_tcp_syslog { tcp(ip(127.0.0.1) port(1999) flags(syslog-protocol)); };

8.1.8. unix-stream() and unix-dgram()

These two drivers behave similarly: they open an AF_UNIX socket and start listening on it for messages.

Both unix-stream and unix-dgram have a single required argument, specifying the filename of the socket to create. 

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

The following options can be specified for these divers:

Name Type Default Description
encoding() string   Specifies the characterset (encoding, e.g., UTF-8) of messages using the legacy BSD-syslog protocol. To list the available character sets on a host, execute the iconv -l command.
flags() empty-lines, kernel, no-multi-line, no-parse, store-legacy-msghdr, syslog-protocol, validate-utf8 empty set

Specifies the log parsing options of the source.

Use the empty-lines flag to keep the empty lines of the messages. By default, syslog-ng removes empty lines automatically.

The kernel flag makes the source default to the LOG_KERN | LOG_CRIT priority if not specified otherwise.

The no-multi-line flag disables line-breaking in the messages; the entire message is converted to a single line.

By default, syslog-ng parses incoming messages as syslog messages. If a source does not send properly formatted messages, use the no-parse flag to disable message parsing for the source. As a result, syslog-ng will generate a new syslog header and put the entire incoming message into the MSG part of the syslog message.

The no-parse flag completely disables syslog message parsing and processes the complete line as the message part of a syslog message. Other information (timestamp, host, etc.) is added automatically. This flag is useful for parsing files not complying to the syslog format.

If the store-legacy-msghdr flag is enabled, syslog-ng stores the original incoming header of the log message. This is useful of the original format of a non-syslog-compliant message must be retained (syslog-ng automatically corrects minor header errors, e.g., adds a whitespace before msg in the following message: Jan 22 10:06:11 host program:msg). Note that store-legacy-msghdr should be enabled when receiving messages from syslog-ng Agent for Windows clients that use the Snare-compatible mode.

The syslog-protocol flag specifies that incoming messages are expected to be formatted according to the new IETF syslog protocol standard. Note that this flag is not needed for the syslog driver.

The validate-utf8 flag enables encoding-verification for messages formatted according to the new IETF syslog standard (see Section 2.18.2, “IETF-syslog messages” for details). If the BOM character is missing, but the message is otherwise UTF-8 compliant, syslog-ng automatically adds the BOM character to the message.
follow_freq() number 1 Indicates that the source should be checked periodically instead of being polled. This is useful for files which always indicate readability, even though no new lines were appended. If this value is higher than zero, syslog-ng will not attempt to use poll() on the file, but checks whether the file changed every time the follow_freq() interval (in seconds) has elapsed. Floating-point numbers (e.g., 1.5) can be used as well.
group() string root Set the gid of the socket.
host_override() string   Replaces the $HOST part of the message with the parameter string.
keep-alive() yes or no yes Selects whether to keep connections open when syslog-ng is restarted; cannot be used with unix-dgram().
keep_timestamp() yes or no yes Specifies whether syslog-ng should accept the timestamp received from the sending application or client. If disabled, the time of reception will be used instead. This option can be specified globally, and per-source as well. The local setting of the source overrides the global option if available.
log_fetch_limit() number The value specified by the global log_fetch_limit() option, which defaults to 10. The maximum number of messages fetched from a source during a single poll loop. The destination queues might fill up before flow-control could stop reading if log_fetch_limit() is too high.
log_iw_size() number 100 The size of the initial window, this value is used during flow control.
log_msg_size() number Use the global log_msg_size() option, which defaults to 8192. Specifies the maximum length of incoming log messages. Uses the value of the global option if not specified.
log_prefix() (DEPRECATED) string   A string added to the beginning of every log message. It can be used to add an arbitrary string to any log source, though it is most commonly used for adding kernel: to the kernel messages on Linux. NOTE: This option is deprecated. Use program_override() instead.
max-connections() number 256 Limits the number of simultaneously open connections. Cannot be used with unix-dgram().
optional() yes or no   Instruct syslog-ng to ignore the error if a specific source cannot be initialized. No other attempts to initialize the source will be made until the configuration is reloaded. This option currently applies to the pipe(), unix-dgram, and unix-stream drivers.
owner() string root Set the uid of the socket.
pad_size() number 0 Specifies input padding. Some operating systems (such as HP-UX) pad all 0 messages to block boundary. This option can be used to specify the block size. (HP-UX uses 2048 bytes). Syslog-ng will pad reads from the associated device to the number of bytes set in pad_size(). Mostly used on HP-UX where /dev/log is a named pipe and every write is padded to 2048 bytes.
perm() number 0666 Set the permission mask. For octal numbers prefix the number with '0', e.g.: use 0755 for rwxr-xr-x.
program_override string   Replaces the $PROGRAM part of the message with the parameter string. For example, to mark every message coming from the kernel, include the program_override("kernel") option in the source containing /proc/kmsg. NOTE: This option replaces the deprecated log_prefix() option.
so_broadcast() yes or no no This option controls the SO_BROADCAST socket option required to make syslog-ng send messages to a broadcast address. See the socket(7) manual page for details.
so_keepalive() yes or no no Enables keep-alive messages, keeping the socket open. This only effects TCP and UNIX-stream sockets. See the socket(7) manual page for details.
so_rcvbuf() number 0 Specifies the size of the socket receive buffer in bytes. See the socket(7) manual page for details.
so_sndbuf() number 0 Specifies the size of the socket send buffer in bytes. See the socket(7) manual page for details.
time_zone() timezone in the form +/-HH:MM   The default timezone for messages read from the source. Applies only if no timezone is specified within the message itself.

Table 8.7. Options for unix-stream() and unix-dgram()


[Example] Example 8.11. Using the unix-stream() and unix-dgram() drivers 
source s_stream { unix-stream("/dev/log" max-connections(10)); };
source s_dgram { unix-dgram("/var/run/log"); };

© 2007-2008 BalaBit IT Security
Please send your comments or documentation bugs to: documentation@balabit.com

Prev  Up  Next
Chapter 8. Reference  Home | Contents  8.2. Destination drivers