This section describes the options of the Java-based http() destination in syslog-ng OSE.

The http destination of syslog-ng OSE can directly post log messages to web services using the HTTP protocol. The http destination has the following options. Some of these options are directly used by the Java code underlying the http destination, therefore these options must be specified in the following format:

option("<option-name>", "<option-value>")

For example, option(“url”, “http://<server-address>:<port-number>"). The exact format to use is indicated in the description of the option.

Required options

The following options are required: url().

ca-dir()

Type: Directory name
Default: none

Description: The name of a directory that contains a set of trusted CA certificates in PEM format. The CA certificate files have to be named after the 32-bit hash of the subject's name. This naming can be created using the c_rehash utility in openssl. For an example, see Configuring TLS on the syslog-ng OSE clients. The syslog-ng OSE application uses the CA certificates in this directory to validate the certificate of the peer.

This option can be used together with the optional ca-file() option.

NOTE: During a TLS handshake, syslog-ng OSE automatically sets the certificate_authorities field of the certificate request based on the ca-file() and ca-dir() options.

ca-file()

Type: File name
Default: empty

Description: Optional. The name of a file that contains a set of trusted CA certificates in PEM format. The syslog-ng OSE application uses the CA certificates in this file to validate the certificate of the peer.

Example format in configuration:

ca-file("/etc/pki/tls/certs/ca-bundle.crt")

NOTE: The ca-file() option can be used together with the ca-dir() option, and it is relevant when peer-verify() is set to other than no or optional-untrusted.

NOTE: During a TLS handshake, syslog-ng OSE automatically sets the certificate_authorities field of the certificate request based on the ca-file() and ca-dir() options.

class-name()

Type: string
Default: N/A

Description: The name of the class (including the name of the package) that includes the destination driver to use.

For the http destination, use this option as class-name("org.syslog_ng.http.HTTPDestination").

client-lib-dir()

Type: string
Default: The syslog-ng OSE module directory: /opt/syslog-ng/lib/syslog-ng/java-modules/

Description: The list of the paths where the required Java classes are located. For example, class-path("/opt/syslog-ng/lib/syslog-ng/java-modules/:/opt/my-java-libraries/libs/"). If you set this option multiple times in your syslog-ng OSE configuration (for example, because you have multiple Java-based destinations), syslog-ng OSE will merge every available paths to a single list.

hook-commands()

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.

Using the hook-commands() when syslog-ng OSE starts or stops

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.

Using the hook-commands() when syslog-ng OSE reloads

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.

Example: Using the hook-commands() with a network source

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")
        )
      );
};

jvm-options()

Type: list
Default: N/A

Description: Specify the Java Virtual Machine (JVM) settings of your Java destination from the syslog-ng OSE configuration file.

For example:

jvm-options("-Xss1M -XX:+TraceClassLoading")

log-fifo-size()

Type: number
Default: Use global setting.

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

method()

Type: DELETE | HEAD | GET | OPTIONS | POST | PUT | TRACE
Default: PUT

Description: Specifies the HTTP method to use when sending the message to the server. Available in syslog-ng OSE version 3.7.2 and newer.

retries()

Type: number (of attempts)
Default: 3

Description: If syslog-ng OSE cannot send a message, it will try again until the number of attempts reaches retries().

If the number of attempts reaches retries(), syslog-ng OSE will wait for time-reopen() time, then tries sending the message again.

template()

Type: string
Default: A format conforming to the default logfile format.

Description: Specifies a template defining the logformat to be used in the destination. Macros are described in Macros of syslog-ng OSE. Please note that for network destinations it might not be appropriate to change the template as it changes the on-wire format of the syslog protocol which might not be tolerated by stock syslog receivers (like syslogd or syslog-ng OSE itself). For network destinations make sure the receiver can cope with the custom format defined.

throttle()

Type: number
Default: 0

Description: Sets the maximum number of messages sent to the destination per second. Use this output-rate-limiting functionality only when using disk-buffer as well to avoid the risk of losing messages. Specifying 0 or a lower value sets the output limit to unlimited.

timeout()

Type: number [seconds]
Default: 0

Description: The value (in seconds) to wait for an operation to complete, and attempt to reconnect the server if exceeded. By default, the timeout value is 0, meaning that there is no timeout. Available in version 3.11 and later.

url()

Type: URL
Default:  

Description: Specifies the hostname or IP address and optionally the port number of the web service that can receive log data via HTTP. Use a colon (:) after the address to specify the port number of the server. You can also use macros, templates, and template functions in the URL, for example: http://host.example.com:8080/${MACRO1}/${MACRO2}/script")

Updated: