Receiving messages from external applications

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

Example 6.18. Using the program() driver

source s_program { program("/etc/init.d/mydaemon"); };

Note

The program is restarted automatically if it exits.

6.9.1. program() source options

Theprogramdriver has the following options:

flags()

assume-utf8, empty-lines, expect-hostname, kernel, no-multi-line, no-parse, sanitize-utf8, store-legacy-msghdr, syslog-protocol, validate-utf8

Type:

empty set Default:

Description: Specifies the log parsing options of the source.

■ empty-lines: Use theempty-linesflag to keep the empty lines of the messages. By default, syslog-ng OSE removes empty lines automatically.

■ expect-hostname: If theexpect-hostnameflag is enabled, syslog-ng OSE will assume that the log message contains a hostname and parse the message accordingly. This is the default behavior for TCP sources. Note that pipe sources use theno-hostnameflag by default.

■ kernel: Thekernelflag makes the source default to theLOG_KERN | LOG_NOTICEpriority if not specified otherwise.

■ no-hostname: Enable theno-hostnameflag if the log message does not include the hostname of the sender host. That way syslog-ng OSE assumes that the first part of the message header is

${PROGRAM} instead of ${HOST}. For example:

source s_dell { network(port(2000) flags(no-hostname)); };

■ no-multi-line: Theno-multi-lineflag disables line-breaking in the messages; the entire message is converted to a single line. Note that this happens only if the underlying transport method actually supports multi-line messages. Currently the , syslog(), network(), unix-dgram() drivers support multi-line messages.

■ no-parse: By default, syslog-ng OSE parses incoming messages as syslog messages. Theno-parse flag completely disables syslog message parsing and processes the complete line as the message part of a syslog message. The syslog-ng OSE application will generate a new syslog header (timestamp, host, and so on) automatically and put the entire incoming message into the MSG part of the syslog message. This flag is useful for parsing messages not complying to the syslog format.

■ dont-store-legacy-msghdr: By default, 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, for example, adds a whitespace beforemsg in the following message:Jan 22 10:06:11 host program:msg). If you do not want to store the original header of the message, enable thedont-store-legacy-msghdrflag.

■ sanitize-utf8: When using thesanitize-utf8flag, syslog-ng OSE converts non-UTF-8 input to an escaped form, which is valid UTF-8.

■ syslog-protocol: Thesyslog-protocolflag specifies that incoming messages are expected to be formatted according to the new IETF syslog protocol standard (RFC5424), but without the frame header. Note that this flag is not needed for thesyslogdriver, which handles only messages that have a frame header.

■ validate-utf8: The validate-utf8 flag enables encoding-verification for messages formatted according to the new IETF syslog standard (for details, see Section 2.8.2, IETF-syslog messages (p. 13)). If theBOMcharacter is missing, but the message is otherwise UTF-8 compliant, syslog-ng automatically adds the BOM character to the message.

The byte order mark (BOM) is a Unicode character used to signal the byte-order of the message text.

program() source options

keep-timestamp() yes or no Type:

yes Default:

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

Warning

To use theS_macros, thekeep-timestamp()option must be enabled (this is the default behavior of syslog-ng OSE).

log-fetch-limit() number Type:

10 Default:

Description: 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 iflog-fetch-limit()is too high.

log-iw-size() number Type:

1000 Default:

Description: The size of the initial window, this value is used during flow control. If themax-connections() option is set, thelog-iw-size()will be divided by the number of connections, otherwiselog-iw-size() is divided by 10 (the default value of the max-connections()option). The resulting number is the initial window size of each connection. For optimal performance when receiving messages from syslog-ng OSE clients, make sure that the window size is larger than theflush-lines()option set in the destination of your clients.

Example 6.19. Initial window size of a connection

Iflog-iw-size(1000)andmax-connections(10), then each connection will have an initial window size of 100.

log-msg-size() number Type:

log-prefix() (DEPRECATED) string

Type:

Default:

Description: 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 addingkernel:to the kernel messages on Linux. NOTE:

This option is deprecated. Useprogram-override()instead.

optional() yes or no Type:

Default:

Description: 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, andunix-streamdrivers.

pad-size() number Type:

0 Default:

Description: Specifies input padding. Some operating systems (such as HP-UX) pad all messages to block boundary. This option can be used to specify the block size. (HP-UX uses 2048 bytes). The syslog-ng OSE application will pad reads from the associated device to the number of bytes set inpad-size(). Mostly used on HP-UX where/dev/log is a named pipe and every write is padded to 2048 bytes. Ifpad-size()was given and the incoming message does not fit intopad-size(), syslog-ng will not read anymore from this pipe and displays the following error message:

Padding was set, and couldn't read enough bytes

program()

filename with path Type:

Default:

Description: The name of the application to start and read messages from.

program-override() string Type:

Default:

Description: Replaces the ${PROGRAM} part of the message with the parameter string. For example, to mark every message coming from the kernel, include theprogram-override("kernel")option in the source containing/proc/kmsg.

program() source options

tags()

string Type:

Default:

Description: Label the messages received from the source with custom tags. Tags must be unique, and enclosed between double quotes. When adding multiple tags, separate them with comma, for exampletags("dmz",

"router"). This option is available only in syslog-ng 3.1 and later.

time-zone()

name of the timezone, or the timezone offset Type:

Default:

Description: The default timezone for messages read from the source. Applies only if no timezone is specified within the message itself.

The timezone can be specified as using the name of the (for exampletime-zone("Europe/Budapest")), or as the timezone offset in +/-HH:MM format (for example+01:00). On Linux and UNIX platforms, the valid timezone names are listed under the/usr/share/zoneinfodirectory.