The Open Distro project is archived. Open Distro development has moved to OpenSearch. The Open Distro plugins will continue to work with legacy versions of Elasticsearch OSS, but we recommend upgrading to OpenSearch to take advantage of the latest features and improvements.

Tarball

The tarball installation works on Linux systems and provides a self-contained directory with everything you need to run Open Distro, including an integrated Java Development Kit (JDK). The tarball is a good option for testing and development, but we recommend Docker or a package manager for production deployments.

The tarball supports CentOS 7, Amazon Linux 2, Ubuntu 18.04, and most other Linux distributions. If you have your own Java installation and you set JAVA_HOME in the terminal, macOS works as well.

Download the tarball:

Open Distro is no longer being developed and exists only as an archive. Please visit OpenSearch documentation to get started with OpenSearch.

Download the checksum:

(No longer available.)

Verify the tarball against the checksum:

# x64
shasum -a 512 -c opendistroforelasticsearch-1.13.3-linux-x64.tar.gz.sha512
# ARM64
shasum -a 512 -c opendistroforelasticsearch-1.13.3-linux-arm64.tar.gz.sha512

On CentOS, you might not have shasum. Install this package:

sudo yum install perl-Digest-SHA

Due to a known issue with the checksum, this step might fail. You can still proceed with the installation.

Extract the TAR file to a directory and change to that directory:

# x64
tar -zxf opendistroforelasticsearch-1.13.3-linux-x64.tar.gz
cd opendistroforelasticsearch-1.13.3
# ARM64
tar -zxf opendistroforelasticsearch-1.13.3-linux-arm64.tar.gz
cd opendistroforelasticsearch-1.13.3

Run Open Distro:
```
./opendistro-tar-install.sh
```

Open a second terminal session, and send requests to the server to verify that Open Distro is up and running:

curl -XGET https://localhost:9200 -u 'admin:admin' --insecure
curl -XGET https://localhost:9200/_cat/plugins?v -u 'admin:admin' --insecure

Configuration

You can modify config/elasticsearch.yml or specify environment variables as arguments using -E:

./opendistro-tar-install.sh -Ecluster.name=odfe-cluster -Enode.name=odfe-node1 -Ehttp.host=0.0.0.0 -Ediscovery.type=single-node

For other settings, see Important settings.

(Optional) Set up Performance Analyzer

In a tarball installation, Performance Analyzer collects data when it is enabled. But in order to read that data using the REST API on port 9600, you must first manually launch the associated reader agent process:

Make Performance Analyzer accessible outside of the host machine

cd /usr/share/elasticsearch # navigate to the Elasticsearch home directory
cd plugins/opendistro_performance_analyzer/pa_config/
vi performance-analyzer.properties

Uncomment the line #webservice-bind-host and set it to 0.0.0.0:

# ======================== Elasticsearch performance analyzer plugin config =========================

# NOTE: this is an example for Linux. Please modify the config accordingly if you are using it under other OS.

# WebService bind host; default to all interfaces
webservice-bind-host = 0.0.0.0

# Metrics data location
metrics-location = /dev/shm/performanceanalyzer/

# Metrics deletion interval (minutes) for metrics data.
# Interval should be between 1 to 60.
metrics-deletion-interval = 1

# If set to true, the system cleans up the files behind it. So at any point, we should expect only 2
# metrics-db-file-prefix-path files. If set to false, no files are cleaned up. This can be useful, if you are archiving
# the files and wouldn't like for them to be cleaned up.
cleanup-metrics-db-files = true

# WebService exposed by App's port
webservice-listener-port = 9600

# Metric DB File Prefix Path location
metrics-db-file-prefix-path = /tmp/metricsdb_

https-enabled = false

#Setup the correct path for certificates
certificate-file-path = specify_path

private-key-file-path = specify_path

# Plugin Stats Metadata file name, expected to be in the same location
plugin-stats-metadata = plugin-stats-metadata

# Agent Stats Metadata file name, expected to be in the same location
agent-stats-metadata = agent-stats-metadata

Make the CLI executable:

sudo chmod +x ./bin/performance-analyzer-agent-cli

Launch the agent CLI:

ES_HOME="$PWD" ./bin/performance-analyzer-agent-cli

In a separate window, enable the Performance Analyzer plugin:

curl -XPOST localhost:9200/_opendistro/_performanceanalyzer/cluster/config -H 'Content-Type: application/json' -d '{"enabled": true}'

If you receive the curl: (52) Empty reply from server error, you are likely protecting your cluster with the security plugin and you need to provide credentials. Modify the following command to use your username and password:

curl -XPOST https://localhost:9200/_opendistro/_performanceanalyzer/cluster/config -H 'Content-Type: application/json' -d '{"enabled": true}' -u 'admin:admin' -k

Finally, enable the Root Cause Analyzer (RCA) framework

curl -XPOST localhost:9200/_opendistro/_performanceanalyzer/rca/cluster/config -H 'Content-Type: application/json' -d '{"enabled": true}'

Similar to step 4, if you run into curl: (52) Empty reply from server, run the command below to enable RCA

curl -XPOST https://localhost:9200/_opendistro/_performanceanalyzer/rca/cluster/config -H 'Content-Type: application/json' -d '{"enabled": true}' -u 'admin:admin' -k

(Optional) Removing Performance Analyzer

See Clean up Performance Analyzer files.

Configuration