//////////////////////////////////////////////////////////////////////////
//// This content is shared by all Elastic Beats. Make sure you keep the
//// descriptions here generic enough to work for all Beats that include
//// this file. When using cross references, make sure that the cross
//// references resolve correctly for any files that include this one.
//// Use the appropriate variables defined in the index.asciidoc file to
//// resolve Beat names: beatname_uc and beatname_lc.
//// Use the following include to pull this content into a doc file:
//// include::../../libbeat/docs/shared-ssl-logstash-config.asciidoc[]
//////////////////////////////////////////////////////////////////////////

[role="xpack"]
[[configuring-ssl-logstash]]
== Secure communication with Logstash

You can use SSL mutual authentication to secure connections between {beatname_uc} and Logstash. This ensures that
{beatname_uc} sends encrypted data to trusted Logstash servers only, and that the Logstash server receives data from
trusted {beatname_uc} clients only.

To use SSL mutual authentication:

. Create a certificate authority (CA) and use it to sign the certificates that you plan to use for
{beatname_uc} and Logstash. Creating a correct SSL/TLS infrastructure is outside the scope of this
document. There are many online resources available that describe how to create certificates.
+
TIP: If you are using {security-features}, you can use the
{ref}/certutil.html[elasticsearch-certutil tool] to generate certificates.

. Configure {beatname_uc} to use SSL. In the +{beatname_lc}.yml+ config file, specify the following settings under
`ssl`:
+
* `certificate_authorities`: Configures {beatname_uc} to trust any certificates signed by the specified CA. If
`certificate_authorities` is empty or not set, the trusted certificate authorities of the host system are used.

* `certificate` and `key`: Specifies the certificate and key that {beatname_uc} uses to authenticate with
Logstash.
+
For example:
+
[source,yaml]
------------------------------------------------------------------------------
output.logstash:
  hosts: ["logs.mycompany.com:5044"]
  ssl.certificate_authorities: ["/etc/ca.crt"]
  ssl.certificate: "/etc/client.crt"
  ssl.key: "/etc/client.key"
------------------------------------------------------------------------------
+
For more information about these configuration options, see <<configuration-ssl>>.

. Configure Logstash to use SSL. In the Logstash config file, specify the following settings for the https://www.elastic.co/guide/en/logstash/current/plugins-inputs-beats.html[Beats input plugin for Logstash]:
+
* `ssl`: When set to true, enables Logstash to use SSL/TLS.
* `ssl_certificate_authorities`: Configures Logstash to trust any certificates signed by the specified CA.
* `ssl_certificate` and `ssl_key`: Specify the certificate and key that Logstash uses to authenticate with the client.
* `ssl_verify_mode`: Specifies whether the Logstash server verifies the client certificate against the CA. You
need to specify either `peer` or `force_peer` to make the server ask for the certificate and validate it. If you
specify `force_peer`, and {beatname_uc} doesn't provide a certificate, the Logstash connection will be closed. If you choose not to use {ref}/certutil.html[certutil], the certificates that you obtain must allow for both `clientAuth` and `serverAuth` if the extended key usage extension is present.
+
For example:
+
[source,json]
------------------------------------------------------------------------------
input {
  beats {
    port => 5044
    ssl => true
    ssl_certificate_authorities => ["/etc/ca.crt"]
    ssl_certificate => "/etc/server.crt"
    ssl_key => "/etc/server.key"
    ssl_verify_mode => "force_peer"
  }
}
------------------------------------------------------------------------------
+
For more information about these options, see the
https://www.elastic.co/guide/en/logstash/current/plugins-inputs-beats.html[documentation for the Beats input plugin].

[float]
[[testing-ssl-logstash]]
=== Validate the Logstash server's certificate

Before running {beatname_uc}, you should validate the Logstash server's certificate. You can use `curl` to validate the certificate even though the protocol used to communicate with Logstash is not based on HTTP. For example:

[source,shell]
------------------------------------------------------------------------------
curl -v --cacert ca.crt https://logs.mycompany.com:5044
------------------------------------------------------------------------------

If the test is successful, you'll receive an empty response error:

[source,shell]
------------------------------------------------------------------------------
* Rebuilt URL to: https://logs.mycompany.com:5044/
*   Trying 192.168.99.100...
* Connected to logs.mycompany.com (192.168.99.100) port 5044 (#0)
* TLS 1.2 connection using TLS_DHE_RSA_WITH_AES_256_CBC_SHA
* Server certificate: logs.mycompany.com
* Server certificate: mycompany.com
> GET / HTTP/1.1
> Host: logs.mycompany.com:5044
> User-Agent: curl/7.43.0
> Accept: */*
>
* Empty reply from server
* Connection #0 to host logs.mycompany.com left intact
curl: (52) Empty reply from server
------------------------------------------------------------------------------

The following example uses the IP address rather than the hostname to validate the certificate:

[source,shell]
------------------------------------------------------------------------------
curl -v --cacert ca.crt https://192.168.99.100:5044
------------------------------------------------------------------------------

Validation for this test fails because the certificate is not valid for the specified IP address. It's only valid for the `logs.mycompany.com`, the hostname that appears in the Subject field of the certificate.

[source,shell]
------------------------------------------------------------------------------
* Rebuilt URL to: https://192.168.99.100:5044/
*   Trying 192.168.99.100...
* Connected to 192.168.99.100 (192.168.99.100) port 5044 (#0)
* WARNING: using IP address, SNI is being disabled by the OS.
* SSL: certificate verification failed (result: 5)
* Closing connection 0
curl: (51) SSL: certificate verification failed (result: 5)
------------------------------------------------------------------------------

See the <<ssl-client-fails,troubleshooting docs>> for info about resolving this issue.

[float]
=== Test the {beatname_uc} to Logstash connection

If you have {beatname_uc} running as a service, first stop the service. Then test your setup by running {beatname_uc} in
the foreground so you can quickly see any errors that occur:

["source","sh",subs="attributes,callouts"]
------------------------------------------------------------------------------
{beatname_lc} -c {beatname_lc}.yml -e -v
------------------------------------------------------------------------------

Any errors will be printed to the console. See the <<ssl-client-fails,troubleshooting docs>> for info about
resolving common errors.
