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 fetcher-style sources. For details on server-style sources, see python: writing server-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 dictionary.
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-fetcher( class("<name_of_the_python_class_executed_by_the_source>") ); }; python { from syslogng import LogFetcher from syslogng import LogMessage class <name_of_the_python_class_executed_by_the_source>(LogFetcher): def init(self, options): # optional print("init") print(options) return True def deinit(self): # optional print("deinit") def open(self): # optional print("open") return True def fetch(self): # mandatory print("fetch") # return LogFetcher.FETCH_ERROR, # return LogFetcher.FETCH_NOT_CONNECTED, # return LogFetcher.FETCH_TRY_AGAIN, # return LogFetcher.FETCH_NO_DATA, return LogFetcher.FETCH_SUCCESS, msg def request_exit(self): print("request_exit") # If your fetching method is blocking, do something to break it # For example, if it reads a socket: socket.shutdown() def close(self): # optional print("close") };
Fetcher-style Python sources must be inherited from the syslogng.LogFetcher class, and must implement at least the fetch method. Multiple inheritance is allowed, but only for pure Python super classes.
For fetcher-style Python sources, syslog-ng OSE handles the event loop and the scheduling automatically. You can use simple blocking server/client libraries to receive or fetch logs.
You can retrieve messages using the fetch() 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 dictionary.
The open(self) method opens the resources required for the source, for example, it initiates a connection to the target service. It is called after init() when syslog-ng OSE is started or reloaded. If fetch() returns with an error, syslog-ng OSE calls the close() and open() methods before trying to fetch a new message.
If open() fails, it should return the False value. In this case, syslog-ng OSE retries it every time-reopen() seconds. By default, this is 1 second for Python sources and destinations, the value of time-reopen() is not inherited from the global option. For details, see Error handling in the python() destination.
Use the fetch method to fetch messages and pass them to the log paths.
For details on parsing messages, see Python LogMessage API.
The fetch method must return one of the following values:
LogFetcher.FETCH_ERROR: Fetching new messages failed, syslog-ng OSE calls the close and open methods.
LogFetcher.FETCH_NO_DATA: There was not any data available. The source waits before calling the fetch method again. The wait time is equal to time-reopen() by default, but you can override it by setting the fetch-no-data-delay() option in the source.
LogFetcher.FETCH_NOT_CONNECTED: Could not access the source, syslog-ng OSE calls the open method.
LogFetcher.FETCH_SUCCESS, msg: Post the message returned as the second argument.
LogFetcher.FETCH_TRY_AGAIN: The fetcher could not provide a message this time, but will make the source call the fetch method as soon as possible.
If you use blocking operations within the fetch() method, use request_exit() to interrupt those operations (for example, to shut down a socket), 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.
Close the connection to the target service. Usually it is called right before deinit() when stopping or reloading syslog-ng OSE. It is also called when fecth() fails.
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.
Using the snmptrap() source, you can read and parse the SNMP traps of the Net-SNMP's snmptrapd application. syslog-ng OSE can read these traps from a log file, and extract their content into name-value pairs, making it easy to forward them as a structured log message (for example, in JSON format). The syslog-ng OSE application automatically adds the .snmp. prefix to the name of the fields the extracted from the message.
The snmptrap() source is available in syslog-ng OSE version
The snmptrap() source has only the options listed in snmptrap() source options. Other options commonly available in other source drivers are not supported.
In addition to traps, the log of snmptrapd may contain other messages (for example, daemon start/stop information, debug logs) as well. Currently syslog-ng OSE discards these messages.
The syslog-ng OSE application cannot resolve OIDs, you have to configure snmptrapd to do so. Note that because of a bug, if snmptrapd does not escape String values in the VarBindList if it can resolve an OID to a symbolic name. As a result, syslog-ng OSE cannot process traps that contain the = in the value of the string. To overcome this problem, disable resolving OIDs in snmptrapd. For details, see the documentation of snmptrapd.
The colon (:) character is commonly used in SNMP traps. However, this character cannot be used in the name of syslog-ng OSE macros (name-value pairs). Therefore, the syslog-ng OSE application automatically replaces all consecutive : characters with a single underscore (_) character. For example, you can reference the value of the NET-SNMP-EXAMPLES-MIB::netSnmpExampleString key using the ${NET-SNMP-EXAMPLES-MIB_netSnmpExampleString} macro.
Note that this affects only name-value pairs (macros). The generated message always contains the original name of the key.
Configure snmptrapd to log into a file.
If you use SMIv1 traps, include the following format string in the configuration file of snmptrapd:
format1 %.4y-%.2m-%.2l %.2h:%.2j:%.2k %B [%b]: %N\n\t%W Trap (%q) Uptime: %#T\n%v\n
If you use SMIv2 traps, use the default format. The snmptrap() source of syslog-ng OSE expects this default format:
format2 %.4y-%.2m-%.2l %.2h:%.2j:%.2k %B [%b]:\n%v\n
Beacause of an snmptrapd bug, if you specify the filename in the configuration file with logOption, you must also specify another output as a command line argument (-Lf, -Ls). Otherwise, snmptrapd will not apply the the trap format.
To use the snmptrap() driver, the scl.conf file must be included in your syslog-ng OSE configuration:
@include "scl.conf"
A sample snmptrapd configuration:
authCommunity log,execute,net public format1 %.4y-%.2m-%.2l %.2h:%.2j:%.2k %B [%b]: %N\n\t%W Trap (%q) Uptime: %#T\n%v\n outputOption s
Starting snmptrapd: snmptrapd -A -Lf /var/log/snmptrapd.log
Sending a sample V2 trap message: snmptrap -v2c -c public 127.0.0.1 666 NET-SNMP-EXAMPLES-MIB::netSnmpExampleHeartbeatNotification netSnmpExampleHeartbeatRate i 60 netSnmpExampleString s "string". From this trap, syslog-ng OSE receives the following input:
2017-05-23 15:29:40 localhost [UDP: [127.0.0.1]:59993->[127.0.0.1]:162]: SNMPv2-SMI::mib-2.1.3.0 = Timeticks: (666) 0:00:06.66 SNMPv2-SMI::snmpModules.1.1.4.1.0 = OID: NET-SNMP-EXAMPLES-MIB::netSnmpExampleHeartbeatNotification NET-SNMP-EXAMPLES-MIB::netSnmpExampleHeartbeatRate = INTEGER: 60 NET-SNMP-EXAMPLES-MIB::netSnmpExampleString = STRING: string
The following syslog-ng OSE configuration sample uses the default settings of the driver, reading SNMP traps from the /var/log/snmptrapd.log file, and writes the log messages generated from the traps into a file.
@include "scl.conf" log { source { snmptrap(filename("/var/log/snmptrapd.log")); }; destination { file("/var/log/example.log"); }; };
From the trap, syslog-ng OSE writes the following into the log file:
May 23 15:29:40 myhostname snmptrapd: hostname='localhost', transport_info='UDP: [127.0.0.1]:59993->[127.0.0.1]:162', SNMPv2-SMI::mib-2.1.3.0='(666) 0:00:06.66', SNMPv2-SMI::snmpModules.1.1.4.1.0='NET-SNMP-EXAMPLES-MIB::netSnmpExampleHeartbeatNotification', NET-SNMP-EXAMPLES-MIB::netSnmpExampleHeartbeatRate='60', NET-SNMP-EXAMPLES-MIB::netSnmpExampleString='string'
Using the same input trap, the following configuration example formats the SNMP traps as JSON messages.
@include "scl.conf" log { source { snmptrap( filename("/var/log/snmptrapd.log") set-message-macro(no) ); }; destination { file("/var/log/example.log" template("$(format-json --scope dot-nv-pairs)\n")); }; };
The previous trap formatted as JSON:
{ "_snmp":{ "transport_info":"UDP: [127.0.0.1]:59993->[127.0.0.1]:162", "hostname":"localhost", "SNMPv2-SMI_snmpModules":{ "1":{ "1":{ "4":{ "1":{ "0":"NET-SNMP-EXAMPLES-MIB::netSnmpExampleHeartbeatNotification" } } } } }, "SNMPv2-SMI_mib-2":{ "1":{ "3":{ "0":"(666) 0:00:06.66" } } }, "NET-SNMP-EXAMPLES-MIB_netSnmpExampleString":"string", "NET-SNMP-EXAMPLES-MIB_netSnmpExampleHeartbeatRate":"60" } }
The snmptrap() driver has the following options. Only the filename() option is required, the others are optional.
Type: | path |
Default: |
Description: The log file of snmptrapd. The syslog-ng OSE application reads the traps from this file.
In addition to traps, the log of snmptrapd may contain other messages (for example, daemon start/stop information, debug logs) as well. Currently syslog-ng OSE discards these messages.
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: | string |
Default: |
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.
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").
Synopsis: | prefix() |
Description: Insert a prefix before the name part of the parsed name-value pairs to help further processing. For example:
To insert the my-parsed-data. prefix, use the prefix(my-parsed-data.) option.
To refer to a particular data that has a prefix, use the prefix in the name of the macro, for example, ${my-parsed-data.name}.
If you forward the parsed messages using the IETF-syslog protocol, you can insert all the parsed data into the SDATA part of the message using the prefix(.SDATA.my-parsed-data.) option.
Names starting with a dot (for example, .example) are reserved for use by syslog-ng OSE. If you use such a macro name as the name of a parsed value, it will attempt to replace the original value of the macro (note that only soft macros can be overwritten, see Hard versus soft macros for details). To avoid such problems, use a prefix when naming the parsed values, for example, prefix(my-parsed-data.)
Default value: .snmp. option.
Type: | yes|no |
Default: | yes |
Description: The snmptrap() source automatically parses the traps into name-value pairs, so you can handle the content of the trap as a structured message. Consequently, you might not even need the ${MESSAGE} part of the log message. If set-message-macro() is set to no, syslog-ng OSE leaves the ${MESSAGE} part empty. If set-message-macro() is set to yes, syslog-ng OSE generates a regular log message from the trap.
Solaris uses its STREAMS framework to send messages to the syslogd process. Solaris 2.5.1 and above uses an IPC called door in addition to STREAMS, to confirm the delivery of a message. The syslog-ng application supports the IPC mechanism via the door() option (see below).
The sun-streams() driver must be enabled when the syslog-ng application is compiled (see ./configure --help).
The sun-streams() driver has a single required argument specifying the STREAMS device to open, and the door() option. For the list of available optional parameters, see sun-streams() source options.
Starting with version
sun-streams(<name_of_the_streams_device> door(<filename_of_the_door>));
© 2024 One Identity LLC. ALL RIGHTS RESERVED. Feedback Términos de uso Privacidad Cookie Preference Center