Install & Run Elasticsearch

The current Elasticsearch settings by default allow automatic index creation if a document is pushed into a non-existent index. With this feature and a loophole in Zephyr's indexing process, users can create new indexes without intending to. This causes an indexing issue, as the indexing percentage will drop to ~1%, and the index-relate functionality is affected.

To stop this, configure Elasticsearch to disallow any index for Zephyr. As a result, any index which begins with the name "Zephyr" will be disallowed for automatic creation.

Zephyr Enterprise requires Elasticsearch 7.16.2 as the search engine.

Notes:

Elasticsearch must be running before you install Zephyr Enterprise. You connect your Zephyr instance to Elasticsearch during product installation. See below for complete information.
This page describes installation of Elasticsearch in its default configuration with authentication disabled. For information on turning on authentication, see Enable Authentication in Elasticsearch.

Install and configure Elasticsearch on a single node

On Windows

Download Elasticsearch.
Unzip the downloaded file.

Open the file elasticsearch-7.16.2\config\elasticsearch.yml and make the following changes.

If you are going to connect to Elasticsearch using the IP address:

cluster.name: zephyr
node.name: "ESNode1"
network.host: 192.168.0.1
http.port: 9200
bootstrap.memory_lock: true
xpack.security.enabled: false
discovery.seed_hosts: ["192.168.0.1"]
indices.query.bool.max_clause_count: 9024

If you are going to connect to Elasticsearch using the hostname:

cluster.name: zephyr
node.name: "ESNode1"
network.host: 127.0.0.1
http.port: 9200
bootstrap.memory_lock: true
xpack.security.enabled: false
discovery.seed_hosts: ["127.0.0.1"]
indices.query.bool.max_clause_count: 9024

Start Elasticsearch by running the elasticsearch-7.16.2\bin\elasticsearch.bat file.

You can also install Elasticsearch on Windows as a service. To do that:

Open the command prompt as a user or admin.
Navigate to the <Elasticsearch>/bin folder.
Run the following command:
elasticsearch-service.bat install

Now check your Windows services. You will see the running Elasticsearch service.

For more information on system configuration, see Configuring System Settings.

On Linux

Install Elasticsearch using the .tar.gz file

Download Elasticsearch.

Use the following command to unpack the archive:

tar -xvf elasticsearch-7.16.2-linux-x86_64.tar.gz

Open the file elasticsearch-7.16.2\config\elasticsearch.yml and make the following changes.

If you a going to connect to Elasticsearch using the IP address:

cluster.name: zephyr
node.name: "ESNode1"
network.host: 192.168.0.1
discovery.seed_hosts: ["192.168.0.1"]
http.port: 9200
bootstrap.memory_lock: true
discovery.type: single-node
xpack.security.enabled: false
indices.query.bool.max_clause_count: 9024

If you are going to connect to Elasticsearch using the hostname:

cluster.name: zephyr
node.name: "ESNode1"
network.host: 127.0.0.1
discovery.seed_hosts: ["127.0.0.1"]
http.port: 9200
bootstrap.memory_lock: true
discovery.type: single-node
xpack.security.enabled: false
indices.query.bool.max_clause_count: 9024

Start Elasticsearch by running the following command:
sudo systemctl start elasticsearch.service

For more information on system configuration, see Configuring System Settings.

Install Elasticsearch using the .rmp file

Download Elasticsearch.
Install Elasticsearch by running the command below:
yum install elasticsearch-7.16.2-x86_64.rpm

Open the /etc/elasticsearch/elasticsearch.yml file for editing and configure it in the following way.

If you a going to connect to Elasticsearch using the IP address:

cluster.name: zephyr
node.name: node-1
path.data: /var/lib/elasticsearch
path.logs: /var/log/elasticsearch
bootstrap.memory_lock: true
network.host: 192.168.0.1
xpack.security.enabled: false
discovery.seed_hosts: ["192.168.0.1"]
http.port: 9200
indices.query.bool.max_clause_count: 9024

If you are going to connect to Elasticsearch using the hostname:

cluster.name: zephyr
node.name: node-1
path.data: /var/lib/elasticsearch
path.logs: /var/log/elasticsearch
bootstrap.memory_lock: true
network.host: localhost
xpack.security.enabled: false
discovery.seed_hosts: ["localhost"]
http.port: 9200
indices.query.bool.max_clause_count: 9024

Run the command below to open the system configuration file:
vi /etc/sysconfig/elasticsearch
Uncomment this line:
MAX_LOCKED_MEMORY=unlimited
Start Elasticsearch by running the following command:
sudo systemctl start elasticsearch.service

For more information on system configuration, see Configuring System Settings.

Configure an Elasticsearch cluster (3 nodes)

The number of Elasticsearch nodes you use in a cluster should be odd. That is, the minimum number of nodes you can use in a cluster is 3.
To avoid split-brain, you need to specify an appropriate value for the discovery.zen.minimum_master_nodes parameter. To determine it, follow the rule N/2+1, where N is the number of nodes in the cluster. In a three-node cluster, the parameter should be set to 2 (3/2+1=2 - rounded down to the nearest integer).

On Windows

Download Elasticsearch.
Unzip the downloaded file on all three machines.
On each node, open the file elasticsearch-7.16.2\config\elasticsearch.yml and make the following changes:

Elasticsearch node 1:

#ESNode 1 (192.168.0.1)

cluster.name: zephyr
node.name: node-1
node.master: true
node.data: true
http.port: 9200
bootstrap.memory_lock: false
network.host: 192.168.0.1
discovery.seed_hosts: ["192.168.0.1", "192.168.0.2", "192.168.0.3"]
cluster.initial_master_nodes: ["192.168.0.1", "192.168.0.2", "192.168.0.3"]
xpack.security.enabled: false
indices.query.bool.max_clause_count: 9024

Elasticsearch node 2:

#ESNode 2 (192.168.0.2)

cluster.name: zephyr
node.name: node-2
node.master: true
node.data: true
http.port: 9200
bootstrap.memory_lock: false
network.host: 192.168.0.2
discovery.seed_hosts: ["192.168.0.1", "192.168.0.2", "192.168.0.3"]
cluster.initial_master_nodes: ["192.168.0.1", "192.168.0.2", "192.168.0.3"]
xpack.security.enabled: false
indices.query.bool.max_clause_count: 9024

Elasticsearch node 3:

#ESNode 3 (192.168.0.3)

cluster.name: zephyr
node.name: node-3
http.port: 9200
node.master: true
node.data: true
bootstrap.memory_lock: false
network.host: 192.168.0.3
discovery.seed_hosts: ["192.168.0.1", "192.168.0.2", "192.168.0.3"]
cluster.initial_master_nodes: ["192.168.0.1", "192.168.0.2", "192.168.0.3"]
xpack.security.enabled: false
indices.query.bool.max_clause_count: 9024

4. Start Elasticsearch on each node by running the elasticsearch-7.16.2\bin\elasticsearch.bat file.

On Linux

Download Elasticsearch.
Install Elasticsearch on all three machines by using the following command:
yum install elasticsearch-7.16.2-x86_64.rpm
On each node, open the /etc/elasticsearch/elasticsearch.yml file for editing and configure it in the following way:

Elasticsearch node 1:

#ESNode 1 (192.168.0.1)

cluster.name: zephyr
node.name: node-1
node.master: true
node.data: true
http.port: 9200
bootstrap.memory_lock: false
network.host: 192.168.0.1
discovery.seed_hosts: ["192.168.0.1", "192.168.0.2", "192.168.0.3"]
cluster.initial_master_nodes: ["192.168.0.1", "192.168.0.2", "192.168.0.3"]
xpack.security.enabled: false
indices.query.bool.max_clause_count: 9024

Elasticsearch node 2:

#ESNode 2 (192.168.0.2)

cluster.name: zephyr
node.name: node-2
node.master: true
node.data: true
http.port: 9200
bootstrap.memory_lock: false
network.host: 192.168.0.2
discovery.seed_hosts: ["192.168.0.1", "192.168.0.2", "192.168.0.3"]
cluster.initial_master_nodes: ["192.168.0.1", "192.168.0.2", "192.168.0.3"]
xpack.security.enabled: false
indices.query.bool.max_clause_count: 9024

Elasticsearch node 3:

#ESNode 3 (192.168.0.3)

cluster.name: zephyr
node.name: node-3
http.port: 9200
node.master: true
node.data: true
bootstrap.memory_lock: false
network.host: 192.168.0.3
discovery.seed_hosts: ["192.168.0.1", "192.168.0.2", "192.168.0.3"]
cluster.initial_master_nodes: ["192.168.0.1", "192.168.0.2", "192.168.0.3"]
xpack.security.enabled: false
indices.query.bool.max_clause_count: 9024

Note: The discovery.seed_hosts parameter should contain all the IP addresses used in the cluster.

4. On all three nodes, run the command below to open the system configuration file:

vi /etc/sysconfig/elasticsearch

5. Uncomment this line:

MAX_LOCKED_MEMORY=unlimited

6. Start Elasticsearch on all the nodes by running the following command:

sudo systemctl start elasticsearch.service

After configuring the cluster, change the number_of_shards and number_of_replicas values in the <Zephyr>\tomcat\webapps\flex\WEB-INF\template\zephyr\_settings.json file:

"number_of_shards" : 2,
"number_of_replicas" : 1

For a single node, leave the default values.

For more information on system configuration, see Configuring System Settings.

Enable TLS 1.2 and 1.3 versions for Elasticsearch

You to add the following two lines in the elasticsearch.yml file:

xpack.security.http.ssl.supported_protocols: TLSv1.3, TLSv1.2
xpack.security.transport.ssl.supported_protocols: TLSv1.2, TLSv1.3

The following is the sample .yml file:

cluster.name: zephyr
node.name: "ESNode1"
network.host: 127.0.0.1
http.port: 9200
bootstrap.memory_lock: true
xpack.security.enabled: true
discovery.seed_hosts: ["127.0.0.1"]
cluster.initial_master_nodes: ["ESNode1"]
indices.query.bool.max_clause_count: 9024
xpack.security.transport.ssl.enabled: true
xpack.security.transport.ssl.verification_mode: certificate
xpack.security.transport.ssl.keystore.path: <path to your elasticsearch installation directory>/config/certs/elastic-certificates.p12
xpack.security.transport.ssl.truststore.path: <path to your elasticsearch installation directory>/config/certs/elastic-certificates.p12
xpack.security.http.ssl.enabled: true
xpack.security.http.ssl.keystore.path:<path to your elasticsearch installation directory>/config/certs/elastic-http1.p12
xpack.security.http.ssl.supported_protocols: TLSv1.3, TLSv1.2
xpack.security.transport.ssl.supported_protocols: TLSv1.2, TLSv1.3

Enable Elasticsearch Authentication

By default Elasticsearch installs in its default configuration with authentication disabled. Zephyr can work with Elasticsearch in this configuration.

You may want to enable authentication for more secure connection between Zephyr and Elasticsearch. You can do this, and Zephyr will be able to work with Elasticsearch in this case as well. For complete information on configuration steps, see Enable Authentication in Elasticsearch.

Connect Zephyr to Elasticsearch

Elasticsearch must be running before you install Zephyr Enterprise. You connect Zephyr to Elasticsearch during product installation. To do this, specify either the IP address of your Elasticsearch server, or its host name depending on the settings you have specified in the elasticsearch.yml file.

Single-node installation
Specify http://192.168.0.1:9200, or http://localhost:9200 when prompted to configure Elasticsearch.
Cluster installation
Specify the following IP addresses and port numbers when prompted to configure Elasticsearch. Use commas to separate them:
http://192.168.0.1:9200,http://192.168.0.2:9200,http://192.168.0.3:9200

Zephyr Enterprise 8.0.1 > Elasticsearch 7.16.2 > installation11.png

Install & Run Elasticsearch

Install and configure Elasticsearch on a single node

On Windows

On Linux

Install Elasticsearch using the .tar.gz file

Install Elasticsearch using the .rmp file

Configure an Elasticsearch cluster (3 nodes)

On Windows

On Linux

Enable TLS 1.2 and 1.3 versions for Elasticsearch

Enable Elasticsearch Authentication

Connect Zephyr to Elasticsearch

See Also