Elasticsearch single-node cluster

Open Distro for Elasticsearch is an open source distribution of Elasticsearch, a highly scalable full-text search engine. It offers advanced security, alerting, index management, deep performance analysis, and several other additional features.

This document will explain how to install Elasticsearch in a single-node cluster.

Note

Root user privileges are necessary to run all the commands described below.

Installing Elasticsearch

Prerequisites

Open Distro for Elasticsearch requires the Java Development Kit and other packages installation including wget, curl, and unzip that will be used in further steps:

Install all the necessary packages for the installation:

# export JAVA_HOME=/usr/ && yum install curl unzip wget && yum install java-11-openjdk-devel

In case JDK 11 is not available for the operating system being used, install the package adoptopenjdk-11-hotspot using Adopt Open JDK.

Install all the necessary packages for the installation:

# apt install curl apt-transport-https unzip wget software-properties-common

Add the repository for Java Development Kit (JDK):

  • For Debian:

    # echo 'deb http://deb.debian.org/debian stretch-backports main' > /etc/apt/sources.list.d/backports.list
    
  • For Ubuntu and other Debian based OS:

    # add-apt-repository ppa:openjdk-r/ppa
    

Update repository data:

# apt update

Install all the required utilities:

# export JAVA_HOME=/usr/ && apt install openjdk-11-jdk

In case JDK 11 is not available for the operating system being used, install the package adoptopenjdk-11-hotspot using Adopt Open JDK.

Install all the necessary packages for the installation:

# export JAVA_HOME=/usr/ && zypper install curl unzip wget && zypper install java-11-openjdk-devel

In case JDK 11 is not available for the operating system being used, install the package adoptopenjdk-11-hotspot using Adopt Open JDK.

Adding the Wazuh repository

  1. Import the GPG key:

    # rpm --import https://packages.wazuh.com/key/GPG-KEY-WAZUH
    
  2. Add the repository:

    # cat > /etc/yum.repos.d/wazuh.repo << EOF
    [wazuh]
    gpgcheck=1
    gpgkey=https://packages.wazuh.com/key/GPG-KEY-WAZUH
    enabled=1
    name=EL-$releasever - Wazuh
    baseurl=https://packages.wazuh.com/4.x/yum/
    protect=1
    EOF
    
  1. Install the GPG key:

    # curl -s https://packages.wazuh.com/key/GPG-KEY-WAZUH | apt-key add -
    
  2. Add the repository:

    # echo "deb https://packages.wazuh.com/4.x/apt/ stable main" | tee -a /etc/apt/sources.list.d/wazuh.list
    
  3. Update the package information:

    # apt-get update
    
  1. Import the GPG key:

    # rpm --import https://packages.wazuh.com/key/GPG-KEY-WAZUH
    
  2. Add the repository:

    # cat > /etc/zypp/repos.d/wazuh.repo <<\EOF
    [wazuh]
    gpgcheck=1
    gpgkey=https://packages.wazuh.com/key/GPG-KEY-WAZUH
    enabled=1
    name=EL-$releasever - Wazuh
    baseurl=https://packages.wazuh.com/4.x/yum/
    protect=1
    EOF
    

Elasticsearch installation

Install Open Distro for Elasticsearch:

Install Open Distro for Elasticsearch:

# yum install opendistroforelasticsearch

Install Elasticsearch OSS and Open Distro for Elasticsearch:

# apt install elasticsearch-oss opendistroforelasticsearch

Install Open Distro for Elasticsearch:

# zypper install opendistroforelasticsearch

Elasticsearch configuration

Once Elasticsearch is installed, download the pre-configured configuration file:

# curl -so /etc/elasticsearch/elasticsearch.yml https://raw.githubusercontent.com/wazuh/wazuh-documentation/4.1/resources/open-distro/elasticsearch/7.x/elasticsearch.yml

This file configures Elasticsearch to use 0.0.0.0 for the network.host variable, so it will accept communications directed to any of its IP addresses instead of binding to the IP of a specific network interface in the host. Access may be restricted to a specific network interface by specifying its IP in this setting so Elasticsearch may not be unnecessarily exposed.

Elasticsearch roles and users

In order to use the Wazuh Kibana plugin properly, it is necessary to add the extra roles and users:

# curl -so /usr/share/elasticsearch/plugins/opendistro_security/securityconfig/roles.yml https://raw.githubusercontent.com/wazuh/wazuh-documentation/4.1/resources/open-distro/elasticsearch/roles/roles.yml
# curl -so /usr/share/elasticsearch/plugins/opendistro_security/securityconfig/roles_mapping.yml https://raw.githubusercontent.com/wazuh/wazuh-documentation/4.1/resources/open-distro/elasticsearch/roles/roles_mapping.yml
# curl -so /usr/share/elasticsearch/plugins/opendistro_security/securityconfig/internal_users.yml https://raw.githubusercontent.com/wazuh/wazuh-documentation/4.1/resources/open-distro/elasticsearch/roles/internal_users.yml

Wazuh users added in Kibana by running the commands above:

wazuh_user

It is created for users who need read-only access to the Wazuh Kibana plugin.

wazuh_admin

It is recommended user for users who need administrative privileges.

Wazuh additional roles added in Kibana to give the appropriate permissions to users:

wazuh_ui_user

It provides wazuh_user permissions to read the Wazuh indices.

wazuh_ui_admin

It allows wazuh_admin to perform reading, writing, management, and indexing tasks on the Wazuh indices.

These users and roles are designed to operate along with the Wazuh Kibana plugin and they are protected so they cannot be modified from the Kibana’s interface. To modify them or add new users or roles, the securityadmin script has to be run.

Certificates creation and deployment

  1. Remove the demo certificates:

    # rm /etc/elasticsearch/esnode-key.pem /etc/elasticsearch/esnode.pem /etc/elasticsearch/kirk-key.pem /etc/elasticsearch/kirk.pem /etc/elasticsearch/root-ca.pem -f
    
  2. Generate and deploy the certificates:

    • Move to the installation location and create the certificates directory:

      # mkdir /etc/elasticsearch/certs
      # cd /etc/elasticsearch/certs
      
    • Download the Search Guard offline TLS tool to create the certificates:

      # curl -so ~/search-guard-tlstool-1.8.zip https://maven.search-guard.com/search-guard-tlstool/1.8/search-guard-tlstool-1.8.zip
      
    • Extract the downloaded file. It is assumed that it has been downloaded in ~/ (home directory):

      # unzip ~/search-guard-tlstool-1.8.zip -d ~/searchguard
      
    • Download the search-guard.yml configuration file. Choose either Wazuh single-node cluster if there is only one Wazuh server, or Wazuh multi-node cluster in case of having more than one Wazuh servers:

      # curl -so ~/searchguard/search-guard.yml https://raw.githubusercontent.com/wazuh/wazuh-documentation/4.1/resources/open-distro/searchguard/single-node/search-guard.yml
      

      After downloading the configuration file in ~/searchguard/search-guard.yml, replace the values <elasticsearch_IP> and <kibana_ip> with the corresponding IP addresses. More than one IP can be specified (one entry per line):

      # Nodes certificates
      nodes:
        - name: elasticsearch
          dn: CN=node-1,OU=Docu,O=Wazuh,L=California,C=US
          ip:
            - <elasticsearch_IP>
        - name: kibana
          dn: CN=kibana,OU=Docu,O=Wazuh,L=California,C=US
          ip:
            - <kibana_ip>
      
      # curl -so ~/searchguard/search-guard.yml https://raw.githubusercontent.com/wazuh/wazuh-documentation/4.1/resources/open-distro/searchguard/single-node/search-guard-multi-node.yml
      

      After downloading the configuration file, replace the value <elasticsearch_IP> and <kibana_ip> with the corresponding IP addresses in the file ~/searchguard/search-guard.yml. More than one IP can be specified (one entry per line):

      # Nodes certificates
      nodes:
        - name: elasticsearch
          dn: CN=node-1,OU=Docu,O=Wazuh,L=California,C=US
          ip:
            - <elasticsearch_IP>
        - name: kibana
          dn: CN=kibana,OU=Docu,O=Wazuh,L=California,C=US
          ip:
            - <kibana_ip>
      

      There should be as many filebeat-X sections as Wazuh servers in the installation:

      - name: filebeat-1
        dn: CN=filebeat-1,OU=Docu,O=Wazuh,L=California,C=US
      - name: filebeat-2
        dn: CN=filebeat-2,OU=Docu,O=Wazuh,L=California,C=US
      

      To learn more about how to create and configure the certificates visit the Certificates deployment section.

    • Run the Search Guard’s script to create the certificates:

      # ~/searchguard/tools/sgtlstool.sh -c ~/searchguard/search-guard.yml -ca -crt -t /etc/elasticsearch/certs/
      

      In case of further certificates deployments, it is highly recommended to keep Search Guard’s TLS offline tool and its configuration file search-guard.yml on the master node.

    • Compress all the necessary files to be sent to the all the instances:

      # tar -cf /etc/elasticsearch/certs/certs.tar *
      
    • Copy certs.tar to all the servers of the distributed deployment. This can be done by using, for example, scp.

    • Remove unnecessary files:

      # rm /etc/elasticsearch/certs/client-certificates.readme /etc/elasticsearch/certs/elasticsearch_elasticsearch_config_snippet.yml search-guard-tlstool-1.7.zip filebeat* -f
      
    • If Kibana will be installed in this node, keep the certificates file. Otherwise, if the file has been already copied to all the instances of the distributed deployment, remove it to increase security rm -f certs.tar.

  3. Enable and start the Elasticsearch service:

    # systemctl daemon-reload
    # systemctl enable elasticsearch
    # systemctl start elasticsearch
    

    Choose one option according to the operating system used:

    1. RPM based operating system:

    # chkconfig --add elasticsearch
    # service elasticsearch start
    
    1. Debian based operating system:

    # update-rc.d elasticsearch defaults 95 10
    # service elasticsearch start
    
  4. Run the Elasticsearch’s securityadmin script to load the new certificates information and start the cluster. To run this command, the value <elasticsearch_IP> must be replaced by the Elasticsearch installation IP:

# /usr/share/elasticsearch/plugins/opendistro_security/tools/securityadmin.sh -cd /usr/share/elasticsearch/plugins/opendistro_security/securityconfig/ -nhnv -cacert /etc/elasticsearch/certs/root-ca.pem -cert /etc/elasticsearch/certs/admin.pem -key /etc/elasticsearch/certs/admin.key -h <elasticsearch_IP>

Run the following command to ensure that the installation has been successful:

# curl -XGET https://localhost:9200 -u admin:admin -k

An example response should look as follows:

 {
   "name" : "node-1",
   "cluster_name" : "elasticsearch",
   "cluster_uuid" : "J4EAfzd7R4KZv-31jBAuNA",
   "version" : {
     "number" : "7.10.0",
     "build_flavor" : "oss",
     "build_type" : "rpm",
     "build_hash" : "51e9d6f22758d0374a0f3f5c6e8f3a7997850f96",
     "build_date" : "2020-11-09T21:30:33.964949Z",
     "build_snapshot" : false,
     "lucene_version" : "8.7.0",
     "minimum_wire_compatibility_version" : "6.8.0",
     "minimum_index_compatibility_version" : "6.0.0-beta1"
   },
   "tagline" : "You Know, for Search"
 }

Note

The Open Distro for Elasticsearch performance analyzer plugin is installed by default and can have a negative impact on system resources. We recommend removing it with the following command /usr/share/elasticsearch/bin/elasticsearch-plugin remove opendistro_performance_analyzer. Please be sure to restart the Elasticsearch service afterwards.

It is highly recommended to change Elasticsearch’s default passwords for the users found at the /usr/share/elasticsearch/plugins/opendistro_security/securityconfig/internal_users.yml file. More information about this process can be found here. It is also recommended to customize the file /etc/elasticsearch/jvm.options in order to improve the performance of Elasticsearch. Learn more about this process in the Elasticsearch tuning section.

To uninstall Elasticsearch, visit the uninstalling section.

Next steps

The next step is the installation of the Wazuh server, select the cluster mode: