Overview

Execbeat is the Beat used to execute any command. Multiple commands can be configured which are executed in a regular interval and the standard output and standard error is shipped to the configured output channel.

Execbeat is inspired by the Logstash exec input filter but doesn't require that the endpoint is reachable by Logstash as Execbeat pushes the data to Logstash or Elasticsearch. This is often necessary in security restricted network setups, where Logstash is not able to reach all servers. Instead the server to be monitored itself has Execbeat installed and can send the data or a collector server has Execbeat installed which is deployed in the secured network environment and can reach all servers to be monitored.

Ensure that this folder is at the following location: ${GOPATH}/src/github.com/edgarm1964

Build information

Execbeat is built against the following Beats versions and if execbeat was able to connect to a running Elastic Search instance or not.

Build against	Connect to ES 6.5.1	ES 6.8.0	ES 7.0.0	ES 7.1.1	ES 7.2.0
Beats 6.5.1	OK	OK	Fails	N/T	N/T
Beats 6.8.0	OK	OK	OK	OK	OK
Beats 6.8.1	OK	OK	OK	OK	OK
Beats 7.0.0	OK	OK	OK	OK	OK
Beats 7.1.1	OK	OK	OK	OK	OK
Beats 7.2.0	OK	OK	OK	OK	OK

N/T: Not Tested

Installation

Download

Pre-compiled binaries for different operating systems are available for download.

Installation

Install the package for your operation system by running the respective package manager or unzipping the package.

Configuration

Adjust the execbeat.yml configuration file to your needs. You may take execbeat.reference.yml as an example containing all possible configuration values. The output of the executed command is stored in the strings stdout and stderr, The exit code is stored in extiCode. The command itself is stored in command. All fields can be accessed using the processors Beats provides. See Decode JSON fields example

Simple example

The list is a YAML array, so each command begins with a dash (-). You can specify multiple commands, and you can specify the same command type more than once. For example:

execbeat.commands:
  - command: date
    period: 2m
    args: '+%Y%m%dT%H%M%S'
    fields:
      app: MyApplication
      env: test
    fields_under_root: true

Decode JSON fields example

If a command returns a JSON formatted string, it is possible to use processors to split the fields of such a string into separate fields. Example:

execbeat.commands:
  - command: /usr/local/bin/a-json-script.sh
    period: 5m
    # args:

processors:
  - decode_json_fields:
      fields: ["stdout"]
      process_array: true
      max_depth: 1
      target: ""
      overwrite_keys: false

Visit processors for more information on processors and their use.

Running

In order to start Execbeat please use the respective startup script, e.g. /usr/bin/execbeat.sh. For more information, run execbeat --help

Starting Execbeat as Service

Where supported Execbeat can be started also using the respetive service scripts, e.g. etc/init.d/execbeat.

Building and Releasing Execbeat

Requirements

Golang = 1.12.4
Glide >= 0.13.0
Mage >= 1.8.0

Build

To build the binary for execbeat run the command below. This will generate a binary in the same directory with the name execbeat.

make clean && make

Run

To run execbeat with debugging output enabled, run:

./execbeat -c execbeat.yml -e -d '*'

Test

To test execbeat, run the following command:

make testsuite

alternatively:

make unit-tests
make system-tests
make integration-tests
make coverage-report

The test coverage is reported in the folder ./build/coverage/

Update

Each beat has a template for the mapping in elasticsearch and a documentation for the fields which is automatically generated based on _meta/fields.yml. To generate docs/execbeat.template.json and docs/execbeat.asciidoc

make update

Cleanup

To clean execbeat source code, run the following commands:

make check
make simplify

To clean up the build directory and generated artifacts, run:

make clean

Clone

To clone execbeat from the git repository, run the following commands:

mkdir -p ${GOPATH}/github.com/edgarm1964
cd ${GOPATH}/github.com/edgarm1964
git clone https://github.com/edgarm1964/execbeat

For further development, check out the beat developer guide.

Packaging

The beat frameworks provides tools to crosscompile and package your beat for different platforms. This requires docker and vendoring as described above. To build packages of your beat, run the following command:

make release

This will fetch and create all images required for the build process. The complete process to finish can take several minutes.

Releases