////////////////////////////////////////////////////////////////////////// //// 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 <>. . 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 <> 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 <> for info about resolving common errors.