How to send email with a Kibana report attached using X-Pack watchers

I have spent several days trying to figure out how to use Elastic, Kibana and X-Pack to automatically send emails with Kibana reports attached to them. As of right now the X-Pack documentation is a bit sparse, so I thought I would share my solution.

Install Elasticsearch 5.0.1

First you have to install elastic. I already have a post about this that can be found here.

Fill Elastic with some data

When Elasticsearch is successfully installed and running, fill it with some data. I’m using Sense to add an activitylog index containing data about users activity on a website.

Install Kibana 5.0.1

You can find the download and installation guide here. When opening Kibana for the first time you will be asked to select a default index pattern. In my case I am using “activitylog” beacuse this is the only index I am interested in for this demo.

Install X-Pack

Stop Kibana and Elastic and install X-Pack as according to documentation. When the installation is complete you have to log in to Kibana and Elastic with the built-in user “elastic” using the password “changeme”.

Send email notifications using X-Pack

I am using Gmail as my mail service in this demo, but Watcher can send email using any SMTP email service.

First, you need to have a Gmail account. To make this tutorial as simple and basic as possible, I have turned off two step authentication and configured gmail to allow less secure apps. Then you have to stop your Kibana and Elastic services and add the following settings to your elasticsearch.yml file.

xpack.notification.email.account:
    gmail_account:
        profile: gmail
        smtp:
            auth: true
            starttls.enable: true
            host: smtp.gmail.com
            port: 587
            user: <username>
            password: <password>

You can skip this step, but just to make sure that X-Pack notifications is working as expected, we create a watcher using Sense (you might have to logon using the elastic user) that sends an email every 60 seconds. Make sure the email is sent and received.

PUT http://localhost:9200/_xpack/watcher/watch/<name_of_report>
{
    "trigger": {
        "schedule": {
            "interval": "60s"
        }
    },
    "actions" : {
          "send_email" : { 
            "email" : { 
                  "to" : "<username>@<domainname>", 
                  "subject" : "Testing watcher notification", 
                  "body" : "{{ctx.payload.hits.total}} error logs found" 
            }
          }
    }
}

You can delete the watcher again using the following request

DELETE http://localhost:9200/_xpack/watcher/watch/<name_of_report>

Stop Elastic and Kibana services again. To enable the X-pack watcher to request Kibana reports we need to secure the endpoints. First, we need to enable message authentication to verify that messages are not tampered with. Run the following command in your elastic folder

bin\x-pack\syskeygen

and add the following to your elasticsearch.yml config file

xpack.security.audit.enabled: true

Then you need to generate a server certificate for Kibana and add the location of the key and the certificate to the kibana.yml file. Remeber to add this file to your Kibana config folder because Kibana runs under a security manager with a restricted set of directories that can be read.

server.ssl.key: C:\<my_path>\kibana-5.0.1-windows-x86\config\certificate\kibana.local.key
server.ssl.cert: C:\<my_path>\kibana-5.0.1-windows-x86\config\certificate\kibana.local.crt
xpack.security.encryptionKey: "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"

I also added the encryption key (must be at least 32 characters long) because Kibana will generate a new one every time it is restarted if I don’t.

As a final step you have to generate a truststore for the X-pack watcher. Use the Java keytool and run the following command to create it.

keytool -importcert -keystore watcher-truststore.jks -file C:\<path_to_certificate>\kibana.local.crt

 Move watcher-truststore.jks to the config folder within elastic for same reasons as with Kibanas certificate, and add the following settings to elasticsearch.yml.

xpack.security.http.ssl.truststore.path: C:\<my_path>\elasticsearch-5.0.1\config\certificate\watcher-truststore.jks
xpack.security.http.ssl.truststore.password: <truststore_password>

I’m using a self signed certificate for kibana.local. Since no certification authorities have approved this certificate I am adding the following to my elasticsearch.yml file. This is not recommended for production environment and should not be necessary if you have a proper certificate.

xpack.ssl.verification_mode: none

I also need to add kibana.local to my hosts file because this is the domain my certificate is created for.

You may now start your Elastic and Kibana server. From now on you need to use https when accessing Kibana. Create a search, visualization or dashboard in Kibana and copy the reporting generation url. Paste the reporting url into the following request that generates an email with the kibana report attached every 60 seconds.

PUT http://localhost:9200/_xpack/watcher/watch/kibana_report1
{
  "trigger" : {
    "schedule": {
      "interval": "60s"
    }
  },
  "actions" : {
  "email_admin" : {
    "email": {
      "to": "<username>@<domainname>",
      "subject": "My first kibana report",
      "attachments" : {
        "kibana_report.pdf" : {
          "http" : {
            "content_type" : "application/pdf",
            "request" : {
              "method": "POST",
              "scheme": "https", 
              "headers": {
                "kbn-xsrf": "reporting"
              },
              "auth": { 
                "basic": {
                  "username": "<elastic_user>",
                  "password": "<elastic_user_password>"
                }
              },
              "read_timeout": "300s",
              "url": "<kibana_report_url>"
            }
          }
        }
      }
    }
  }
 }
}

The built in elastic user has the username “elastic” and password “changeme”. You also need to remember to set the “read_timeout” property to last longer the the time used for Kibana to generate the report.

If everything was set up correctly you should be sending emails with the selected Kibana report as an attachment.