webhook() source options

This section describes the options of the webhook source in syslog-ng OSE.

The webhook() and webhook-json() drivers have the following options:

auth_token()

Type:	string
Default:	none

Description: You can request an authentication token from the clients as an additional method of validation. Do not use this under plain HTTP. When auth_token("<token>") is set, syslog-ng OSE only accepts requests that contain the Authorization: Basic <token>, Authorization: Bearer <token>, or a similar header. Other requests will be rejected with 403.

Example:

auth_token("dGVzdF9zZWdlskfoe0aF90b2tlbg==")

include_request_headers()

Type:	`yes`, `no`
Default:	`no`

Description: If enabled, the HTTP request headers from the webhook are available for processing as a JSON object under the ${webhook.headers} field. This option works for webhook() and for webhook-json() as well.

paths()

Type:	JSON list
Default:	`/.*`

Description: The paths() option sets the endpoints where the webhook will receive data. You can use static paths, or regular expressions. In regular expressions you can use named capture groups to automatically set the macro values.

For example, the /events/(?P<HOST>.*) path specifies the hostname for the data received in the request based on the second part of the URL: a request to the /events/my-example-host URL sets the host field of that message to my-example-host.

You can set multiple endpoints, for example, paths([“/events”,”/events/(?P<HOST>.*)”])

port()

Type:	integer
Default:	`80`(webhook), `443`(HTTPS webhook)

Description: Specifies the port-number where the webhook is listening on, for example, 8080. Make sure to enable the port you have configured on the firewall of the syslog-ng OSE host. The default value is 80 for HTTP webhooks, and 443 for HTTPS webhooks.

prefix()

Type:	string
Default:

Description: This option can be used to insert a prefix before the name part of the parsed name-value pairs to help further processing when using the webhook-json() source. For example, to insert the webhook. prefix, use the prefix(webhook.) option.

Names starting with a dot (for example, .example) are reserved for use by syslog-ng OSE. If you attempt use a macro name identical to 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, for more information, see Hard versus soft macros). To avoid such problems, use a prefix when naming the parsed values, for example, prefix(my-parsed-data.).

proxy_header()

Type:	string
Default:

Description: By default, syslog-ng OSE expects data to be sent directly, without a proxy, and sets the ${SOURCEIP} and ${SOURCEPORT} macros to the IP and port of the peer.

When proxy_header() is set the following conditions apply:

${SOURCEIP} and ${SOURCEPORT} macros will be set according to the proxy header defined in proxy_header().
The ${PEERIP} and ${PEERPORT} macros will contain the IP and port of the proxy.

Example: getting proxy data from `x-forwarded-for` request header

webhook(port(8080) proxy-header("x-forwarded-for"));

Header in the request:

curl  -H "X-Forwarded-FOR: 1.2.3.4" -X POST --data "{}" http://127.0.0.1:8080/

NOTE: Note that syslog-ng OSE only trusts the header that is specified in the proxy_header() option. If the request includes multiple headers with the specified name, the last one is used.

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.

cert-file()

Accepted values:	Filename
Default:	none

Description: Name of a file, that contains an X.509 certificate (or a certificate chain) in PEM format, suitable as a TLS certificate, matching the private key set in the key-file() option. The syslog-ng OSE application uses this certificate to authenticate the syslog-ng OSE client on the destination server. If the file contains a certificate chain, the file must begin with the certificate of the host, followed by the CA certificate that signed the certificate of the host, and any other signing CAs in order.

key-file()

Accepted values:	Filename
Default:	none

Description: The name of a file that contains an unencrypted private key in PEM format, suitable as a TLS key. If properly configured, the syslog-ng OSE application uses this private key and the matching certificate (set in the cert-file() option) to authenticate the syslog-ng OSE client on the destination server.

peer-verify()

Accepted values:	optional-trusted \| optional-untrusted \| required-trusted \| required-untrusted \| yes \| no
Default:	required-trusted

Description: Verification method of the peer, the four possible values is a combination of two properties of validation:

Whether the peer is required to provide a certificate (required or optional prefix).
Whether the certificate provided needs to be valid or not.

The following table summarizes the possible options and their results depending on the certificate of the peer.

The remote peer has:

		no certificate	invalid certificate	valid certificate
Local peer-verify() setting	optional-untrusted	TLS-encryption	TLS-encryption	TLS-encryption
	optional-trusted	TLS-encryption	rejected connection	TLS-encryption
	required-untrusted	rejected connection	TLS-encryption	TLS-encryption
	required-trusted	rejected connection	rejected connection	TLS-encryption

For untrusted certificates only the existence of the certificate is checked, but it does not have to be valid — syslog-ng OSE accepts the certificate even if it is expired, signed by an unknown CA, or its CN and the name of the machine mismatches.

CAUTION: When validating a certificate, the entire certificate chain must be valid, including the CA certificate. If any certificate of the chain is invalid, syslog-ng OSE will reject the connection.

Starting with syslog-ng OSE version 3.10, you can also use a simplified configuration method for the peer-verify option, simply setting it to yes or no. The following table summarizes the possible options and their results depending on the certificate of the peer.