ELK Ansible Role

This role installs the ELK stack (Elasticsearch, Logstash, and Kibana) for collecting and monitoring logs. It is designed to work with Riemann for sending alerts.

Requirements

• You need the freedomofpress.generate-ssl-cert role.
• At least 2GB of RAM for the log server.
• Log clients to send logs.

Role Variables

elk_kibana_user: "kibana"
elk_kibana_logfile: "/var/log/kibana.log"

# You can disable the snapshot feature, but it's not well tested. The default is false. 
# If you enable it on the first run, add `meta: flush_handlers` to ensure 
# the `path.repo:` variable is recognized by the elasticsearch service.
elk_elasticsearch_snapshot: false

elk_elasticsearch_snapshot_directory: /var/lib/elasticsearch/backups
elk_elasticsearch_snapshot_repository: es_backup
elk_elasticsearch_snapshot_initialization:
  type: fs
  settings:
    location: "{{ elk_elasticsearch_snapshot_directory }}"
    compress: yes
  _hack: null

# Snapshot name format. The ElasticSearch API does not accept iso8601 format.
elk_elasticsearch_snapshot_name: "snapshot-{{ ansible_date_time.epoch }}"

# Limits for Elasticsearch in /etc/security/limits.conf. 
# Copy the entire list if changing any element.
elk_elasticsearch_pam_limits:
    - domain: elasticsearch
      limit_item: memlock
      limit_type: hard
      value: unlimited

    - domain: elasticsearch
      limit_item: memlock
      limit_type: soft
      value: unlimited

    - domain: elasticsearch
      limit_item: nofile
      limit_type: soft
      value: 65535

    - domain: elasticsearch
      limit_item: nofile
      limit_type: hard
      value: 65535

# Riemann plugin for alerts, de-dot filter for ElasticSearch v2 compatibility
elk_logstash_plugins:
  - logstash-output-riemann
  - logstash-filter-de_dot

# Network interface for firewall rules and IPv4 lookups
elk_network_interface: eth0

elk_cluster_name: elk-logging

# SSL is off by default. Specify the paths to your SSL certificates for HTTPS. 
# You need to place the SSL certificates in a separate play.
elk_nginx_ssl_certificate: ""
elk_nginx_ssl_certificate_key: ""
elk_nginx_server_name: localhost

# Not safe for production! Change for secure logins.
elk_kibana_username: kibana
elk_kibana_password: kibana

# Change the landing page, e.g., to a custom dashboard:
# "dashboard/Your-Dashboard-Name". Replace spaces with hyphens.
elk_kibana_default_app: discover

# Automatically configure IP whitelisting for "logclients" using ufw.
# Disable if using a different firewall configuration.
elk_configure_firewall: true

# Allow other playbooks to use a custom webserver configuration.
# Set to false to skip this role's nginx setup.
elk_configure_nginx: true

# Allow overrides for patterns and filters fileglob list.
elk_logstash_patterns:
  - logstash-patterns/*
elk_logstash_filters:
  - logstash-configs/*

# Specify GeoIP databases to copy. Off by default.
elk_logstash_geoipdbs: []

Usage

Use the role in a playbook like this:

- hosts: logserver
  roles:
    - role: elk
      elk_kibana_username: admin
      elk_kibana_password: WowWhatAStrongPassword4

Adding Visualizations

This role does not automatically create visualizations in Kibana. You can import saved visualizations located in files/kibana-dashboards.json. In the Kibana interface, go to Settings -> Objects -> Import and upload the JSON file.

Running Tests

This role uses Molecule and ServerSpec for testing. Install them with:

pip install molecule
gem install serverspec
molecule test

You can run specific tests with:

molecule idempotence
molecule verify

Check the Molecule documentation for more details.

Further Reading

Setup

• Official ElasticSearch Documentation
• UCLA ELK Configuration
• DigitalOcean Guide for Setting Up ELK

Developing Custom Filters

• Grok Debugger
• Grok Constructor
• How to Develop Logstash Configuration Files

See the examples/writing-filters folder in this repo for a ready-to-use development environment. Copy the folder to a server with Logstash installed, or use a Vagrant testing VM.

Maintenance

• Elasticsearch Curator
• Elasticsearch Zero-Downtime Reindexing

License

MIT