: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}" <1>
    document_type => "%{[@metadata][type]}" <2>
  }
}
------------------------------------------------------------------------------
<1> Specifies the index to write events to. See <<plugins-{type}s-{plugin}-versioned-indexes>> for
more about this setting.
<2> 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, do not 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}-versioned-indexes"]
==== Versioned Beats Indices

To minimize the impact of future schema changes on your existing indices and
mappings in Elasticsearch, configure the Elasticsearch output to write to
versioned indices. The pattern that you specify for the `index` setting
controls the index name:

[source,yaml]
----
index => "%{[@metadata][beat]}-%{[@metadata][version]}-%{+YYYY.MM.dd}"
----

`%{[@metadata][beat]}`:: Sets the first part of the index name to the value of
the `beat` metadata field, for example, `filebeat`.
`%{[@metadata][version]}`:: Sets the second part of the name to the Beat
version, for example, +{logstash_version}+.
`%{+YYYY.MM.dd}`:: Sets the third part of the name to a date based on the
Logstash `@timestamp` field.

This configuration results in daily index names like
+filebeat-{logstash_version}-{localdate}+.

[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}-add_hostname>> |<<boolean,boolean>>|No
| <<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}-ssl_peer_metadata>> |<<boolean,boolean>>|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}-add_hostname"]
===== `add_hostname`

  added[5.1.4, Field was added to allow users to control whether or not the `host` field is automatically added to events.]
  deprecated[5.1.4, In future versions of this plugin, this setting will be removed, and the 'hosts' field will not be added to events.]

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

Flag to determine whether to add `host` field to event using the value supplied by the beat in the `hostname` field.


[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}-ssl_peer_metadata"]
===== `ssl_peer_metadata`

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

Enables storing client certificate information in event's metadata.

This option is only valid when `ssl_verify_mode` is set to `peer` or `force_peer`.

[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!:
