Description

This repository contains the official Beats Docker images from Elastic.

These images are currently under development, and should be considered alpha-quality.

Please do not run these images in production, but feel free to experiment.

Prerequisites

1. docker-engine
2. python3.5, python3.5-pip and python3.5 development libraries
3. virtualenv compatible with python3.5

Quick demo

Run make demo to build, test and run the Beats.

Elasticsearch and Kibana containers are also provided. Once the containers are all running, point a browser at http://localhost:5601 to find Kibana, and log in with elastic/changeme as the username and password.

Operational notes

All Beats

Configuration file

Each Beat has a YAML configuration file at /usr/share/[BEAT]/[BEAT].yml. A simple default file is provided, but you will probably want to override it by bind-mounting your own configuration like this:

docker run -v metricbeat.yml:/usr/share/metricbeat/metricbeat.yml docker.elastic.co/beats/metricbeat:5.2.1

Alternatively, you could extend the image like this:

FROM docker.elastic.co/beats/metricbeat:5.2.1
COPY metricbeat.yml /usr/share/metricbeat/metricbeat.yml

Metricbeat

Normally, container isolation prevents Metricbeat from seeing information about the host system and/or other containers. See Running Metricbeat in a Container for details.

In the demo, Metricbeat is configured to monitor processes on the host system.

Filebeat

A common use for a Filebeat container is to monitor logs on the Docker host system. By default, Filebeat is configured to watch all files matching /mnt/log/*.log. Thus, a quick way to get started is to mount the host system's log directory:

docker run -v /var/log:/mnt/log docker.elastic.co/beats/filebeat:5.2.1

This mount is configured in the demo, so Filebeat will ship the logs of the host system.

Packetbeat

Packetbeat runs as a non-root user, but requires some network capabilities to operate correctly. Ensure that the NET_ADMIN capability is available to the container. Like so:

docker run --cap-add=NET_ADMIN docker.elastic.co/beats/packetbeat:5.2.1

You may also wish to connect the Packetbeat container to the host network to see traffic for the host system:

docker run --cap-add=NET_ADMIN --network=host docker.elastic.co/beats/packetbeat:5.2.1

Supported Docker versions

The images have been tested on Docker 1.13.1.

Contributing, issues and testing

Acceptance tests for the images are located in the test directory, and can be invoked with make test. Python 3.5 is required to run the tests. They are based on the excellent testinfra, which is itself based on wonderful pytest.

beats-docker is developed under a test-driven workflow, so please refrain from submitting patches without test coverage. If you are not familiar with testing in Python, please raise an issue instead.

This image is built on Ubuntu 16.04.