python() and python-fetcher() source options

This section describes the options of the python() and python-fetcher() sources in syslog-ng OSE.

The python() and python-fetcher() drivers have the following options.

class()

Type:	string
Default:	N/A

Description: The name of the Python class that implements the source, for example:

python(
    class("MyPythonSource")
);

If you want to store the Python code in an external Python file, the class() option must include the name of the Python file containing the class, without the path and the .py extension, for example:

python(
    class("MyPythonfilename.MyPythonSource")
);

For details, see Python code in external files

fetch-no-data-delay()

Type:	integer (seconds)
Default:	-1 (disabled)

Description: If the fetch method of a python-fetcher() source returns with the LogFetcher.FETCH_NO_DATA constant, the source waits fetch-no-data-delay() seconds before calling the fetch method again. If you want to call the fetch method sooner, set the fetch-no-data-delay() option to the number of seconds to wait before calling the fetch method.

flags()

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, threaded, 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.
ignore-aux-data: This flag enables the source to ignore auxiliary data.
kernel: The kernel flag makes the source default to the LOG_KERN | LOG_NOTICE priority if not specified otherwise.
no-header: The no-header flag triggers syslog-ng OSE to parse only the PRI field of incoming messages, and put the rest of the message contents into ${MSG}.

Its functionality is similar to that of the no-parse flag, except the no-header flag does not skip the PRI field.

NOTE: Essentially, the no-header flag signals syslog-ng OSE that the syslog header is not present (or does not adhere to the conventions / RFCs), so the entire message (except from the PRI field) is put into ${MSG}.

Example: using the no-header flag with the syslog-parser() parser

The following example illustrates using the no-header flag with the syslog-parser() parser:
```
  parser p_syslog {
      syslog-parser(
      flags(no-header)
      );
  };
```
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 even though flags(no-parse) disables message parsing, some flags can still be used, for example, the no-multi-line flag.
dont-store-legacy-msghdr: By default, syslog-ng OSE 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 OSE 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 OSE node using the syslog-ng() destination, or to a SIEM system, ensuring that the SIEM can process it. Available only in 3.16 and later.
syslog-protocol: The syslog-protocol flag specifies that incoming messages are expected to be formatted according to the new IETF syslog protocol standard (RFC-5424), 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.
threaded: The threaded flag enables multithreading for the destination. For details on multithreading, see Multithreading and scaling in syslog-ng OSE.

If a parsing or syntax error occurs, use "threaded" nested in quotation marks.
```
  flags(
      validate-utf8
      "threaded"
      store-raw-message
  )
```
NOTE: The file destination uses multiple threads only if the destination filename contains macros.
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 BOM¹ character is missing, but the message is otherwise UTF-8 compliant, syslog-ng OSE automatically adds the BOM character to the message.

keep-hostname()

Type:	yes or no
Default:	no

Description: Enable or disable hostname rewriting.

If enabled (keep-hostname(yes)), syslog-ng OSE assumes that the incoming log message was sent by the host specified in the HOST field of the message.
If disabled (keep-hostname(no)), syslog-ng OSE rewrites the HOST field of the message, either to the IP address (if the use-dns() parameter is set to no), or to the hostname (if the use-dns() parameter is set to yes and the IP address can be resolved to a hostname) of the host sending the message to syslog-ng OSE. For details on using name resolution in syslog-ng OSE, see Using name resolution in syslog-ng.

NOTE: If the log message does not contain a hostname in its HOST field, syslog-ng OSE automatically adds a hostname to the message.

For messages received from the network, this hostname is the address of the host that sent the message (this means the address of the last hop if the message was transferred via a relay).
For messages received from the local host, syslog-ng OSE adds the name of the host.

This option can be specified globally, and per-source as well. The local setting of the source overrides the global option if available.

NOTE: When relaying messages, enable this option on the syslog-ng OSE server and also on every relay, otherwise syslog-ng OSE will treat incoming messages as if they were sent by the last relay.

log-iw-size()

Type:	number
Default:

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.

loaders()

Type:	list of python modules
Default:	empty list

Description: The syslog-ng OSE application imports Python modules specified in this option, before importing the code of the Python class. This option has effect only when the Python class is provided in an external Python file. This option has no effect when the Python class is provided within the syslog-ng OSE configuration file (in a python{} block). You can use the loaders() option to modify the import mechanism that imports Python class. For example, that way you can use hy in your Python class.

python(class(usermodule.HyParser) loaders(hy))

options()

Type:	string
Default:	N/A

Description: This option allows you to pass custom values from the configuration file to the Python code. Enclose both the option names and their values in double-quotes. The Python code will receive these values during initialization as the options dictionary. For example, you can use this to set the IP address of the server from the configuration file, so it is not hard-coded in the Python object.

python(
    class("MyPythonClass")
    options(
        "host" "127.0.0.1"
        "port" "1883"
        "otheroption" "value")
);

For example, you can refer to the value of the host field in the Python code as options[“host”]. Note that the Python code receives the values as strings, so you might have to cast them to the type required, for example: int(options[“port”])

NOTE: From version 3.27, syslog-ng OSE supports the arrow syntax for
declaring custom Java and Python options. You can alternatively declare
them using a similar syntax:
options(  
   "host" => "localhost"  
   "port" => "1883"  
   "otheroption" => "value"  
)                    

persist-name()

Type:	string
Default:	N/A

Description: If you receive the following error message during syslog-ng OSE startup, set the persist-name() option of the duplicate drivers:

Error checking the uniqueness of the persist names, please override it with persist-name option. Shutting down.

Automatic assignment of persist names failed, as conflicting persist names were found. Please override the automatically assigned identifier using an explicit persist-name() option or remove the duplicated configuration elements.

This error happens if you use identical drivers in multiple sources, for example, if you configure two file sources to read from the same file. In this case, set the persist-name() of the drivers to a custom string, for example, persist-name(“example-persist-name1”).

NOTE: Starting with 3.26, syslog-ng OSE assigns a persist name to Python sources and destinations. The persist name is generated from the class name.
If you want to use the same Python class multiple times in your syslog-ng OSE configuration, add a unique persist-name() to each source or destination, otherwise syslog-ng OSE will not start.

For example:
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 PyNetworkSource(LogSource):
   @staticmethod
   def generate_persist_name(options):
       return options["port"]
   def run(self):
       pass
   def request_exit(self):
       pass

tags()

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 OSE 3.1 and later.

time-reopen()

Accepted values:	number [seconds]
Default:	1

Description: The time to wait in seconds before a dead connection is reestablished.

time-zone()

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.

CAUTION: This option is available only when using Python 3.

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