Installing and Configuring HERO

Checking system prerequisites

Before starting to install HERO, you must check the following system prerequisites:

Verify that Docker and Docker Compose are installed, configured, and ready to use. For the required version, see System Requirements.

If you don't have Docker and Docker Compose already installed, see Installing Docker and Docker Compose.

HERO requires some values to be set for ulimit parameter, for Linux OS. See: How to verify and set ulimit parameter.
Verify the available virtual memory. See: How to verify and set the available virtual memory.
If you are installing HERO on RHEL or CentOS distros, SELinux must be set to Permissive or Disabled. See: How to set SELinux to permissive.
Verify that the Workload Automation user entitled to discover servers in HERO has access to the crontab command.

Installation procedure

To install and configure HERO, run the following procedure.

From HCL License Portal download the appropriate HERO installation package.
Extract the content of the tar.gz file into <BUILD_DIR>, a directory of your choice. Use one of the extraction tools available on your system or downloadable from the Internet. The tool you use must be able to keep the file permissions on the extracted files.
If you want to enable IPv6 connectivity in Docker containers, you must properly set the subnet values (gateway and ipv6_address) in the <BUILD_DIR>/devops/templates/ipv6/docker-compose.yml file. For details, see Docker documentation.
HERO server uses Tomcat standard time zone (UTC). If the monitored servers use a different time zone, this might impact HERO monitoring activities. To set up a different time zone in HERO, before starting with the installation, you must edit the <BUILD_DIR>/docker-compose.yml file in the following way:
- At the end of the following line:
  
  - CATALINA_OPTS=-Xmx4g -Xms4g -Dnashorn.args=--no-deprecation-warning
  
  add the following parameter:
  
  -Duser.timezone=selected_time_zone
  
  Configuration example for GMT time zone:
  
  - CATALINA_OPTS=-Xmx4g -Xms4g -Dnashorn.args=--no-deprecation-warning - Duser.timezone=GMT
  
  Note:
  
  Make sure you do not change file indentation.
  
  For the list of supported time zones in Tomcat, see the section Available Time Zones in the Java documentation.

To install HERO on Windows operating system, user must have administrator permissions. To install HERO on Linux operating system, user must have read and write permissions for the <BUILD_DIR> directory. The user must have execute permissions for Docker commands. This means that the user must be a member of sudoers group or Docker group. If the user is a member of sudoers group but not of Docker group, the installation script must be run with sudo. Also, in order for Docker containers to access HERO configuration files, all sub-folders and files in the <BUILD_DIR>/EXT directory must have permission set to 775 .
For Windows, open a PowerShell console. For Linux, open a Bash shell.
From the <BUILD_DIR> directory, start the installation command. By default, HERO installation will start offline. To install HERO online, run the command with "-o" flag:
- For Linux, issue the command: ./installHERO.sh
  
  To get the command help, type: ./installHERO.sh --help
- For RHEL machines, issue the command: ./installHERO-Podman.sh
- For Windows, issue the command: .\installHERO.ps1
  To get the command help, type: Get-help .\installHERO.ps1

You can supply the required parameters within the command, otherwise default values will be taken.

Parameters you can specify are:
- For Linux: ./installHERO.sh -h <current hostname> -p < current port > -d < current deploy path >
- For RHEL machines: ./installHERO-Podman.sh -h <current hostname> -p < current port > -d < current deploy path >
- For Windows: .\installHERO.ps1 -HOSTNAME <current hostname> -port <current port> -deployPath <current deploy path>
Where:
- hostname - the host name of the machine where you are installing HERO. It must be reachable from any server where you want to deploy the monitoring scripts. This parameter is mandatory. If you are installing HERO on a SELinux machine such as RHEL or CentOS, set the hostname to the Fully Qualified Domain Name of the machine. To identify it, run the command hostname --fqdn.
- port - the https port of the HERO server. This parameter is optional (default value is 443).
- deployPath - the directory on the target server in which the monitoring scripts must be deployed. This directory cannot contain blanks. This parameter is optional (default value is <$HOST_NAME/%RETRIEVED_IP_MACHINE%> ).
The HCL Master License Agreement (MLA) is displayed by the installation script for your acceptance. Scroll down or press the "q" key to quit. Type "Y" to accept the MLA.
The installation script runs the installation process and verifies its successful completion.

Post installation steps

When the installation is complete, the following link is prompted to login to the HERO dashboard: https://<your_host_machine_address:port>/Dashboard

The installation script generates two HERO users:

userid test, password test, with user role
userid admin, password admin, with administrator role

Note:

At login time, if you enter wrong credentials, after 5 unsuccessful attemps you will be locked out for 30 minutes.

Use the Keycloak administration console to define new users, new roles, or change default passwords. You can access Keycloak administration console at the following link: https://<IP:PORT>/keycloak/auth/admin by using the following credentials:

userid=admin
password=password

If you want, you can change Keycloak default password. For instructions, see Configuring Security.

Before adding environments to the HERO dashboard, verify that the installation process has created OpenSearch Dashboards default index pattern:

In the environment page, check if the KPI link appears on top of the server card.
If the link doesn't show up, manually set the OpenSearch Dashboards default index pattern by following the procedure in the Appendix.

To stop HERO (for example, after changing some configuration parameters), from the <BUILD_DIR> directory, type docker-compose stop.

To restart HERO, from the <BUILD_DIR> directory, type docker-compose start.

For any reference, you can find the manual installation procedure in the Appendix. It guides you to manually execute the steps run by the automatic installation script.

Managing containers

To manage HERO containers, run the following procedures from the <BUILD_DIR> directory.

To gracefully stop/restart HERO, for example after reconfiguring HERO, run the following commands:
1. docker-compose stop
2. docker-compose start

To reset the containers, while maintaining HERO configuration and data stored in the DB, run the following procedure:
1. docker-compose down
2. docker-compose up --build -d

This procedure doesn't reset the custom client secret if you have created one (see Configuring Security).

To reset the containers and the HERO configuration, while maintaining the data stored in the DB, run the following procedure:
1. docker-compose down
2. docker volume rm <BUILD_DIR>_hero-home
3. docker-compose up --build -d

This procedure doesn't reset the custom client secret if you have created one (see Configuring Security).

To reset the containers, the HERO configuration, and the data stored in the DB, run the following procedure:
1. docker-compose down
2. docker volume rm <BUILD_DIR>_hero-home <BUILD_DIR>_ build_hero-db-data <BUILD_DIR>_ build_hero-es-data <BUILD_DIR>_ build_keycloak-nginx-ssl <BUILD_DIR>_ build_pgdata
3. docker-compose up --build -d

This procedure resets also the custom client secret if you have created one (see Configuring Security). Reconfigure HERO with the default client secret or create a new one.

In addition, to delete also HERO images, run the following command:

docker rmi <BUILD_DIR>] _tomcat <BUILD_DIR>_prediction <BUILD_DIR>_keycloak <BUILD_DIR>_nginx <BUILD_DIR>_kibana docker.elastic.co/kibana/kibana-oss docker.elastic.co/elasticsearch/elasticsearch-oss

This command completely uninstall HERO.

Applying changes to Runbooks and Monitors

Every time a runbook is added, or a new monitor is created, run the following commands from the <BUILD_DIR> directory:

docker stop hero-tomcat
docker rm hero-tomcat
docker volume rm <BUILD_DIR>_hero-home (to remove the configuration volume)
docker-compose up --build -d

Configuration Files

The dashboard.properties file contains general configuration parameters:

disk-space	Minimum percentage for the disk space monitor to generate an alert.
IPdashboard	The URL of the HERO server used by the monitoring scripts.
IPdashboard_curl_options	The options used by the CURL command run by the monitoring scripts. Used for authentication purposes on the HERO server.
elasticsearch_external	The historical database (OpenSearch) URL to be used by the monitoring scripts running on the workstation.
elasticsearch_curl_options	The options for the CURL command run by the KPI scripts. Used for authentication purposes on OpenSearch.
Queue_< queue name >_limit	Warning that notifies when the queue availability is lower than the limit that you set. Supported only for Workload Automation.
esClientLink	The link used by the HERO server to reach the Historical Database (OpenSearch).
kibanaLink	Link to OpenSearch Dashboards.
scheduledTime	The frequency of the scheduling operations for HERO monitors.
esQueueMapping	Template for creating the index on OpenSearch.
esQueueDashboardTemplate	Template for creating the queue dashboard.
esQueueChartVisualizationTemplate	Template for creating the chart visualization for the queue.
esQueueGaugeVisualizationTemplate	Template for creating the Gauge visualization for the chart in the dashboard.
esQueuePanelJSONTemplate	Template for creating the Queue panel.
esThroughputMapping	Template for creating the OpenSearch index for throughput.
esThroughputChartVisualizationTemplate	Template for the throughput visualization for the chart in the dashboard.
esThroughputPanelJSONTemplate	Template for creating the throughput panel.
LaunchInContextUrl	The url of the HERO UI that will be used in the alert emails.
tempPath	The path on the HERO Server where the monitor files will be stored before deploying.
runbookLimit	Maximum number of visualized runbooks.
alertSmtpEmail	Optional if you want to configure alerting by email. The sender email account [Example: username@gmail.com].
alertSmtpPassword	Optional if you want to configure alerting by email. The password associated to the sender email account.
smtpPasswordEncrypted	Optional if you want to configure alerting by email. Set encryption for the alertSmtpPassword. Can be "true" or "false". If smtp is configured through HERO installation script, the value of smtpPasswordEncrypted parameter is set to "true" (default value). If you configure smtp manually, you must set smtpPasswordEncrypted to "false".
alertSmtpServer	Optional if you want to configure alerting by email. Fully qualified hostname of the SMTP Server that will be used by HERO to send alerts by email [Example: smtp.gmail.com].
alertSmtpPort	Optional if you want to configure alerting by email. The port of the SMTP mail server.
smtpTlsEnabled	Optional if you want to configure alerting by email. Set the TLS enablement for smtp client while establishing a connection from HERO. Can be "true" or "false". Default value is "true".
sslTrustStorePassword	Optional if you are using a custom SSL truststore file for your JDBC connection, you are required to provide an SSLtruststore password.
maxLogsShown	Maximum number of visualized logs.
pwdNeedsEncryption	Require that alertSmtpPassword must be encrypted on the first execution of SMTP application.
taskSchedulerThreadPoolSize	Max number of threads for scheduled monitors.
predictionIndexMapping	Template to create the prediction index on OpenSearch.
deployPath	Home directory in which monitoring scripts are deployed.

The ui.properties file configures the connection to the HERO web application services:

ip	The hostname or IP address of the HERO server.
port	The port of the HERO server. Default value is 443.
kibanaHost	The hostname of the dashboarding service (OpenSearch Dashboards) that is reachable by the browser.
kibanaPort	The port of the dashboarding service (OpenSearch Dashboards) that is reachable by the browser.
protocol	The protocol to be used (http or https).
wsProtocol	The protocol used for the shell inside HERO, this protocol should be ws if the protocol property is http, otherwise this should be wss.
sshPort	The ssh port for the connection to other machines (usually 22).
keycloak	Used to configure the connection to Keycloak. Set this variable to the same value at which you set the Keycloak_URL parameter in the .tomcat.env file. For details, see Configuring Security.
roles	Available roles in the HERO Keycloak security configuration, separated by comma.
clientSecret	Used to configure HERO with a new secret in place of the default one. For details, see Configuring Security.

If a re-configuration is done on dynamic files, such as dashboard.properties or ui.properties, restart docker-compose by running the following commands:

docker-compose stop
docker-compose start