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.
program(filename);
|
NOTE:
The program is restarted automatically if it exits. |
The program driver has the following options:
Type: | assume-utf8, empty-lines, expect-hostname, kernel, no-hostname, no-multi-line, no-parse, sanitize-utf8, store-legacy-msghdr, store-raw-message, syslog-protocol, validate-utf8 |
Default: | empty set |
Description: Specifies the log parsing options of the source.
assume-utf8: The assume-utf8 flag assumes that the incoming messages are UTF-8 encoded, but does not verify the encoding. If you explicitly want to validate the UTF-8 encoding of the incoming message, use the validate-utf8 flag.
empty-lines: Use the empty-lines flag to keep the empty lines of the messages. By default, syslog-ng OSE removes empty lines automatically.
expect-hostname: If the expect-hostname flag 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 the no-hostname flag by default.
guess-timezone: Attempt to guess the timezone of the message if this information is not available in the message. Works when the incoming message stream is close to real time, and the timezone information is missing from the timestamp.
kernel: The kernel flag makes the source default to the LOG_KERN | LOG_NOTICE priority if not specified otherwise.
no-hostname: Enable the no-hostname flag 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: The no-multi-line flag 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 file() and pipe() drivers support multi-line messages.
no-parse: By default, syslog-ng OSE parses incoming messages as syslog messages. The no-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 MESSAGE part of the syslog message (available using the ${MESSAGE} macro). This flag is useful for parsing messages not complying to the syslog format.
If you are using the flags(no-parse) option, then syslog message parsing is completely disabled, and the entire incoming message is treated as the ${MESSAGE} part of a syslog message. In this case, syslog-ng OSE generates a new syslog header (timestamp, host, and so on) automatically. Note that since flags(no-parse) disables message parsing, it interferes with other flags, for example, disables flags(no-multi-line).
dont-store-legacy-msghdr: By default, syslog-ng stores the original incoming header of the log message. This is useful if 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). If you do not want to store the original header of the message, enable the dont-store-legacy-msghdr flag.
sanitize-utf8: When using the sanitize-utf8 flag, syslog-ng OSE converts non-UTF-8 input to an escaped form, which is valid UTF-8.
store-raw-message: Save the original message as received from the client in the ${RAWMSG} macro. You can forward this raw message in its original form to another syslog-ng node using the syslog-ng() destination, or to a SIEM system, ensuring that the SIEM can process it. Available only in
syslog-protocol: The syslog-protocol flag 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 the syslog driver, 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 IETF-syslog messages). If the
Description: This option makes it possible to execute external programs when the relevant driver is initialized or torn down. The hook-commands() can be used with all source and destination drivers with the exception of the usertty() and internal() drivers.
|
NOTE: The syslog-ng OSE application must be able to start and restart the external program, and have the necessary permissions to do so. For example, if your host is running AppArmor or SELinux, you might have to modify your AppArmor or SELinux configuration to enable syslog-ng OSE to execute external applications. |
To execute an external program when syslog-ng OSE starts or stops, use the following options:
startup() | |
Type: | string |
Default: | N/A |
Description: Defines the external program that is executed as syslog-ng OSE starts. |
shutdown() | |
Type: | string |
Default: | N/A |
Description: Defines the external program that is executed as syslog-ng OSE stops. |
To execute an external program when the syslog-ng OSE configuration is initiated or torn down, for example, on startup/shutdown or during a syslog-ng OSE reload, use the following options:
setup() | |
Type: | string |
Default: | N/A |
Description: Defines an external program that is executed when the syslog-ng OSE configuration is initiated, for example, on startup or during a syslog-ng OSE reload. |
teardown() | |
Type: | string |
Default: | N/A |
Description: Defines an external program that is executed when the syslog-ng OSE configuration is stopped or torn down, for example, on shutdown or during a syslog-ng OSE reload. |
In the following example, the hook-commands() is used with the network() driver and it opens an iptables port automatically as syslog-ng OSE is started/stopped.
The assumption in this example is that the LOGCHAIN chain is part of a larger ruleset that routes traffic to it. Whenever the syslog-ng OSE created rule is there, packets can flow, otherwise the port is closed.
source { network(transport(udp) hook-commands( startup("iptables -I LOGCHAIN 1 -p udp --dport 514 -j ACCEPT") shutdown("iptables -D LOGCHAIN 1") ) ); };
Type: | yes or no |
Default: | yes |
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.
|
Caution:
To use the S_ macros, the keep-timestamp() option must be enabled (this is the default behavior of syslog-ng OSE). |
Type: | number |
Default: | 100 |
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 if log-fetch-limit() is too high.
Type: | yes|no |
Default: | yes |
Description: By default, when program() starts an external application or script, it inherits the entire environment of the parent process (that is, syslog-ng OSE). Use inherit-environment(no) to prevent this.
Type: | number |
Default: | 100 |
Description: The size of the initial window, this value is used during flow-control. Its value cannot be lower than 100, unless the dynamic-window-size() option is enabled. For details on flow-control, see Managing incoming and outgoing messages with flow-control.
Type: | number (bytes) |
Default: | Use the global log-msg-size() option, which defaults to 65536. |
Description: Maximum length of a message in bytes. This length includes the entire message (the data structure and individual fields). The maximal value that can be set is 268435456 bytes (256MB). For messages using the IETF-syslog message format (RFC5424), the maximal size of the value of an SDATA field is 64kB.
In most cases, it is not recommended to set log-msg-size() higher than 10 MiB.
For details on how encoding affects the size of the message, see Message size and encoding.
Uses the value of the global option if not specified.
Type: | string |
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 adding kernel: to the kernel messages on Linux.
|
NOTE:
This option is deprecated. Use program-override() instead. |
Type: | yes or no |
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, and unix-stream drivers.
Type: | number |
Default: | 0 |
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. The syslog-ng OSE application 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. If pad-size() was given and the incoming message does not fit into pad-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
Type: | filename with path |
Default: |
Description: The name of the application to start and read messages from.
Type: | string |
Default: |
Description: 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.
Type: | string |
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.
Type: | name of the timezone, or the timezone offset |
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 by using the name, for example, time-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/zoneinfo directory.
The Python source allows you to write your own source in Python. You can import external Python modules to receive or fetch the messages. Since many services have a Python library, the Python source makes integrating syslog-ng OSE very easy and quick.
You can write two different type of sources in Python:
Server-style sources that receives messages. Write server-style sources if you want to use an event-loop based, nonblocking server framework in Python, or if you want to implement a custom loop.
Fetcher-style sources that actively fetch messages. In general, write fetcher-style sources (for example, when using simple blocking APIs), unless you explicitly need a server-style source.
This section describes server-style sources. For details on fetcher-style sources, see python-fetcher: writing fetcher-style Python sources.
The following points apply to using Python blocks in syslog-ng OSE in general.
Python parsers and template functions are available in syslog-ng OSE version
Python destinations and sources are available in syslog-ng OSE version
Supported Python versions: 2.7
The Python block must be a top-level block in the syslog-ng OSE configuration file.
If you store the Python code in a separate Python file and only include it in the syslog-ng OSE configuration file, make sure that the PYTHON_PATH environment variable includes the path to the Python file, and export the PYTHON_PATH environment variable. For example, if you start syslog-ng OSE manually from a terminal and you store your Python files in the /opt/syslog-ng/etc directory, use the following command: export PYTHONPATH=/opt/syslog-ng/etc
In production, when syslog-ng OSE starts on boot, you must configure your startup script to include the Python path. The exact method depends on your operating system. For recent Red Hat Enterprise Linux, Fedora, and CentOS distributions that use systemd, the systemctl command sources the /etc/sysconfig/syslog-ng file before starting syslog-ng OSE. (On openSUSE and SLES, /etc/sysconfig/syslog file.) Append the following line to the end of this file: PYTHONPATH="<path-to-your-python-file>", for example, PYTHONPATH="/opt/syslog-ng/etc"
The Python object is initiated every time when syslog-ng OSE is started or reloaded.
The Python block can contain multiple Python functions.
Using Python code in syslog-ng OSE can significantly decrease the performance of syslog-ng OSE, especially if the Python code is slow. In general, the features of syslog-ng OSE are implemented in C, and are faster than implementations of the same or similar features in Python.
Validate and lint the Python code before using it. The syslog-ng OSE application does not do any of this.
Python error messages are available in the internal() source of syslog-ng OSE.
You can access the name-value pairs of syslog-ng OSE directly through a message object or a dict.
To help debugging and troubleshooting your Python code, you can send log messages to the internal() source of syslog-ng OSE. For details, see Logging from your Python code.
Python sources consist of two parts. The first is a syslog-ng OSE source object that you define in your syslog-ng OSE configuration and use in the log path. This object references a Python class, which is the second part of the Python source. The Python class receives or fetches the log messages, and can do virtually anything that you can code in Python. You can either embed the Python class into your syslog-ng OSE configuration file, or store it in an external Python file.
source <name_of_the_python_source>{ python( class("<name_of_the_python_class_executed_by_the_source>") options( "option1" "value1", "option2" "value2" ) ); }; python { from syslogng import LogSource from syslogng import LogMessage class <name_of_the_python_class_executed_by_the_source>(LogSource): def init(self, options): # optional print("init") print(options) self.exit = False return True def deinit(self): # optional print("deinit") def run(self): # mandatory print("run") while not self.exit: # Must create a message msg = LogMessage("this is a log message") self.post_message(msg) def request_exit(self): # mandatory print("exit") self.exit = True };
Server-style Python sources must be inherited from the syslogng.LogSource class, and must implement at least the run and request_exit methods. Multiple inheritance is allowed, but only for pure Python super classes.
You can implement your own event loop, or integrate the event loop of an external framework or library, for example, KafkaConsumer, Flask, Twisted engine, and so on.
To post messages, call LogSource::post_message() method in the run method.
The syslog-ng OSE application initializes Python objects every time when it is started or reloaded. The init method is executed as part of the initialization. You can perform any initialization steps that are necessary for your source to work.
When this method returns with False, syslog-ng OSE does not start. It can be used to check options and return False when they prevent the successful start of the source.
options: This optional argument contains the contents of the options() parameter of the syslog-ng OSE configuration object as a Python dict.
Use the run method to implement an event loop, or start a server framework or library. Create LogMessage instances in this method, and pass them to the log paths by calling LogSource::post_message().
Currently, run stops permanently if an unhandled exception happens.
For details on parsing and posting messages, see Python LogMessage API.
The syslog-ng OSE application calls this method when syslog-ng OSE is shut down or restarted. The request_exit method must shut down the event loop or framework, so the run method can return gracefully. If you use blocking operations within the run() method, use request_exit() to interrupt those operations and set an exit flag, otherwise syslog-ng OSE is not able to stop. Note that syslog-ng OSE calls the request_exit method from a thread different from the source thread.
This method is executed when syslog-ng OSE is stopped or reloaded. This method does not return a value.
For the list of available optional parameters, see python() and python-fetcher() source options.
The LogMessage API allows you to create LogMessage objects in Python sources, parse syslog messages, and set the various fields of the log message.
You can use the LogMessage() method to create a structured log message instance. For example:
from syslogng import LogMessage msg = LogMessage() # Initialize an empty message with default values (recvd timestamp, rcptid, hostid, ...) msg = LogMessage("string or bytes-like object") # Initialize a message and set its ${MESSAGE} field to the specified argument
You can also explicitly set the different values of the log message. For example:
msg["MESSAGE"] = "message" msg["HOST"] = "hostname"
You can set certain special field (timestamp, priority) by using specific methods.
Note the following points when creating a log message:
When setting the hostname, syslog-ng OSE takes the following hostname-related options of the configuration into account: chain-hostnames(), keep-hostname(), use-dns(), and use-fqdn().
Python sources ignore the log-msg-size() option.
The syslog-ng OSE application accepts only one message from every LogSource::post_message() or fetch() call, batching is currently not supported. If your Python code accepts batches of messages, you must pass them to syslog-ng OSE one-by-one. Similarly, if you need to split messages in the source, you must do so in your Python code, and pass the messages separately.
Do not reuse or store LogMessage objects after posting (calling post_message()) or returning the message from fetch().
The parse() method allows you to parse incoming messages as syslog messages. By default, the parse() method attempts to parse the message as an IETF-syslog (RFC5424) log message. If that fails, it parses the log message as a BSD-syslog (RFC3164) log message. Note that syslog-ng OSE takes the parsing-related options of the configuration into account: flags(), keep-hostname(), recv-time-zone().
If keep-hostname() is set to no, syslog-ng OSE ignores the hostname set in the message, and uses the IP address of the syslog-ng OSE host as the hostname (to use the hostname instead of the IP address, set the use-dns() or use-fqdn() options in the Python source).
msg_ietf = LogMessage.parse('<165>1 2003-10-11T22:14:15.003Z mymachine.example.com evntslog - ID47 [exampleSDID@32473 iut="3" eventSource="Application" eventID="1011"] An application event log entry', self.parse_options) msg_bsd = LogMessage.parse('<34>Oct 11 22:14:15 mymachine su: \'su root\' failed for lonvick on /dev/pts/8', self.parse_options)
You can set the priority of the message with the set_pri() method.
msg.set_pri(165)
You can use the set_timestamp() method to set the date and time of the log message.
timestamp = datetime.fromisoformat("2018-09-11T14:49:02.100+02:00") msg.set_timestamp(timestamp) # datetime object, includes timezone information
In Python 2, timezone information cannot be attached to the datetime instance without using an external library. The syslog-ng OSE represents naive datetime objects in UTC.
© ALL RIGHTS RESERVED. Feedback Términos de uso Privacidad Cookie Preference Center