Skip to main content
Version: 5.1

Installing SA Web

Conventions:

  • SAF_INSTALLER - the directory where the SA Web installation package is unpacked
Note!

For SA Web to function correctly, you need to specify the entire list of nodes in the SA Data Storage cluster and the installed SA Engine. If you have a separation into hot and cold storage types, it is sufficient to specify the hot nodes.

General Information​

Unpack the installation package into a directory, for example, /app/distr and specify the unpacked directory as a variable:

tar xzf saf-installer-*.tar.gz -C /app/distr/
SAF_INSTALLER=/app/distr/saf_5.1/

SA Web is based on OpenSearch-Dashboards, so the article will sometimes use this as an alternative name.

Run the SA Web installer as the root user, specifying the path to it:

${SAF_INSTALLER}/opensearch-dashboards/install.sh

You can run the installation script as the opensearch user with limited privileges (in rootless mode). However, some commands must be executed before and after running the script by a user with elevated privileges.
To start the installation without elevated privileges, use the following command:

sudo -u opensearch ${SAF_INSTALLER}/opensearch-dashboards/install.sh
warning

A full update cannot be completed without root privileges. Some operations must be performed by a user with elevated rights. The installer will display a list of required operations at the appropriate step. If these commands are not executed before updating, data loss may occur.

We recommend using a separate server for installing SA Web. The default owner for SA Web directories is opensearch and the group is opensearch.

The installer supports the following parameters:

  • -c, --config <path_to_config_file_yaml> - use a configuration file for installation
  • -h, --help - display help

The installer supports the use of a configuration file; all parameters in the file correspond to the questions and parameters during manual installation.

Example configuration file ${SAF_INSTALLER}/opensearch-dashboards/example_config_dashboards.yaml
OpensearchDashboards:
  openSearchDashboardsLocation:
    # Use already existing directories if found (if not will use default dirs)
    USE_PREVIOUS_OSD_PATHS: n
    # User for install
    KBN_USER: opensearch
    # Group for install
    KBN_GROUP: opensearch
    # Home path to install directory
    KBN_PATH_HOME: "/app/opensearch-dashboards"
    # Directory OpenSearch Dashboards configuration
    KBN_PATH_CONFIG: "/app/opensearch-dashboards/config"
    # Directory OpenSearch Dashboards data storage
    KBN_PATH_DATA: "/app/data/opensearch-dashboards"
    # Directory OpenSearch Dashboards logs storage
    KBN_PATH_LOGS: "/app/logs/opensearch-dashboards"
  baseOpenSearchDashboardsParameters:
    # Name of the current node
    NODE_NAME: saf-osd
    # Servers with roles master
    ES_HOST_LIST: https://127.0.0.1:9200
    # Using existing certificates and keys
    USE_EXISTING_CERTS: y
    # Using existing CA certificate and private key to generate node certificate and private key
    EXISTING_CA_CERT: y
    # Path to CA cert
    CA_CERT_PATH: "/app/opensearch/config/ca-cert.pem"
    # Path to CA key
    CA_KEY_PATH: "/app/opensearch/config/ca-key.pem"
    # Path to existing node certificate
    EXISTING_NODE_CERT: "./certs/node-cert.pem"
    # Path to existing node private key
    EXISTING_NODE_PRKEY: "./certs/node-key.pem"
    # CN for node certificate
    CERT_NODE_NAME: saf-osd
    # Country code
    CERT_COUNTRY: AE
    # Region
    CERT_STATE: Dubai
    # City
    CERT_CITY: Dubai
    # Name organization
    CERT_ORG: SAF Test Org
    # IP to connect current node
    CERT_NODE_IP: 127.0.0.1
  installationProceed:
    # Kill processes of kibana and opensearch dashboards if they started
    kill_current_instance: "y"
    # Clear existed folders
    clear_existed_folders: "y"
    # Making changes to the operating system
    continue_installation: "y"

In the configuration file, all parameters are configured to install SA Web on the same server alongside a single SA Data Storage node and SA Master Node.

Installing the Main Directories​

The installer checks for running OpenSearch-Dashboards, if found, asks whether to continue the installation.

================================================================================
SEARCH ANYWHERE FRAMEWORK INSTALL SCRIPT - OPENSEARCH DASHBOARDS
================================================================================

Current working directory: /app/distr/saf_5.1/opensearch-dashboards

Current name of install's archive: opensearch-dashboards-2.18.0-linux-x64.tar.gz

Current version OpenSearch-Dashboards: 2.18.0

================================================================================
-- STEP 1. INSTALLATION DIRECTORIES


!!! You have running instance of OpenSearch-Dashboards. Installer support only one running instance per node.
Do you want to continue? [y/N]:

The script also displays the detected installation archive and the version of OpenSearch-Dashboards to be installed. By default, the installation will be cancelled unless you enter y to continue. If you proceed with the installation, the currently running service will be stopped.

In the first step, the main installation directories are specified. We recommend storing all files related to SAF in a single directory /app; this will simplify maintenance later.

If you are performing a test installation and plan to install all SAF components on one server, you must specify separate directories for each component. You need to enter the following directories:

  • Home directory — the installation directory for SA Web
  • Conf directory — the location of the configuration files
  • Data directory — the directory for storing various files used during the operation of SA Web
  • Logs directory — the directory for storing logs
-- STEP 1. INSTALLATION DIRECTORIES

Opensearch Dashboards home directory [/app/opensearch-dashboards]:
Opensearch Dashboards conf directory [/app/opensearch-dashboards/config]:
Opensearch Dashboards data directory [/app/data/opensearch-dashboards]: /app/data/opensearch-dashboards/
Opensearch Dashboards logs directory [/app/logs/opensearch-dashboards]: /app/logs/opensearch-dashboards/

Final Opensearch Dashboards home directory: /app/opensearch-dashboards
Final Opensearch Dashboards conf directory: /app/opensearch-dashboards/config
Final Opensearch Dashboards data directory: /app/data/opensearch-dashboards/
Final Opensearch Dashboards logs directory: /app/logs/opensearch-dashboards/
Is this correct? [y/n]:

After entering, confirm the correctness of the data. The installer will analyze the existing directories, and if they are not empty, it will issue a warning again:

!!! You've chosen non-empty directories. All files will be deleted.
Do you want to continue? [y/N]:
danger

If you continue, all contents of the specified directories will be deleted without the possibility of recovery!

To continue the installation, you need to enter y again and press Enter.

Rootless Installation​

At this stage, you can disable the use of commands that require elevated root privileges by selecting the rootless mode.

-- STEP 2. DISABLE OPERATIONS WHERE ROOT RIGHTS ARE REQUIRED

Want to install SEARCH ANYWHERE FRAMEWORK without root privileges? [y/N]:

To proceed with the installation in rootless mode, type y and press Enter. If you prefer to continue installation as the root user, type n or simply press Enter.

Linux username for SEARCH ANYWHERE FRAMEWORK [opensearch]:
Linux groupname for SEARCH ANYWHERE FRAMEWORK [opensearch]:

Final SEARCH ANYWHERE FRAMEWORK username: opensearch
Final SEARCH ANYWHERE FRAMEWORK groupname: opensearch
Is this correct? [Y/n]:

Next, provide the system (Linux) user and group under which the SA Web service will run. By default, these are set to opensearch. Press Enter to keep the default values.

After that, confirm the selected user and group by pressing Enter.

If rootless mode is selected, you will see a message listing the required preparatory commands. These must be executed by a user with elevated privileges (e.g., root):

 ATTENTION!
Before installing SEARCH ANYWHERE FRAMEWORK, you must run the following commands as a user with root privileges.
Change user, group and directories as needed

/bin/dnf install zip unzip openssl curl
systemctl stop opensearch-dashboards
groupadd --system opensearch
useradd --system --no-create-home -g opensearch opensearch
mkdir -p /app/opensearch-dashboards
mkdir -p /app/opensearch-dashboards/config
mkdir -p /app/data/opensearch-dashboards
mkdir -p /app/logs/opensearch-dashboards
chown -R opensearch:opensearch /app/opensearch-dashboards /app/opensearch-dashboards/config /app/data/opensearch-dashboards /app/logs/opensearch-dashboards /app/distr/saf_5.1/opensearch-dashboards

!!! Are you sure you have done everything from the list above? [y/N]:

If you've completed all the necessary steps for installation, type y and press Enter. If you still need to perform some tasks or want to cancel the installation, just press Enter.

The installer includes several checks. If any issues are found, the script will stop automatically and display a message:

You need to chown all directories, login as opensearch and run the script again.

Setting Server Parameters​

In this step, the basic parameters of SA Web are entered:

  • Node name — the name of the current SA Web server
  • Bind address — the interface that SA Web will listen on. By default, all available network interfaces are listened to. You can specify multiple IP addresses
  • OpenSearch host list — one or more addresses for connecting to OpenSearch nodes with the data role, listed in quotes and separated by commas. The address must include the https protocol and the port number for connection
-- STEP 3. BASE OPENSEARCH DASHBOARDS PARAMETERS

Node name [saf-node-00]:
Bind address [0.0.0.0]:
Opensearch host list ["https://localhost:9200"]:

Final node name: saf-node-00
Final bind address: "0.0.0.0"
Final Opensearch host list: [ "https://localhost:9200" ]
Is this correct? [y/n]:

After entering, you need to confirm the correctness of the data.

Setting Certificate Parameters​

Note!

When creating the private key, the RSA cryptographic algorithm with a length of 2048 bits is used, and the SHA-256 algorithm is used to create the digital fingerprint. The administrator and current server certificates are created for 1095 days.

This step configures the key and certificate parameters for the current server. If a self-signed CA certificate was used when installing the first OpenSearch node, it must be copied to the current server to sign the node certificate with the same CA. There is an option to use your own certificates.

  • Do you want to use your existing certificates and keys? — Do you want to use existing certificate and key files? You can specify your own files or use the built-in algorithm
  • Do you want to use an existing CA certificate and private key to generate certificates and keys for this node? — If you choose N, you will need to manually provide all the necessary certificates for the node to work. Otherwise, by choosing Y, the remaining certificates will be automatically generated based on the CA certificate and key
  • Path to CA certificate — Path to the root certificate. The certificate must be the same on all SAF components
  • Path to CA key — Path to the private key. The key must be the same on all SAF components
  • CN for node certificate — Common name for the current server
  • Country for node certificate — Country name for the current server
  • State for node certificate — State/region name for the current server
  • Locality for node certificate — City name for the current server
  • Organization for node certificate — Organization name for the current server
  • External IP — The external IP address of the current server, which will be used to interact with other components. The script will automatically collect external addresses on the current server and offer them as the default value

Below is an example specifying an existing CA private key and certificate:

-- STEP 4. OPENSEARCH SECURITY SSL/TLS SETTINGS

Do you want to use your existing certificates and keys? [Y/n]: y
Do you want to use an existing CA certificate and private key to generate certificates and keys for this node? [Y/n] y
Path to CA certificate [./certs/ca-cert.pem]: /app/opensearch/config/ca-cert.pem
Path to CA key [./certs/ca-key.pem]: /app/opensearch/config/ca-key.pem
CN for node certificate [saf-node-00]:
Country for node certificate [UAE]:
State for node certificate [Dubai]:
Locality (city) for node certificate [Dubai]:
Organization for node certificate [SAF Test Org]:
External IP for alt_names extension [172.16.0.27]:
Final path to CA certificate: /app/opensearch/config/ca-cert.pem
Final path to CA key: /app/opensearch/config/ca-key.pem
Final CN for node certificate: saf-node-00
Final country for node certificate: UAE
Final state for node certificate: Dubai
Final locality (city) for node certificate: Dubai
Final organization for node certificate: SAF Test Org
External IP for alt_names extension: 172.16.0.27
Is this correct? [y/n]:

Generating Configuration Files​

No action is required from the administrator at this stage. This stage is conditionally divided into two parts:

  • Preparing temporary directories, performing checks, preparing templates
  • Generating configuration files from the specified parameters

Creating Certificates​

No action is required from the administrator at this stage. The private key and certificate of the current server are created from the specified parameters.

Unpacking the Archive and Modifying Configuration Files​

No action is required from the administrator at this stage. The archive containing OpenSearch Dashboards is unpacked, the configuration files extracted from the archive are modified, and preparatory processes are carried out before system changes.

Starting Changes to the OS​

All operations up to this point are performed strictly within the installer directory and do not affect the OS. You can view the set of files ready for installation in the staging directory. For this, the administrator will be asked for permission to continue the installation:

!!! AT THIS POINT WE START TO MAKE CHANGES IN OPERATING SYSTEM !!!
Do you want to continue? [y/N]:

Confirm the changes to continue the installation by pressing y and then Enter.

Installation​

No action is required from the administrator at this stage. Several actions take place here:

  • Creating groups and users
  • Creating directories
  • Installing OpenSearch Dashboards
  • Making changes to the visual design
  • Installing plugins
  • Changing file and directory ownership and setting SELinux rules
Note!

If the rootless installation mode was selected, some operations will not be performed.

Starting the Service and Enabling the New Interface​

No action is required from the administrator at this stage.

Note!

This step will be skipped if the installation was performed in rootless mode.

Completing the Installation​

If the rootless installation mode was selected, the following message will be displayed:

 ATTENTION!
After installing SEARCH ANYWHERE FRAMEWORK, you must run the following commands as a user with root privileges.
Change user, group and directories as needed.

cp /opt/saf_5.1/opensearch-dashboards/staging/services/opensearch-dashboards.service /etc/systemd/system/
chown root:root /etc/systemd/system/opensearch-dashboards.service
chcon -Rv -u system_u -r object_r -t bin_t /app/opensearch-dashboards/bin
chown -R opensearch:opensearch /app/opensearch-dashboards /app/opensearch-dashboards/config /app/data/opensearch-dashboards /app/logs/opensearch-dashboards
systemctl daemon-reload
systemctl enable opensearch-dashboards
systemctl start opensearch-dashboards
systemctl status opensearch-dashboards

These commands must be executed by a user with elevated (root) privileges.

Upon completion of the installation, a firewall configuration message should appear using firewalld and ufw as examples, as well as a successful installation message, as shown in the image below. Any other type of installation completion indicates an error, and additional corrective actions are required.

================================================================================
-- Additional firewall configuration example (if needed)
-- For RHEL/CentOS with firewalld
    firewall-cmd --permanent --zone=public --add-port=5601/tcp
    firewall-cmd --reload
-- For AstraLinux/Debian with ufw
    ufw allow 5601/tcp
================================================================================

================================================================================
-- SEARCH ANYWHERE FRAMEWORK SUCCESSFULLY INSTALLED!
================================================================================

Upon successful completion of the installer, the node is deployed and ready for use. The systemd service opensearch-dashboards.service should be running on it. The service will start automatically after the OS restarts.

Note that you need to configure the firewall for port 5601/tcp – the port for accessing SA Web. To check functionality, open the page https://<your-server-ip-address>:5601 in your browser and use the credentials you specified during OpenSearch installation.

Example of the page output: Example of the page output