syslog-ng Open Source Edition 3.22 - Administration Guide

Preface Introduction to syslog-ng The concepts of syslog-ng Installing syslog-ng The syslog-ng OSE quick-start guide The syslog-ng OSE configuration file source: Read, receive, and collect log messages
How sources work default-network-drivers: Receive and parse common syslog messages internal: Collecting internal messages file: Collecting messages from text files wildcard-file: Collecting messages from multiple text files linux-audit: Collecting messages from Linux audit logs network: Collecting messages using the RFC3164 protocol (network() driver) nodejs: Receiving JSON messages from nodejs applications mbox: Converting local e-mail messages to log messages osquery: Collect and parse osquery result logs pipe: Collecting messages from named pipes pacct: Collecting process accounting logs on Linux program: Receiving messages from external applications python: writing server-style Python sources python-fetcher: writing fetcher-style Python sources snmptrap: Read Net-SNMP traps sun-streams: Collecting messages on Sun Solaris syslog: Collecting messages using the IETF syslog protocol (syslog() driver) system: Collecting the system-specific log messages of a platform systemd-journal: Collecting messages from the systemd-journal system log storage systemd-syslog: Collecting systemd messages using a socket tcp, tcp6, udp, udp6: Collecting messages from remote hosts using the BSD syslog protocol— OBSOLETE unix-stream, unix-dgram: Collecting messages from UNIX domain sockets stdin: Collecting messages from the standard input stream
destination: Forward, send, and store log messages
amqp: Publishing messages using AMQP collectd: sending metrics to collectd elasticsearch2: Sending messages directly to Elasticsearch version 2.0 or higher (DEPRECATED) elasticsearch-http: Sending messages to Elasticsearch HTTP Bulk API file: Storing messages in plain-text files graphite: Sending metrics to Graphite Sending logs to Graylog hdfs: Storing messages on the Hadoop Distributed File System (HDFS) Posting messages over HTTP http: Posting messages over HTTP without Java kafka: Publishing messages to Apache Kafka (Java implementation) kafka: Publishing messages to Apache Kafka (C implementation, using the librdkafka client) loggly: Using Loggly logmatic: Using Logmatic.io mongodb: Storing messages in a MongoDB database network: Sending messages to a remote log server using the RFC3164 protocol (network() driver) osquery: Sending log messages to osquery's syslog table pipe: Sending messages to named pipes program: Sending messages to external applications pseudofile() python: writing custom Python destinations redis: Storing name-value pairs in Redis riemann: Monitoring your data with Riemann slack: Sending alerts and notifications to a Slack channel smtp: Generating SMTP messages (e-mail) from logs snmp: Sending SNMP traps Splunk: Sending log messages to Splunk sql: Storing messages in an SQL database stomp: Publishing messages using STOMP syslog: Sending messages to a remote logserver using the IETF-syslog protocol syslog-ng: Forwarding messages and tags to another syslog-ng node tcp, tcp6, udp, udp6: Sending messages to a remote log server using the legacy BSD-syslog protocol (tcp(), udp() drivers) Telegram: Sending messages to Telegram unix-stream, unix-dgram: Sending messages to UNIX domain sockets usertty: Sending messages to a user terminal: usertty() destination Write your own custom destination in Java or Python Client-side failover
log: Filter and route log messages using log paths, flags, and filters Global options of syslog-ng OSE TLS-encrypted message transfer template and rewrite: Format, modify, and manipulate log messages parser: Parse and segment structured messages db-parser: Process message content with a pattern database (patterndb) Correlating log messages Enriching log messages with external data Statistics of syslog-ng Multithreading and scaling in syslog-ng OSE Troubleshooting syslog-ng Best practices and examples The syslog-ng manual pages Creative Commons Attribution Non-commercial No Derivatives (by-nc-nd) License

snmp() destination options

This driver sends SNMP traps using the SNMP v2c or v3 protocol.

The snmp() destination has the following options:

auth-algorithm()
Type: SHA|sha
Default: SHA

Description: The authentication method to use. Lowercase values (for example, sha) can be used as well.

This option is used with the SNMPv3 protocol.

auth-password()
Type: string
Default: empty string

Description: The password used for authentication. If the auth-username() option is set but the auth-password() is empty, syslog-ng OSE will try to authenticate with an empty password.

This option is used with the SNMPv3 protocol.

auth-username()
Type: string
Default: empty string

Description: The username used to authenticate on the SNMP server. If this parameter is set, syslog-ng OSE will try to authenticate on the SNMP server.

This option is used with the SNMPv3 protocol.

community()
Type: string
Default: public

Description: The community string used for SNMPv2c authentication.

This option is used with the SNMPv2c protocol.

enc-algorithm()
Type: AES|aes
Default: AES

Description: The encryption method used to encrypt the SNMP traffic. Lowercase values (for example, aes) can be used as well.

This option is used with the SNMPv3 protocol.

enc-password()
Type: string
Default:

Description: The password used for the encryption. Encryption is used only if the enc-password() is not empty.

This option is used with the SNMPv3 protocol.

engine-id()
Type: number (hexadecimal number)
Default:

Description: The engine ID is a hexadecimal number at least 10 digits long, starting with 0x. For example 0xABABABABAB.

This option is a required parameter when using the SNMPv3 protocol.

host()
Type: hostname or IP address
Default: n/a

Description: Hostname of the SNMP server.

log-fifo-size()
Type: number
Default: Use global setting.

Description: The number of messages that the output queue can store.

port()
Type: number (port number)
Default: 162

Description: The port number to connect to.

snmp-obj()
Type: <oid_of_the_object>, <type_of_the_object>, <value_of_the_object>
Default: n/a

Description: The snmp-obj() option can be used to create custom SNMP trap elements. To create a trap element, specify the OID, type, and value of the element in the snmp-obj() option. To send SNMP traps, at least one snmp-obj() option must be defined. The snmp-obj() option requires the following parameters. Note that syslog-ng OSE does not validate the values of these elements.

  • <oid_of_the_object>: The object id of the SNMP object, for example, .1.3.6.1.4.1.18372.3.1.1.1.1.1.

  • <type_of_the_object>: The type of the object specified as an ASN.1 primitive. One of: Integer, Timeticks, Octetstring, Counter32, Ipaddress, Objectid. The type names are not case sensitive.

  • <value_of_the_object>: The value of the object as a string. The macros of syslog-ng OSE can be used to set these values, making it possible to transfer the content and other metadata from the the syslog message to the SNMP trap. Note that if the value of an Integer, Counter32 or Timeticks object is not a number (for example, is an empty string or other not-number string), syslog-ng OSE will automatically replace the value with 0. The values of other types of objects are not validated.

Example: Defining SNMP objects

The following are SNMP object definitions:

snmp-obj('.1.3.6.1.4.1.18372.3.1.1.1.1.3', 'Ipaddress', '192.168.1.1')
snmp-obj('.1.3.6.1.4.1.18372.3.1.1.1.1.2', 'Octetstring', '${MESSAGE}')
time-zone()
Type: name of the timezone, or the timezone offset
Default: unspecified

Description: Convert timestamps to the timezone specified by this option. If this option is not set, then the original timezone information in the message is used. Converting the timezone changes the values of all date-related macros derived from the timestamp, for example, HOUR. For the complete list of such macros, see Date-related macros.

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.

trap-obj()
Type: <oid_of_the_object>, "Objectid", <value_of_the_object>
Default: n/a

Description: The trap-obj() is a specialized version of the snmp-obj() option that is used to identify the SNMP trap object. The type of the trap object is always Objectid. The <oid_of_the_object> and the <value_of_the_object> parameters are identical to the respective parameters of the snmp-obj() option. For details on these parameters, see snmp-obj().

NOTE:

Using the trap-obj() object is equivalent to using the snmp-obj() with the Objectid type.

version()
Type: v2c|v3
Default: v2c

Description: Specifies which version of the SNMP protocol to use.

NOTE:

The syslog-ng OSE application will accept any valid option for the snmp() destination, but will only use the ones relevant to the selected protocol version, any other option will be ignored. For example, if the version("v2c") engine-id("0xABABABABAB") community("mycommunity") options are set, syslog-ng OSE will accept every option, but process only the community() option, because engine-id() applies only to SNMPv3.


Was this topic helpful?

[Select Rating]



Splunk: Sending log messages to Splunk

Although syslog-ng OSE currently does not have any built-in integration with Splunk, the existing message-formatting features and flexibility of syslog-ng OSE allows you to forward your log messages to Splunk. In syslog-ng OSE version 3.8 or later, you can use the http() destination. In earlier versions, you can use the program() destination.

For details on forwarding log messages to Splunk with syslog-ng OSE see the following posts on the Splunk blog:

Note that the syslog-ng Premium Edition application has a dedicated Splunk destination. For details, see splunk-hec: Sending messages to Splunk HTTP Event Collector.


Was this topic helpful?

[Select Rating]



sql: Storing messages in an SQL database

The sql() driver sends messages into an SQL database. Currently the Microsoft SQL (MSSQL), MySQL, Oracle, PostgreSQL, and SQLite databases are supported.

Declaration:
sql(database_type host_parameters database_parameters [options]);

The sql() driver has the following required parameters: type(), database(), table(), columns(), and values().

Caution:

The syslog-ng application requires read and write access to the SQL table, otherwise it cannot verify that the destination table exists.

Currently the syslog-ng application has default schemas for the different databases and uses these defaults if the database schema (for example columns and column types) is not defined in the configuration file. However, these schemas will be deprecated and specifying the exact database schema will be required in later versions of syslog-ng.

NOTE:

In addition to the standard syslog-ng packages, the sql() destination requires database-specific packages to be installed. These packages are automatically installed by the binary syslog-ng installer.

The table and value parameters can include macros to create tables and columns dynamically (for details, see Macros of syslog-ng OSE).

Caution:

When using macros in table names, note that some databases limit the maximum allowed length of table names. Consult the documentation of the database for details.

Inserting the records into the database is performed by a separate thread. The syslog-ng application automatically performs the escaping required to insert the messages into the database.

Example: Using the sql() driver

The following example sends the log messages into a PostgreSQL database running on the logserver host. The messages are inserted into the logs database, the name of the table includes the exact date and the name of the host sending the messages. The syslog-ng application automatically creates the required tables and columns, if the user account used to connect to the database has the required privileges.

destination d_sql {
    sql(type(pgsql)
    host("logserver") username("syslog-ng") password("password")
    database("logs")
    table("messages_${HOST}_${R_YEAR}${R_MONTH}${R_DAY}")
    columns("datetime", "host", "program", "pid", "message")
    values("{$R_DATE}", "${HOST}", "${PROGRAM}", "${PID}", "${MSGONLY}")
    indexes("datetime", "host", "program", "pid", "message"));
};

The following example specifies the type of the database columns as well:

destination d_sql {
    sql(type(pgsql)
    host("logserver") username("syslog-ng") password("password")
    database("logs")
    table("messages_${HOST}_${R_YEAR}${R_MONTH}${R_DAY}")
    columns("datetime varchar(16)", "host varchar(32)", "program  varchar(20)", "pid varchar(8)", "message  varchar(200)")
    values("${R_DATE}", "${HOST}", "${PROGRAM}", "${PID}", "${MSGONLY}")
    indexes("datetime", "host", "program", "pid", "message"));
};

Was this topic helpful?

[Select Rating]



Using the sql() driver with an Oracle database

The Oracle sql destination has some special aspects that are important to note.

  • The hostname of the database server is set in the tnsnames.ora file, not in the host parameter of the sql() destination.

    If the tnsnames.ora file is not located in the /etc directory (or in the /var/opt/oracle directory on Solaris), set the following Oracle-related environment variables, so syslog-ng OSE will find the file: ORACLE_BASE, ORACLE_HOME, and ORACLE_SID. For details, see the documentation of the Oracle Instant Client.

  • You cannot use the same database() settings in more than one destination, because the database() option of the SQL driver is just a reference to the connection string of the tnsnames.ora file. To overcome this problem, you can duplicate the connections in the tnsnames.ora file under a different name, and use a different table in each Oracle destination in syslog-ng OSE.

  • As certain database versions limit the maximum length of table names, macros in the table names should be used with care.

  • In the current version of syslog-ng OSE, the types of database columns must be explicitly set for the Oracle destination. The column used to store the text part of the syslog messages should be able to store messages as long as the longest message permitted by syslog-ng, therefore it is usually recommended to use the varchar2 or clob column type. (The maximum length of the messages can be set using the log-msg-size() option.) For details, see the following example.

  • The Oracle Instant Client used by syslog-ng OSE supports only the following character sets:

    • Single-byte character sets: US7ASCII, WE8DEC, WE8MSWIN1252, and WE8ISO8859P1

    • Unicode character sets: UTF8, AL16UTF16, and AL32UTF8

Example: Using the sql() driver with an Oracle database

The following example sends the log messages into an Oracle database running on the logserver host, which must be set in the /etc/tnsnames.ora file. The messages are inserted into the LOGS database, the name of the table includes the exact date when the messages were sent. The syslog-ng application automatically creates the required tables and columns, if the user account used to connect to the database has the required privileges.

destination d_sql {
  sql(type(oracle)
  username("syslog-ng") password("password")
  database("LOGS")
  table("msgs_${R_YEAR}${R_MONTH}${R_DAY}")
  columns("datetime varchar(16)", "host varchar(32)", "program varchar(32)", "pid varchar(8)", "message varchar2")
  values("${R_DATE}", "${HOST}", "${PROGRAM}", "${PID}", "${MSGONLY}")
  indexes("datetime", "host", "program", "pid", "message"));
};

The Oracle Instant Client retrieves the address of the database server from the /etc/tnsnames.ora file. Edit or create this file as needed for your configuration. A sample is provided below.

LOGS =
(DESCRIPTION =
(ADDRESS_LIST =
(ADDRESS = (PROTOCOL = TCP)
(HOST = logserver)
(PORT = 1521))
)
(CONNECT_DATA =
(SERVICE_NAME = EXAMPLE.SERVICE)
)
)

Was this topic helpful?

[Select Rating]



Related Documents