:plugin: beats
:type: input
:default_codec: plain

///////////////////////////////////////////
START - GENERATED VARIABLES, DO NOT EDIT!
///////////////////////////////////////////
:version: %VERSION%
:release_date: %RELEASE_DATE%
:changelog_url: %CHANGELOG_URL%
:include_path: ../../../../logstash/docs/include
///////////////////////////////////////////
END - GENERATED VARIABLES, DO NOT EDIT!
///////////////////////////////////////////

[id="plugins-{type}s-{plugin}"]

=== Beats input plugin

include::{include_path}/plugin_header.asciidoc[]

==== Description

This input plugin enables Logstash to receive events from the
https://www.elastic.co/products/beats[Elastic Beats] framework.

The following example shows how to configure Logstash to listen on port
5044 for incoming Beats connections and to index into Elasticsearch:

[source,ruby]
------------------------------------------------------------------------------
input {
  beats {
    port => 5044
  }
}

output {
  elasticsearch {
    hosts => "localhost:9200"
    manage_template => false
    index => "%{[@metadata][beat]}-%{[@metadata][version]}-%{+YYYY.MM.dd}"
    document_type => "%{[@metadata][type]}" <1>
  }
}
------------------------------------------------------------------------------
<1> Starting with Logstash 6.0, the `document_type` option is
deprecated due to the
https://www.elastic.co/guide/en/elasticsearch/reference/6.0/removal-of-types.html[removal of types in Logstash 6.0].
It will be removed in the next major version of Logstash. If you are running
Logstash 6.0 or later, you do not need to set `document_type` in your
configuration because Logstash sets the type to `doc` by default.

IMPORTANT: If you are shipping events that span multiple lines, you need to
use the https://www.elastic.co/guide/en/beats/filebeat/current/multiline-examples.html[configuration options available in Filebeat] to handle multiline events
before sending the event data to Logstash. You cannot use the
{logstash-ref}/plugins-codecs-multiline.html[Multiline codec plugin] to handle multiline events. Doing so will
result in the failure to start Logstash.


[id="plugins-{type}s-{plugin}-options"]
==== Beats Input Configuration Options

This plugin supports the following configuration options plus the <<plugins-{type}s-{plugin}-common-options>> described later.

[cols="<,<,<",options="header",]
|=======================================================================
|Setting |Input type|Required
| <<plugins-{type}s-{plugin}-cipher_suites>> |<<array,array>>|No
| <<plugins-{type}s-{plugin}-client_inactivity_timeout>> |<<number,number>>|No
| <<plugins-{type}s-{plugin}-host>> |<<string,string>>|No
| <<plugins-{type}s-{plugin}-include_codec_tag>> |<<boolean,boolean>>|No
| <<plugins-{type}s-{plugin}-port>> |<<number,number>>|Yes
| <<plugins-{type}s-{plugin}-ssl>> |<<boolean,boolean>>|No
| <<plugins-{type}s-{plugin}-ssl_certificate>> |a valid filesystem path|No
| <<plugins-{type}s-{plugin}-ssl_certificate_authorities>> |<<array,array>>|No
| <<plugins-{type}s-{plugin}-ssl_handshake_timeout>> |<<number,number>>|No
| <<plugins-{type}s-{plugin}-ssl_key>> |a valid filesystem path|No
| <<plugins-{type}s-{plugin}-ssl_key_passphrase>> |<<password,password>>|No
| <<plugins-{type}s-{plugin}-ssl_verify_mode>> |<<string,string>>, one of `["none", "peer", "force_peer"]`|No
| <<plugins-{type}s-{plugin}-tls_max_version>> |<<number,number>>|No
| <<plugins-{type}s-{plugin}-tls_min_version>> |<<number,number>>|No
|=======================================================================

Also see <<plugins-{type}s-{plugin}-common-options>> for a list of options supported by all
input plugins.

&nbsp;

[id="plugins-{type}s-{plugin}-cipher_suites"]
===== `cipher_suites` 

  * Value type is <<array,array>>
  * Default value is `java.lang.String[TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384, TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384, TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256, TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256, TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384, TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384, TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256, TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256]@459cfcca`

The list of ciphers suite to use, listed by priorities.

[id="plugins-{type}s-{plugin}-client_inactivity_timeout"]
===== `client_inactivity_timeout` 

  * Value type is <<number,number>>
  * Default value is `60`

Close Idle clients after X seconds of inactivity.

[id="plugins-{type}s-{plugin}-host"]
===== `host` 

  * Value type is <<string,string>>
  * Default value is `"0.0.0.0"`

The IP address to listen on.

[id="plugins-{type}s-{plugin}-include_codec_tag"]
===== `include_codec_tag` 

  * Value type is <<boolean,boolean>>
  * Default value is `true`



[id="plugins-{type}s-{plugin}-port"]
===== `port` 

  * This is a required setting.
  * Value type is <<number,number>>
  * There is no default value for this setting.

The port to listen on.

[id="plugins-{type}s-{plugin}-ssl"]
===== `ssl` 

  * Value type is <<boolean,boolean>>
  * Default value is `false`

Events are by default sent in plain text. You can
enable encryption by setting `ssl` to true and configuring
the `ssl_certificate` and `ssl_key` options.

[id="plugins-{type}s-{plugin}-ssl_certificate"]
===== `ssl_certificate` 

  * Value type is <<path,path>>
  * There is no default value for this setting.

SSL certificate to use.

[id="plugins-{type}s-{plugin}-ssl_certificate_authorities"]
===== `ssl_certificate_authorities` 

  * Value type is <<array,array>>
  * Default value is `[]`

Validate client certificates against these authorities. 
You can define multiple files or paths. All the certificates will
be read and added to the trust store. You need to configure the `ssl_verify_mode`
to `peer` or `force_peer` to enable the verification.


[id="plugins-{type}s-{plugin}-ssl_handshake_timeout"]
===== `ssl_handshake_timeout` 

  * Value type is <<number,number>>
  * Default value is `10000`

Time in milliseconds for an incomplete ssl handshake to timeout

[id="plugins-{type}s-{plugin}-ssl_key"]
===== `ssl_key` 

  * Value type is <<path,path>>
  * There is no default value for this setting.

SSL key to use.
NOTE: This key need to be in the PKCS8 format, you can convert it with https://www.openssl.org/docs/man1.1.0/apps/pkcs8.html[OpenSSL]
for more information.

[id="plugins-{type}s-{plugin}-ssl_key_passphrase"]
===== `ssl_key_passphrase` 

  * Value type is <<password,password>>
  * There is no default value for this setting.

SSL key passphrase to use.

[id="plugins-{type}s-{plugin}-ssl_verify_mode"]
===== `ssl_verify_mode` 

  * Value can be any of: `none`, `peer`, `force_peer`
  * Default value is `"none"`

By default the server doesn't do any client verification.

`peer` will make the server ask the client to provide a certificate. 
If the client provides a certificate, it will be validated.

`force_peer` will make the server ask the client to provide a certificate.
If the client doesn't provide a certificate, the connection will be closed.

This option needs to be used with `ssl_certificate_authorities` and a defined list of CAs.

[id="plugins-{type}s-{plugin}-tls_max_version"]
===== `tls_max_version` 

  * Value type is <<number,number>>
  * Default value is `1.2`

The maximum TLS version allowed for the encrypted connections. The value must be the one of the following:
1.0 for TLS 1.0, 1.1 for TLS 1.1, 1.2 for TLS 1.2

[id="plugins-{type}s-{plugin}-tls_min_version"]
===== `tls_min_version` 

  * Value type is <<number,number>>
  * Default value is `1`

The minimum TLS version allowed for the encrypted connections. The value must be one of the following:
1.0 for TLS 1.0, 1.1 for TLS 1.1, 1.2 for TLS 1.2



[id="plugins-{type}s-{plugin}-common-options"]
include::{include_path}/{type}.asciidoc[]

:default_codec!: