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, guess-timezone, 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 PE removes empty lines automatically.
expect-hostname: If the expect-hostname flag is enabled, syslog-ng PE 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.
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 PE 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 PE 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 PE 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 PE 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 PE 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
| 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 PE). |
| Type: | number |
| Default: | 10 |
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 PE). 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. 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 (64 KiB). |
Description: Maximum length of a message in bytes. This length includes the entire message (the data structure and individual fields). The maximum value that you can set is 268435456 bytes (256 MiB).
For messages using the IETF-syslog message format (RFC5424), the maximal size of the value of an SDATA field is 64 KiB.
NOTE: In most cases, you do not need 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.
You can use human-readable units when setting configuration options. For details, see Notes about the configuration syntax.
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 PE 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 as using the name of the (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 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.
Only the default Python modules are available (that is, you cannot import external Python modules, and One Identity does not support using external Python modules).
The syslog-ng PE application uses its own Python interpreter (shipped with the default syslog-ng PE installation) instead of the system's Python interpreter.
The syslog-ng PE application is shipped with Python version 3.8.
The Python block must be a top-level block in the syslog-ng PE configuration file.
If you store the Python code in a separate Python file and only include it in the syslog-ng PE 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 PE 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 PE 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 PE. (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 PE is started or reloaded.
The Python block can contain multiple Python functions.
Using Python code in syslog-ng PE can significantly decrease the performance of syslog-ng PE, especially if the Python code is slow. In general, the features of syslog-ng PE 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 PE application does not do any of this.
Python error messages are available in the internal() source of syslog-ng PE.
You can access the name-value pairs of syslog-ng PE directly through a message object or a dictionary.
To help debugging and troubleshooting your Python code, you can send log messages to the internal() source of syslog-ng PE. For details, see Logging from your Python code.
|
|
Caution:
This is a Preview Feature, which provides an insight to planned enhancements to functionality in the product. Consider this Preview Feature a work in progress, as it may not represent the final design and functionality. This feature has completed QA release testing, but its full impact on production systems has not been determined yet, and potential future changes in functionality and the user interface may result in compatibility issues in your current settings. One Identity recommends the following:
However, you are welcome to try this feature and if you have any feedback, Contact One Identity. Support Policy on Product Preview Features The One Identity Support Team will:
|
Using Python in syslog-ng PE is recommended only if you are familiar with both Python and syslog-ng PE. One Identity is not responsible for the quality, resource requirements, or any bugs in the Python code, nor any syslog-ng PE crashes, message losses, or any other damage caused by the improper use of this feature, unless explicitly stated in a contract with One Identity.
NOTE: Starting with
log {
source { python(class(PyNetworkSource) options("port" "8080") persist-name("<unique-string>); };
source { python(class(PyNetworkSource) options("port" "8081")); };
};
Alternatively, you can include the following line in the Python package: @staticmethod generate_persist_name. For example:
from syslogng import LogSource
class PyNetworSource(LogSource):
@staticmethod
def generate_persist_name(options):
return options["port"]
def run(self):
pass
def request_exit(self):
passPython sources consist of two parts. The first is a syslog-ng PE source object that you define in your syslog-ng PE 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 PE 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 PE 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 PE 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 PE configuration object as a Python dictionary.
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 PE application calls this method when syslog-ng PE 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 PE is not able to stop. Note that syslog-ng PE calls the request_exit method from a thread different from the source thread.
This method is executed when syslog-ng PE 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 PE 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 PE 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 PE 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 PE 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 PE ignores the hostname set in the message, and uses the IP address of the syslog-ng PE 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 PE represents naive datetime objects in UTC.
In Python 3, naive and timezone-aware datetime objects are both supported.
© 2024 One Identity LLC. ALL RIGHTS RESERVED. Feedback Terms of Use Privacy Cookie Preference Center