Installing and removing KUMA

This section described the installation of KUMA. KUMA can be installed on one server to get familiar with the program capabilities. KUMA can also be installed in a production environment.

Installing for demo

For demonstration purposes, you can deploy KUMA components on a single server.

The server where the installer is run cannot have the name localhost or localhost.<domain>. The installer can run from any folder, but the RPM packages must be located in the same folder as the kuma-installer file. You can get more information about kuma-installer by running it with the --help parameter.

Before deploying the program, make sure that the servers where you intend to install the components meet the hardware and software requirements.

KUMA components are addressed using the fully qualified domain name (FQDN) of the host. Before you install the program, you must ensure that the command hostnamectl status returns the true name of the host FQDN in the Static hostname field.

It is recommended to use Network Time Protocol (NTP) to synchronize time between servers with KUMA services.

The KUMA installation takes place over several stages:

1. Preparing the source machine

   The source machine is used during the program installation process: the installer files are unpacked and run on it.

2. Preparing the target machine

   The program components are installed on the target machines. The source machine can be used as a target one.

3. Preparing an inventory file for demonstration installation

   Create an inventory file describing the network structure of the program components that the installer can use to deploy KUMA.

4. Installing the program for demonstration purposes

   Install the program and get the URL and login credentials for the web interface.

If necessary, the program installed for demonstration purposes can be distributed to different servers for full-fledged operation.

Preparing an inventory file for demonstration installation

Installation, update, and removal of KUMA components is performed from the folder containing the unpacked installer by using the Ansible tool and the user-created inventory file containing a list of the hosts of KUMA components and other parameters. In the case of a demonstration installation, the host will be the same for all components. The inventory file is in the YAML format.

Before installing KUMA version certified by the state authorities of Russian Federation, the files from both Distribution kit disks must be unpacked into a kuma-ansible-installer folder.

To create an inventory file for a demonstration installation:

1. Go to the KUMA installer folder by executing the following command:

   cd kuma-ansible-installer

2. Create an inventory file by copying the single.inventory.yml.template:

   cp single.inventory.yml.template single.inventory.yml

3. Edit the inventory file parameters:
   • If you want demonstration services to be created during the installation, set the deploy_example_services parameter value to true.

     deploy_example_services: true

     Demonstration services can only be created during the initial installation of KUMA. When updating the system using the same inventory file, no demonstration services will be created.

   • If you are installing KUMA in a production environment and have a separate source machine, set the ansible_connection parameter to ssh:

     ansible_connection: ssh

4. Replace all kuma.example.com lines in the inventory file with the host of the target machine on which you want to install KUMA components.

The inventory file is created. You can install KUMA for demonstration purposes using it.

It is recommended that you not remove the inventory file after installing KUMA:

• If you change this file (for example, add information about a new server for the collector), you can reuse it to update the system with a new component.
• You can use this inventory file to delete KUMA.

Installing the program for demonstration purposes

KUMA is installed using the Ansible tool and the YML inventory file. The installation is performed using the source machine, where all of the KUMA components are installed on the target machines.

Root privileges are required to run the installer.

To install KUMA for demonstration purposes:

1. On the source machine, log in to the OS as the root user and go to the folder with the unpacked installer.
2. Place the file with the license key in the folder <installer folder>/roles/kuma/files/.
3. Launch the installer by executing the following command:

   ./install.sh single.inventory.yml

4. Accept the terms of the End User License Agreement.

   If you do not accept the terms of the End User License Agreement, the program will not be installed.

KUMA components are installed on the target machine. The screen will display the URL of the KUMA web interface and the user name and password that must be used to access the web interface.

By default, the KUMA web interface address is https://kuma.example.com:7220.

Default login credentials (after the first login, you must change the password of the admin account):
- user name—admin
- password—mustB3Ch@ng3d!

It is recommended that you save the inventory file used to install the program. It can be used to add components to the system or remove KUMA.

You can later upgrade the demonstration installation to the full one.

Upgrading the demonstration installation

You can upgrade the demonstration installation by installing the program over the installed KUMA using the distributed.inventory.yml template.

Several steps are required to upgrade the demonstration installation:

1. Installing the program

   Specify the host of the demonstration server and place it in the core group when preparing the inventory file.

2. Deleting the demonstration services

   In the KUMA web interface under Resources → Active services copy the IDs for the existing services and delete them.

   Then delete the services from the machine where they were installed using the command /opt/kaspersky/kuma/kuma <collector/correlator/storage> --id <service ID> --uninstall. Repeat the delete command for each service.

3. Rebuilding services on the right machines

Installing KUMA in production environment

Before deploying the program, make sure that the servers where you intend to install the components meet the hardware and software requirements.

KUMA components are addressed using the fully qualified domain name (FQDN) of the host. Before you install the program, you must ensure that the command hostnamectl status returns the true name of the host FQDN in the Static hostname field.

It is recommended to use Network Time Protocol (NTP) to synchronize time between servers with KUMA services.

The KUMA installation takes place over several stages:

1. Configuring network access

   Make sure all the necessary ports are open to allow KUMA components to interact with each other based on your organization's security structure.

2. Preparing the source machine

   The source machine is used during the program installation process: the installer files are unpacked and run on it.

3. Preparing the target machines

   The program components are installed on the target machines.

4. Preparing the inventory file

   Create an inventory file describing the network structure of the program components that the installer can use to deploy KUMA.

5. Installing the program

   Install the program and get the URL and login credentials for the web interface.

6. Creating services

   Create services in the KUMA web interface and install them on the target machines intended for them.

Configuring network access

For the program to run correctly, you need to ensure that the KUMA components are able to interact with other components and programs over the network via the protocols and ports specified during the installation of the KUMA components. The table below shows the default network ports values.

Network ports used so KUMA components can interact with each other

Preparing the source machine

The source machine is used during the program installation process: the installer files are unpacked and run on it.

To prepare the source machine for the KUMA installation:

1. Install Oracle Linux 8.4 by selecting the Server installation option. A disk image for installation is available on the official Oracle site.
2. Log in to the operating system as the root user.
3. Configure the network interface.

   For convenience, you can use the graphical utility nmtui.

4. Configure the system time to synchronize with the NTP server:
   1. If the machine does not have direct Internet access, edit the /etc/chrony.conf file to replace 2.pool.ntp.org with the name or IP address of your organization's internal NTP server.
   2. Start the system time synchronization service by executing the following command:

      systemctl enable --now chronyd

   3. Wait a few seconds and execute the following command:

      timedatectl | grep 'System clock synchronized'

      If the system time is synchronized correctly, the output will contain the line "System clock synchronized: yes."

5. Generate an SSH key for authentication on the SSH servers of the target machines by executing the following command:

   ssh-keygen -f /root/.ssh/id_rsa -N "" -C kuma-ansible-installer

6. Make sure the source machine has network access to all the target machines by host name and copy the SSH key to each of them by executing the following command:

   ssh-copy-id -i /root/.ssh/id_rsa root@<host name of the source machine>

7. Copy the archive with the KUMA installer to the source machine and unpack it using the following command (about 2 GB of disk space is required):

   tar -xpf kuma-ansible-installer-<version>.tar.gz

   Before installing KUMA version certified by the state authorities of Russian Federation, the files from both Distribution kit disks must be unpacked into a kuma-ansible-installer folder.

The source machine is ready for the KUMA installation.

Preparing the target machine

The program components are installed on the target machines.

To prepare the target machine for the installation of KUMA components:

1. Install Oracle Linux 8.4 by selecting the Server installation option. A disk image for installation is available on the official Oracle site.
2. Log in to the operating system as the root user.
3. Configure the network interface.

   For convenience, you can use the graphical utility nmtui.

4. Configure the system time to synchronize with the NTP server:
   1. If the machine does not have direct Internet access, edit the /etc/chrony.conf file to replace 2.pool.ntp.org with the name or IP address of your organization's internal NTP server.
   2. Start the system time synchronization service by executing the following command:

      systemctl enable --now chronyd

   3. Wait a few seconds and execute the following command:

      timedatectl | grep 'System clock synchronized'

      If the system time is synchronized correctly, the output will contain the line "System clock synchronized: yes."

5. Specify the host name. It is highly recommended to use the FQDN. For example: kuma-1.mydomain.com.

   You should not change the KUMA host name after installation: this will make it impossible to verify the authenticity of certificates and will disrupt the network communication between the program components.

6. Register the target machine in your organization's DNS zone to allow host names to be translated to IP addresses.

   If your organization does not use a DNS server, you can use the /etc/hosts file for name resolution. The content of the files can be automatically generated for each target machine when installing KUMA.

7. Execute the following command and write down the result:

   hostname -f

   You will need this host name when installing KUMA. The source machine must be able to access the target machine using this name.

The target machine is ready for the installation of KUMA components.

The source machine can be used as a target one. To do this, prepare the source machine, and then follow steps 5–7 in the instructions for preparing the target machine.

Preparing the inventory file

The installation, updating, and removal of KUMA components is performed from the folder with the unpacked installer using the Ansible tool and the user-created inventory file with a list of hosts of KUMA components and other parameters. The inventory file is in the YAML format.

Before installing KUMA version certified by the state authorities of Russian Federation, the files from both Distribution kit disks must be unpacked into a kuma-ansible-installer folder.

To create an inventory file:

1. Go to the KUMA installer folder by executing the following command:

   cd kuma-ansible-installer

2. Create an inventory file by copying the distributed.inventory.yml.template:

   cp distributed.inventory.yml.template distributed.inventory.yml

3. Edit the inventory file parameters:
   • If you want demonstration services to be created during the installation, set the deploy_example_services parameter value to true.

     deploy_example_services: true

     Demonstration services can only be created during the initial installation of KUMA. When updating the system using the same inventory file, no demonstration services will be created.

   • If the machines are not registered in your organization's DNS zone, set the generate_etc_hosts parameter to true, and for each machine in the inventory, replace the ip (0.0.0.0) parameter values with the actual IP addresses.

     generate_etc_hosts: true

     When using this parameter, the installer will automatically add the IP addresses of the machines from the inventory file to the /etc/hosts files on the machines where KUMA components are installed.

   • If you are installing KUMA in a production environment and have a separate source machine, set the ansible_connection parameter to ssh:

     ansible_connection: ssh

4. In the inventory file, specify the host of the target machines on which KUMA components should be installed. If the machines are not registered in the DNS zone of your organization, replace the parameter values ip (0.0.0.0) with the actual IP addresses.

   The hosts are specified in the following sections of the inventory file:

   • core is the section for specifying the host and IP address of the target machine on which KUMA Core will be installed. You may only specify one host in this section.
   • collector is the section for specifying the host and IP address of the target machine on which the collector will be installed. You may specify one of more hosts in this section.
   • correlator is the section for specifying the host and IP address of the target machine on which the correlator will be installed. You may specify one of more hosts in this section.
   • storage is the section for specifying the hosts and IP addresses of the target machines on which storage components will be installed. You may specify one of more hosts in this section.

     Storage components: clusters, shards, replicas, and keepers.

     A cluster is a logical group of machines that possess all accumulated normalized KUMA events. It consists of one or more logical shards.

     A shard is a logical group of machines that possess a specific portion of all normalized events accumulated in the cluster. It consists of one or more replicas. Increasing the number of shards lets you do the following:

     • Accumulate more events by increasing the total number of servers and disk space.
     • Absorb a larger stream of events by distributing the load associated with an influx of new events.
     • Reduce the time taken to search for events by distributing search areas among multiple machines.

     A replica is a machine that is a member of the logical shard and possesses a copy of the data of this shard. If there are multiple replicas, there are multiple copies (data is replicated). Increasing the number of replicas lets you do the following:

     • Improve fault tolerance.
     • Distribute the total load related to data searches among multiple machines (although it's best to increase the number of shards for this purpose).

     A keeper is an optional role of a replica that involves the replica's participation in coordinating data replication throughout the entire cluster. There must be at least one replica with this role for the entire cluster. It is recommended to have 3 keeper replicas. The number of replicas involved in coordinating replication must be an odd number.

     Each machine in the storage section can have the following parameter combinations:

     • shard + replica + keeper
     • shard + replica
     • keeper

     If the shard and replica parameters are specified, the machine is a part of a cluster and helps accumulate and search for normalized KUMA events. If the keeper parameter is additionally specified, the machine also helps coordinate data replication at the cluster-wide level.

     If only keeper is specified, the machine will not accumulate normalized events, but it will participate in coordinating data replication at the cluster-wide level. The keeper parameter values must be unique.

     If several replicas are defined within the same shard, the value of the replica parameter must be unique within this shard.

The inventory file is created. It can be used to install KUMA.

It is recommended that you not remove the inventory file after installing KUMA:

• If you change this file (for example, add information about a new server for the collector), you can reuse it to update the system with a new component.
• You can use this inventory file to delete KUMA.

Installing the program

KUMA is installed using the Ansible tool and the YML inventory file. The installation is performed using the source machine, where all of the KUMA components are installed on the target machines.

Root privileges are required to run the installer.

To install KUMA:

1. On the source machine, log in to the OS as the root user and go to the folder with the unpacked installer.
2. Place the file with the license key in the folder <installer folder>/roles/kuma/files/.
3. Launch the installer by executing the following command:

   ./install.sh distributed.inventory.yml

4. Accept the terms of the End User License Agreement.

   If you do not accept the terms of the End User License Agreement, the program will not be installed.

KUMA components are installed on the target machines. The screen will display the URL of the KUMA web interface and the user name and password that must be used to access the web interface.

By default, the KUMA web interface address is https://kuma.example.com:7220.

Default login credentials (after the first login, you must change the password of the admin account):
- user name—admin
- password—mustB3Ch@ng3d!

It is recommended that you save the inventory file used to install the program. It can be used to add components to the system or remove KUMA.

Creating services

KUMA services should be installed only after KUMA deployment is complete. The services can be installed in any order.

When deploying several KUMA services on the same host, you must specify unique ports for each service using the --api.port <port> parameters during installation.

Below is a list of the sections describing how specific services are created:

• Creating a storage
• Creating a correlator
• Creating a collector
• Creating KUMA agents

Changing CA certificate

After KUMA Core is installed, a unique self-signed CA certificate with the matching key is generated. This CA certificate is used to sign all other certificates for internal communication between KUMA components and REST API requests. The CA certificate is stored on the KUMA Core server in the /opt/kaspersky/kuma/core/certificates/ folder.

You can use your company's certificate and key instead of self-signed KUMA CA certificate and key.

Root privileges are required to change KUMA components configuration.

Before changing KUMA certificate, make sure to make a backup copy of the previous certificate and key with the names backup_external.cert and backup_external.key.

To change KUMA certificate:

1. Rename your company's certificate and key files to external.cert and external.key.

   Keys must be in PEM format.

2. Place external.cert and external.key to the /opt/kaspersky/kuma/core/certificates/ folder.
3. Restart the kuma-core service by running the systemctl restart kuma-core command.
4. Restart the browser hosting the KUMA web interface.

You company's certificate and key are now used for internal communication between KUMA components and REST API requests.

Delete KUMA

To remove KUMA, use the Ansible tool and the user-generated inventory file.

To remove KUMA:

1. On the source machine, go to the installer folder:

   cd kuma-ansible-installer

2. Execute the following command:

   ./uninstall.sh <inventory file>

KUMA and all of the program data will be removed from the server.

The databases that were used by KUMA (for example, the ClickHouse storage database) and the information they contain must be deleted separately.

Updating previous versions of KUMA

You can install KUMA 1.5.x over versions 1.x.x. To do this, follow the instructions for installing the program in a production environment, and when you reach the stage of preparing the inventory file list the hosts of the already deployed KUMA system in it.

During the update, the accumulated events are not transferred from the old version of the program to the new one.

The old services for collectors and correlators in the new program are displayed in the Other section when setting destination points.