140 lines
6.8 KiB
Text
140 lines
6.8 KiB
Text
//////////////////////////////////////////////////////////////////////////
|
|
//// 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[]
|
|
//////////////////////////////////////////////////////////////////////////
|
|
|
|
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}, you can use the
|
|
{elasticsearch}/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 {elasticsearch}/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 Beats 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.
|