Logging with syslog-ng
Chapter 6. Collecting log messages — sources and source drivers
6.6. Receiving messages from external applications
The program driver starts an external application and reads messages from the standard output (stdout) of the ap-plication. 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.9. Using the program() driver
source s_program { program("/etc/init.d/mydaemon"); };
Note
The program is restarted automatically if it exits.
6.6.1. program() source options
Theprogramdriver has the following options:
flags()
empty-lines, kernel, no-multi-line, no-parse, 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.
Receiving messages from external applications
■ kernel: Thekernelflag makes the source default to theLOG_KERN | LOG_CRITpriority 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 { udp(port(2000) flags(no-hostname)); };
■ no-multi-line: The no-multi-lineflag 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 theno-parseflag to disable message parsing for the source. As a result, syslog-ng will generate a new syslog header and put the entire incomisyslog-ng message into the MSG part of the syslog message.
■ no-parse: Theno-parseflag completely disables syslog message parsing and processes the complete line as the message part of a syslog message. Other information (timestamp, host, and so on) is added automatically. This flag is useful for parsing files not complying to the syslog format.
■ store-legacy-msghdr: If thestore-legacy-msghdrflag 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, for example, adds a whitespace before msg in the following message: Jan 22 10:06:11 host program:msg). Note that store-legacy-msghdrshould be enabled when receiving messages from syslog-ng Agent for Windows clients that use the Snare-compatible mode.
■ syslog-protocol: 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 thesyslogdriver.
■ validate-utf8: Thevalidate-utf8flag enables encoding-verification for messages formatted according to the new IETF syslog standard (for details, see Section 2.9.2, IETF-syslog messages (p. 13)). 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 Type:
1 Default:
Description: Indicates that the source should be checked periodically. 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 usepoll()on the file, but checks whether the file changed every time thefollow_freq()interval (in seconds) has elapsed. Floating-point numbers (for example1.5) can be used as well.
keep_timestamp()
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.
log_fetch_limit() number Type:
The value specified by the global log_fetch_limit() option, which defaults to10. 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:
100 Default:
Description: The size of the initial window, this value is used during flow control.
log_msg_size() number Type:
Use the globallog_msg_size()option, which defaults to8192. Default:
Description: Specifies the maximum length of incoming log messages. Uses the value of the global option if not specified.
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 thepipe(), unix-dgram, andunix-streamdrivers.
pad_size() number Type:
program() source options
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 applic-ation will pad reads from the associated device to the number of bytes set inpad_size(). Mostly used on HP-UX where/dev/logis a named pipe and every write is padded to 2048 bytes. Ifpad_sizewas 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. NOTE: This option replaces the deprecatedlog_prefix()option.
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 example tags("dmz",
"router"). This option is available only in syslog-ng 3.1 and later.
time_zone()
timezone in +/-HH:MM format Type:
Default:
Description: The default timezone for messages read from the source. Applies only if no timezone is specified within the message itself.