For other versions, see the Versioned plugin docs.
For questions about the plugin, open a topic in the Discuss forums. For bugs or feature requests, open an issue in Github. For the list of Elastic supported plugins, please consult the Elastic Support Matrix.
The HTTP filter provides integration with external web services/REST APIs.
The plugin includes sensible defaults that change based on ECS compatibility mode. When targeting an ECS version, headers are set as @metadata and the target_body is a required option. See target_body , and target_headers .
This plugin supports the following configuration options plus the Common Options described later.
String, Array or Hash
There are also multiple configuration options related to the HTTP connectivity:
a valid filesystem path
a valid filesystem path
a valid filesystem path
a valid filesystem path
a valid filesystem path
Also see Common Options for a list of options supported by all filter plugins.
The body of the HTTP request to be sent.
An example to send body as json
http < body => < "key1" =>"constant_value" "key2" => "%" > body_format => "json" >
If set to "json" and the body is a type of array or hash, the body will be serialized as JSON. Otherwise it is sent as is.
Controls this plugin’s compatibility with the Elastic Common Schema (ECS). The value of this setting affects the default value of target_body and target_headers .
The HTTP headers to be sent in the request. Both the names of the headers and their values can reference values from event fields.
Define the query string parameters (key-value pairs) to be sent in the HTTP request.
Define the target field for placing the body of the HTTP response.
Define the target field for placing the headers of the HTTP response.
The URL to send the request to. The value can be fetched from event fields.
The verb to be used for the HTTP request.
How many times should the client retry a failing URL. We highly recommend NOT setting this value to zero if keepalive is enabled. Some servers incorrectly end keepalives early requiring a retry! Note: if retry_non_idempotent is set only GET, HEAD, PUT, DELETE, OPTIONS, and TRACE requests will be retried.
If you need to use a custom X.509 CA (.pem certs) specify the path to that here
If you’d like to use a client certificate (note, most people don’t want this) set the path to the x509 cert here
If you’re using a client certificate specify the path to the encryption key here
Timeout (in seconds) to wait for a connection to be established. Default is 10s
Enable cookie support. With this enabled the client will persist cookies across requests as a normal web browser would. Enabled by default
Should redirects be followed? Defaults to true
Turn this on to enable HTTP keepalive support. We highly recommend setting automatic_retries to at least one with this to fix interactions with broken keepalive implementations.
If you need to use a custom keystore ( .jks ) specify that here. This does not work with .pem keys!
Specify the keystore password here. Note, most .jks files created with keytool require a password!
Specify the keystore type here. One of JKS or PKCS12 . Default is JKS
Password to be used in conjunction with the username for HTTP authentication.
Max number of concurrent connections. Defaults to 50
Max number of concurrent connections to a single host. Defaults to 25
If you’d like to use an HTTP proxy . This supports multiple configuration syntaxes:
Timeout (in seconds) for the entire request.
If automatic_retries is enabled this will cause non-idempotent HTTP verbs (such as POST) to be retried.
Timeout (in seconds) to wait for data on the socket. Default is 10s
SSL certificate to use to authenticate the client. This certificate should be an OpenSSL-style X.509 certificate file.
This setting can be used only if ssl_key is set.
The .cer or .pem CA files to validate the server’s certificate.
The list of cipher suites to use, listed by priorities. Supported cipher suites vary depending on the Java and protocol versions.
Enable SSL/TLS secured communication. It must be true for other ssl_ options to take effect.
OpenSSL-style RSA private key that corresponds to the ssl_certificate .
This setting can be used only if ssl_certificate is set.
Set the keystore password
The keystore used to present a certificate to the server. It can be either .jks or .p12
The format of the keystore file. It must be either jks or pkcs12 .
List of allowed SSL/TLS versions to use when establishing a connection to the HTTP endpoint.
For Java 8 'TLSv1.3' is supported only since 8u262 (AdoptOpenJDK), but requires that you set the LS_JAVA_OPTS="-Djdk.tls.client.protocols=TLSv1.3" system property in Logstash.
If you configure the plugin to use 'TLSv1.1' on any recent JVM, such as the one packaged with Logstash, the protocol is disabled by default and needs to be enabled manually by changing jdk.tls.disabledAlgorithms in the $JDK_HOME/conf/security/java.security configuration file. That is, TLSv1.1 needs to be removed from the list.
Set the truststore password
The truststore to validate the server’s certificate. It can be either .jks or .p12 .
The format of the truststore file. It must be either jks or pkcs12 .
Controls the verification of server certificates. The full option verifies that the provided certificate is signed by a trusted authority (CA) and also that the server’s hostname (or IP address) matches the names identified within the certificate.
The none setting performs no verification of the server’s certificate. This mode disables many of the security benefits of SSL/TLS and should only be used after cautious consideration. It is primarily intended as a temporary diagnostic mechanism when attempting to resolve TLS errors. Using none in production environments is strongly discouraged.
If you need to use a custom truststore ( .jks ) specify that here. This does not work with .pem certs!
Specify the truststore password here. Note, most .jks files created with keytool require a password!
Specify the truststore type here. One of JKS or PKCS12 . Default is JKS
Username to use with HTTP authentication for ALL requests. Note that you can also set this per-URL. If you set this you must also set the password option.
How long to wait before checking for a stale connection to determine if a keepalive request is needed. Consider setting this value lower than the default, possibly to 0, if you get connection errors regularly.
This client is based on Apache Commons. Here’s how the Apache Commons documentation describes this option: "Defines period of inactivity in milliseconds after which persistent connections must be re-validated prior to being leased to the consumer. Non-positive value passed to this method disables connection validation. This check helps detect connections that have become stale (half-closed) while kept inactive in the pool."