1. Introduction¶

This manual describes the installation procedures for the Elastic Stack (ELK).

2. Install Preparations¶

This section covers the essential steps required for the installation.

Attention

All steps must be performed with root privileges unless stated otherwise.

To install ELK you will need:

Root permission on the server
GBDS installed on the server
SmartSenseObjects<date>.json file

Note

If you do not have the file, contact the Griaule Support Team at support@griaule.com.

Then, follow the steps presented below.

Login to the server as root.
Prepare the Repository.
Install and Configure Elasticsearch.
Install and Configure Kibana.
Install and Configure Logstash.
Configure ELK with SmartSense.

3. Prepare the Repository¶

To install ELK, you must first add the repository to the server.

To do so, import the GPG key:

rpm --import https://artifacts.elastic.co/GPG-KEY-elasticsearch

Create the repository file:

vi /etc/yum.repos.d/elasticsearch.repo

Add the following content to the file and save it:

[elasticsearch-6.x]
name=Elasticsearch repository for 6.x packages
baseurl=https://artifacts.elastic.co/packages/6.x/yum
gpgcheck=1
gpgkey=https://artifacts.elastic.co/GPG-KEY-elasticsearch
enabled=1
autorefresh=1
type=rpm-md

Then, update the cache of the packages manager. Start by cleaning the cache:

yum clean all

Finally, rebuild the package cache:

yum makecache

4. Installing ELK¶

4.1. Installing and Configuring Elasticsearch¶

Install the Elasticsearch package:

yum install elasticsearch -y

Then, open the Elasticsearch configuration file:

vi /etc/elasticsearch/elasticsearch.yml

In the Network section, look for the line that starts with #network.host:. Uncomment it and change its value to:

Note

Make sure to replace <host-ip> with the IP address of the server.

network.host: <host-ip>
              ^^^^^^^^^

Then, start the Elasticsearch service:

systemctl start elasticsearch

And enable the Elasticsearch service to start automatically on boot:

systemctl enable elasticsearch

Finally, check if the Elasticsearch service is running:

Note

Make sure to replace <host-ip> with the IP address of the server.

curl -X GET "<host-ip>:9200"
             ^^^^^^^^^

The output should be similar to:

{
  "name" : "QDexH8a",
  "cluster_name" : "elasticsearch",
  "cluster_uuid" : "gAAIqERvS_msO7Y1_759Ja",
  "version" : {
    "number" : "6.8.23",
    "build_flavor" : "default",
    "build_type" : "rpm",
    "build_hash" : "4f67856",
    "build_date" : "2022-01-06T21:30:50.087716Z",
    "build_snapshot" : false,
    "lucene_version" : "7.7.3",
    "minimum_wire_compatibility_version" : "5.6.0",
    "minimum_index_compatibility_version" : "5.0.0"
  },
  "tagline" : "You Know, for Search"
}

4.2. Installing and Configuring Kibana¶

Install the Kibana package:

yum install kibana -y

Then, open the Kibana configuration file:

vi /etc/kibana/kibana.yml

Look for the line that starts with #server.host:. Uncomment it and change its value to:

Note

Make sure to replace <hostname> with the hostname of the server. Keep the double quotes.

server.host: "<hostname>"
              ^^^^^^^^^^

Next, look for the line that starts with #elasticsearch.hosts:. Uncomment it and change its value to:

Note

Make sure to replace <elasticsearch-host-ip> with the IP address configured on Elasticsearch. Keep the double quotes.

elasticsearch.hosts: ["http://<elasticsearch-host-ip>:9200"]
                              ^^^^^^^^^^^^^^^^^^^^^^^

Then, start the Kibana service:

systemctl start kibana

Next, install and configure Nginx.

4.2.1. Installing and Configuring Nginx¶

Install the Nginx package:

yum install nginx -y

Next, create a file that will contain the authentication credentials for Kibana. To do so, run the following command and enter the desired password when prompted:

echo "kibanaadmin:`openssl passwd -apr1`" | tee -a /etc/nginx/htpasswd.users

Then, create a new configuration file for Nginx:

Note

Make sure to replace <hostname> with the hostname of the server.

vi /etc/nginx/conf.d/<hostname>_kibana.conf
                     ^^^^^^^^^^

Add the following content to the file, making the appropriate changes in server_name and proxy_pass:

Note

Make sure to replace <host-ip> with the IP address of the server and <kibana-host-ip> with the IP address of the server where Kibana is installed.

Warning

Below, the lines containing “^^^^^^^^^” are only present to highlight the changes that must be made. Remove them before saving the file.

server {
    listen 80;

    server_name <host-ip>;
                ^^^^^^^^^

    auth_basic "Restricted Access";
    auth_basic_user_file /etc/nginx/htpasswd.users;

    location / {
        proxy_pass http://<kibana-host-ip>:5601;
                          ^^^^^^^^^^^^^^^^
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrad;
    }
}

Test the Nginx configuration file:

nginx -t

Then, restart the Nginx service:

systemctl restart nginx

If necessary, configure the connection in the SE:

setsebool httpd_can_network_connect 1 -P

Finally, check if the Kibana service is running, by accessing the following URL in a browser:

Note

Make sure to replace <host-ip> with the IP address of the server.

http://<host-ip>/status
       ^^^^^^^^^

Tip

The username is kibanaadmin and the password is the one created above.

4.3. Installing and Configuring Logstash¶

Install the Logstash package:

yum install logstash -y

Next, install the MySQL Connector/J package:

yum install mysql-connector-java -y

Then, create a new configuration file for Logstash:

vi /etc/logstash/conf.d/smartsense.conf

Add the following content to the file, making the appropriate changes in jdbc_connection_string, jdbc_user, jdbc_password, and hosts:

Note

Make sure to replace <database-ip>, <database-username>, <database-password>, and <elasticsearch-host-ip> with the appropriate values. Keep the double quotes.

Warning

Below, the lines containing “^^^^^^^^^” are only present to highlight the changes that must be made. Remove them before saving the file.

input {
    jdbc {
        jdbc_driver_library => "/usr/share/java/mysql-connector-java.jar"
        jdbc_driver_class => "com.mysql.jdbc.Driver"
        jdbc_connection_string => "jdbc:mysql://<database-ip>:3306/"
                                                ^^^^^^^^^^^^^
        jdbc_user => "<database-username>"
                      ^^^^^^^^^^^^^^^^^^^
        jdbc_password => "<database-password>"
                          ^^^^^^^^^^^^^^^^^^^
        jdbc_validate_connection => true
        tracking_column => "id"
        use_column_value => true
        statement => "SELECT * FROM smartsense.load_balancing_count where id >    :sql_last_value;"
        schedule => "*/2 * * * *"
        clean_run => false
    }
}
output {
    elasticsearch {
        hosts => ["<elasticsearch-host-ip>:9200"]
                   ^^^^^^^^^^^^^^^^^^^^^^^
        index => "smart_sense_index_pattern"
        document_type => "data"
    }
    stdout {
        codec => rubydebug
    }
}

Next, the systemd file for Logstash needs to be modified to ensure it initializes using the previously created configuration file. To do so, open the file:

vi /etc/systemd/system/logstash.service

Look for the line that starts with ExecStart=. Change its value from:

ExecStart=/usr/share/logstash/bin/logstash "--path.settings" "/etc/logstash"

To:

ExecStart=/usr/share/logstash/bin/logstash "--path.settings" "/etc/logstash" "-f" "/etc/logstash/conf.d/smartsense.conf"

Then, apply changes by reloading the systemd manager configuration:

systemctl daemon-reload

Important

If installing in a new server that has an empty database, insert a dummy value in the smartsense.load_balancing_count table to avoid errors. To do so, run the following command and enter the database password:

Note

Make sure to replace <database-username> and <mysql-database-ip> with the appropriate values.

#        vvvvvvvvvvvvvvvvvvv       vvvvvvvvvvvvvvvvvvv
mysql -u <database-username> -p -h <mysql-database-ip> \
      -e "USE smartsense; INSERT INTO load_balancing_count (id, hostname, load_time, api_id, transaction_type, latent, ul, load_count, extraction_time_avg, extraction_quality_avg, match_avg, total_avg, extraction_time_min, extraction_quality_min, match_min, total_min, extraction_time_max, extraction_quality_max, match_max, total_max) VALUES (1, 'hostname', '2023-08-31 21:25:40', '8829E30D-4994-4D09-99AF-B6F818473928', 'IDENTIFY', 'false', 'false', 1, '541.0', '0.0', '48.0', '599.0', '541', '0', '48', '599', '541', '0', '48', '599');"

Next, start the Logstash service:

systemctl start logstash

And follow the log:

tail -f /var/log/logstash/logstash-plain.log

Error

If an error occurs indicating that Logstash cannot write to the directory /var/lib/logstash/{folder}, execute the following command:

chown -R logstash:logstash /var/lib/logstash

Finally, to check if Logstash created the index in Elasticsearch, run the following command:

Note

Make sure to replace <elasticsearch-host-ip> with the IP address of the server where Elasticsearch is installed.

curl -X GET "<elasticsearch-host-ip>:9200/_cat/indices?v"
             ^^^^^^^^^^^^^^^^^^^^^^^

The output should be similar to:

health status index                     uuid                   pri rep docs.count docs.deleted store.size pri.store.size
yellow open   smart_sense_index_pattern 6Ux_yM25SvG2zWGdGR0HQw   5   1          1            0      6.7kb          6.7kb
green  open   .kibana_1                 BBO89yLnTUC3F7nhqKwf9w   1   0          4            0       18kb           18kb
green  open   .kibana_task_manager      sIMoATiBRsS8bXiVBCscrA   1   0          2            0     12.5kb         12.5kb

5. Configuring ELK with SmartSense¶

5.1. Configuring Kibana¶

5.1.1. Creating the index pattern in Kibana¶

Note

Make sure to replace <kibana-host-ip> with the IP address of the server where Kibana is installed.

In a browser, access: http://<kibana-host-ip>:5601. Then, on the sidebar, click on Management and then, under the Kibana section, click on Index Patterns.

Or access the following URL:

http://<kibana-host-ip>:5601/app/kibana#/management/kibana/indices
       ^^^^^^^^^^^^^^^^

Then, click on the Create index pattern button.

In the Step 1 of 2, in the Index pattern field, enter smart_sense_index_pattern.

If all steps were performed correctly up to this point, the message “Success! Your index pattern matches 1 index” will appear and the Next step button will be enabled, click on it.

Then, in the Step 2 of 2, in the Time Filter field name dropdown menu, select @timestamp.

Finally, click on the Create index pattern button.

You will be redirected to the newly created index pattern page. The URL of this page contains the GUID of the index pattern. Copy it, as it will be used later.

For example, for the URL:

http://<kibana-host-ip>:5601/app/kibana#/management/kibana/indices/ee2d28f0-0e9f-11ee-b23a-15805fde7b38?_g=()&_a=(tab:indexedFields)
                                                                   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The GUID that should be copied is ee2d28f0-0e9f-11ee-b23a-15805fde7b38.

5.1.2. Editing the SmartSense Kibana Objects JSON file¶

Open the supplied SmartSense Kibana Objects JSON file.

Look for the GUID 4a141e90-4fb9-11ed-bd96-63c5b972c3f4.

On all occurrences, replace the current GUID with the GUID of the index pattern created above.

For example, if the copied GUID is ee2d28f0-0e9f-11ee-b23a-15805fde7b38, replace:

4a141e90-4fb9-11ed-bd96-63c5b972c3f4

with:

ee2d28f0-0e9f-11ee-b23a-15805fde7b38

Save and close the JSON file.

5.1.3. Importing the SmartSense Kibana Objects JSON file¶

Note

Make sure to replace <kibana-host-ip> with the IP address of the server where Kibana is installed.

In a browser, access: http://<kibana-host-ip>:5601. Then, on the sidebar, click on Management and then, under the Kibana section, click on Saved Objects.

Or access the following URL:

http://<kibana-host-ip>:5601/app/kibana#/management/kibana/objects
       ^^^^^^^^^^^^^^^^

On the upper-right corner, click on Import.

Then, click on Please select a JSON file to import and select the SmartSense Kibana Objects JSON file, or drag and drop the file on the marked area.

Click on the Import button, located on the lower-right corner.

You should see the message “Import successful. Successfully imported 10 objects.”.

Finally, click on the Done button.

5.2. Configuring the Dashboards on SmartSense¶

Open the the SmartSense configuration file, config.properties, located in the /var/lib/tomcats/smart-sense/conf folder:

vim /var/lib/tomcats/smart-sense/conf/config.properties

Find the # SMARTSENSE - ELK CONFIGURATION section.

For each property (linkEnroll, linkIdentify, linkIdentifyLatent, linkUpdate, linkVerify), replace the pre-configured IP or Hostname with the IP or Hostname of the server where Kibana is installed.

For example, if the IP address of the server where Kibana is installed is 172.16.0.185, replace:

linkEnroll=http://172.16.0.177:5601/app/kibana#/dashboard/c7ba3d80-5148-11ed-bd96-63c5b972c3f4 ...
                  ^^^^^^^^^^^^

with:

linkEnroll=http://172.16.0.185:5601/app/kibana#/dashboard/c7ba3d80-5148-11ed-bd96-63c5b972c3f4 ...
                  ^^^^^^^^^^^^

Save and close the file.

After all steps in the Elastic Stack installation procedure are completed, move back to the SmartSense Server Configuration manual to complete the configuration.