[Topic 251751]

Kaspersky Unified Monitoring and Analysis Platform Help

New features

• What's new in KUMA
  
  

Hardware and software requirements

• Hardware and software requirements
  
  

Getting started

• Application architecture
• Installation and removal
• Managing tenants
• Monitoring event sources
  
  

Managing the KUMA web interface

• Administrator's guide
• User guide
  
  

Additional features

• Interaction with external systems via API
  
  

Licensing

• KUMA licensing
  
  

Contacting Technical Support

• How to get technical support
  
  

[Topic 217694]

About Kaspersky Unified Monitoring and Analysis Platform

Kaspersky Unified Monitoring and Analysis Platform (hereinafter KUMA or "application") is an integrated software solution that combines the following functionality:

• Receiving, processing, and storing information security events
• Analyzing and correlating incoming data
• Searching in received events
• Creating notifications about detected indicators of information security threats

The application is built on a microservice architecture. This means that you can create and configure only those microservices (hereinafter also "services") that you need, which lets you use KUMA as a log management system or as a full-fledged SIEM system. In addition, flexible routing of data feeds lets you use third-party services for additional event processing.

The update functionality (including anti-virus signature updates and code base updates) may not be available in the application in the territory of the USA.

[Topic 220925]

What's new

Kaspersky Unified Monitoring and Analysis Platform introduces the following features and improvements:

Changed the storage location of the self-signed CA certificate and the certificate reissue mechanism.
The certificate is stored in the database. The previous method of reissuing internal certificates by deleting certificates from the Core file system and restarting the Core is no longer allowed. This method will cause the Core to fail to start. Until the certificate reissuing process is completed, new services may not be connected to the Core.
After reissuing the internal CA certificates in the Settings → General → Reissue internal CA certificates section of the KUMA web interface, you must stop the services, delete the old certificates from service directories, and manually restart all services. Only users with the General Administrator role can reissue internal CA certificates.

• KUMA now also supports the following operating systems:
  • Ubuntu 22.04 LTS
  • Oracle Linux 9.4
  • Astra Linux 1.7.5
  • RED OS 7, 8.
• Starting with version 3.2.x, the password complexity requirements have been updated. The password must be at least 16 characters long, contain at least one alphabetic and one numeric character, and may not contain three or more identical characters in a row. The new requirements apply only to new installations. In existing KUMA installations, the requirements apply only to new users. For existing users, the requirements are applied only when the password is changed.
• In the KUMA web console, in the Active services section, the Core service is displayed as core-1. In the operating system of the Core server, the kuma-core.service is now named kuma-core 00000000-0000-0000-0000-000000000000.service.
• Added the Event router service. This service lets you receive events from collectors and send events to specified destinations in accordance with the filters configured for the service. An intermediate service like this enables effective load balancing between links and lets you use low-bandwidth links. For example, as shown in the diagram in the expandable section, instead of sending events as multiple streams from collector 5 to the destinations, you can send events as one stream: in the diagram, collector 1 + collector 2 + collector 3 send events to the router of the local office, then to the router of the data center, and from there the events are finally sent to the specified destinations.

  Diagram of event transmission with and without an event router

  

• NCIRCC integration — updated list of fields and incident types, added the ability to submit information about personal data leaks. Exported incidents with an old type that is no longer supported are displayed correctly.
• Grouping by arbitrary fields, using time rounding functions from the event interface.

  When conducting an investigation, you need to get selections of events and build aggregation queries. Now you can run aggregation queries simply by selecting one or more fields you want to group by and doing Run query. Aggregation queries with time rounding are available for fields of the Date type.

  As a result, both the groups and the grouped events can be displayed without rewriting the search query. You can navigate the groups, flip through the lists of events included in the group, and view the fields of event, which makes your job easier and lets you get your result quicker when investigating.

• Now you convert a source field using an information entropy calculation function. In the collector, you can configure an enrichment rule for a source field of the event type, select the entropy conversion type, and specify a target field of the float type in which you want KUMA to place the conversion result. The result of the conversion is a number. Calculating the information entropy allows detecting DNS tunnels or compromised passwords, for example, when a user enters the password instead of the login and this password gets logged in plain text. Typically, a login consists of alphabetic characters, and the conversion calculates the information entropy and returns, for example, 2.5416789. If the user mistakenly enters the password in the login field and so the password ends up in the log as plain text, KUMA calculates the information entropy and outputs 4, because a password containing letters, numerals and special characters has a higher entropy. In this way, you can find events in which the user name has an entropy more than 3, and trigger a "Password change required" rule in such cases. After configuring enrichment in the collector, you must update the settings to apply the changes.
• You can search for events in multiple selected storages simultaneously using a simple query. For example, you can find events to determine where a user account is being blocked or which IP addresses were used to log in to which URLs.

  Some installations may require using multiple separate storages, for example, in cases of low-bandwidth links, or regulatory requirements to store events in a certain country. Federated search allows running a search query on multiple storage clusters simultaneously and getting the result as one combined table. Finding events in distributed storage clusters is now quicker and easier. The combined table of events indicates the storage in which a record was found. Group queries, retroscan, or export to TSV are not supported when searching in multiple clusters.

• Coverage of a MITRE ATT&CK matrix by rules

  When developing detection logic, an analyst can be guided by the mapping of content to real-world threats. You can use MITRE ATT&CK matrices to find out the techniques to which your organization's resources are vulnerable. As an aid to analysts, we developed a tool that allows visualizing the coverage of a MITRE ATT&CK matrix by the rules you have developed and thus assessing the level of security.

  The functionality lets you:

  • Import an up-to-date file with the list of techniques and tactics into KUMA.
  • Specify the techniques and tactics detected by a rule in its properties.
  • Export from KUMA a list of rules marked up in accordance with a matrix to the MITRE ATT&CK Navigator (you can specify individual folders with rules).

  The file with the list of marked up rules is displayed in the MITRE ATT&CK Navigator.

• Reading files by the Windows agent.

  The KUMA agent installed on Windows systems can now read text files and send data to the KUMA collector. The same agent installed on a Windows server can send data both from Windows logs and from text files with logs. For example, you no longer need to use shared folders to get Exchange Server transport logs or IIS logs.

• Getting DNS Analytics logs using the etw connector.

  The new ETW (Event Tracing for Windows) transport used by the Windows agent for reading a DNS Analytics subscription allows getting an extended DNS log, diagnostics events, and analytical information about the operation of the DNS server, which is more information than the DNS debug log provides, and with less impact on DNS server performance.

  Recommended configuration for reading ETW logs:

  • If no agent is installed on the server that is the source of DNS Analytics logs, create a new collector and a new agent:
    1. Create an etw connector. The agent is created automatically.
    2. Create a dedicated collector for ETW logs. In the collector installation wizard, specify the etw connector and the [OOTB] Microsoft DNS ETW logs json normalizer.
    3. Install the collector and the agent.
  • If the WEC agent is already installed on the server that is the source of DNS Analytics logs, create a collector and edit the settings of the manually created agent:
    1. Create a collector with an http transport and \0 as the delimiter; specify the [OOTB] Microsoft DNS ETW logs json normalizer.
    2. Save collector settings.
    3. Install the collector.
    4. In the existing WEC agent, add an ETW configuration and in it, specify the following:
       • The etw connector
       • Specify the collector created at step "a." as the destination.
       • Select http as the destination type and \0 as the delimiter.
    5. Save agent settings and start the agent.
• CyberTrace enrichment over the API.

  Cybertrace-http is a new streaming event enrichment type in CyberTrace that allows you to send a large number of events with a single request to the CyberTrace API. We recommend using this enrichment type for systems with a lot of events. Cybertrace-http significantly outperforms the previous 'cybertrace' type, which is still available in KUMA for backward compatibility.

• Activation with a code.

  Now you can activate KUMA using an activation code. With this method, you do not need to worry about importing new keys into KUMA when renewing or reconfiguring your license. To activate using a code, your Core server needs access to several servers on the internet. You can still use the old activation method with a license file.

• Optimized transmission of events in CEF format. Transmitted events include the CEF header and only non-empty fields. When events are sent to third-party systems in CEF format, empty fields are not transmitted.
• Events can now be received from ClickHouse using the SQL connector. In the SQL connector settings, you can select the Database type for the connection. In this case, the prefix corresponding to the protocol is automatically specified in the URL field.
• The 'file', '1c-log', and '1c-xml' connectors now have the 'Poll interval, ms' setting, which sets the interval for reading files from the directory. Adjusting this setting can reduce CPU and RAM consumption.
• The 'airgap' parameter was removed from the inventory file. If your inventory file still contains the 'airgap' parameter, the installer ignores it during installation or update.
• Secrets of the URL and Proxy types no longer contain the login and password. Added the ability to transform the password.
• Fields containing a value in addition to the key have been added to service events about an entry dropping out of the active sheet and context table. Fields with values provide more flexibility in writing correlation rules for processing such service events.

  A context table record drops out if a nonzero value is specified for the record retention time in the context table configuration.

  When a record becomes out of date, an event is generated inside the correlator, which is "looped back" to the input of the correlator. This event is not sent to the storage.

  If the corresponding correlation rule is configured, a correlation event and an alert can be created based on this event. Such a correlation event is what is sent to the storage and displayed in the Events section.

• Added the service monitoring functionality.

  A user with the General administrator role can configure thresholds for monitored parameters for all types of services except agents and cold storage. If the specified thresholds are exceeded, KUMA generates an audit event, sends a notification email message to the user with the General administrator role, and the service is displayed in the Active services section with a yellow status. A yellow status means that the service is running, but there are errors. You can view the error message by clicking the yellow status icon, and you can take steps to correct the operation of the service.

• The list of statuses for services has been updated: the purple status has been added, and the yellow status is used more broadly.
• Now you can go from the 'Source status' section to the events of the selected event source. Qualifying conditions in the search query string are generated automatically after clicking the link. By default, events are displayed for the last 5 minutes. If necessary, you can change the time interval and repeat the query.
• Collecting metrics from the agent.

  The Metrics section now has a subsection where the performance of the agent is visualized. This graphical view helps administrators who are responsible for collecting events using agents. Metrics for agents are available after upgrading the agents to version 3.2.x.

• Added support for the compact embedded SQLite 3.37.2 database management system.
• Added the 'elastic' connector for receiving events from Elasticsearch versions 7 and 8. A fingerprint secret has been added for the connector.
• For connectors of the tcp, udp, and file types, the following auditd event processing options have been added:
  • The Auditd toggle switch allows grouping auditd event lines received from the connector into an auditd event.
  • The Event buffer TTL field allows specifying the lifetime of the auditd event line buffer in milliseconds.
• Now you can configure a list of fields for event source identification. DeviceProduct, DeviceHostName, DeviceAddress, DeviceProcessName is the set of fields used by default for identifying event sources. Now you can redefine the list of fields and their order. You can specify up to 9 fields in a sequence that is meaningful to the user. After saving changes to the set of fields, previously identified event sources are deleted from the KUMA web interface and from the database. You can still use a set of fields for default event source identification.
• Added the iLike operator to the event search query graphical builder.
• Updated the list of REST API methods. Description of v2.1 methods is available in OpenAPI format.
• The parameters of the snmp-trap connector now include an additional parameter that allows you to specify an OID that is a MAC address.
• The KUMA installer checks the status of SELinux.
• Creating a backup copy of the Core using the "/opt/kaspersky/kuma/kuma tools backup" command line utility is no longer supported
• Certain obsolete normalizers are no longer supported or provided:
  • [Deprecated][OOTB] Microsoft SQL Server xml
  • [Deprecated][OOTB] Windows Basic
  • [Deprecated][OOTB] Windows Extended v.0.3
  • [Deprecated][OOTB] Cisco ASA Extended v 0.1
  • [Deprecated][OOTB] Cisco Basic

[Topic 217846]

Distribution kit

The distribution kit includes the following files:

• kuma-ansible-installer-<build number>.tar.gz is used to install KUMA components without the option of deployment in a high availability configuration
• kuma-ansible-installer-ha-<build number>.tar.gz is used to install KUMA components with the option of deployment in a high availability configuration
• Files containing information about the version (release notes) in Russian and English

[Topic 217889]

Hardware and software requirements

Recommended hardware

This section lists the hardware requirements for processing an incoming event stream in KUMA at various Events per Second (EPS) rates.

The table below lists the hardware and software requirements for installing the KUMA components, assuming that the ClickHouse cluster only accepts INSERT queries. Hardware requirements for SELECT queries are calculated separately for the particular database usage profile of the customer.

Recommended hardware for ClickHouse cluster storage

The configuration of the equipment must be chosen based on the system load profile. You can use the "All-in-one" configuration for an event stream of under 10,000 EPS and when using graphical panels supplied with the system.

KUMA supports Intel and AMD CPUs with SSE 4.2 and AVX instruction set support.

Depending on the number and complexity of database queries made by users, reports, and dashboards, a greater amount of resources may be required.

For every 50,000 assets (above the first 50,000), you must add 2 extra threads or vCPUs and 4 GB of RAM to the resources of the Core component.

For every 100 services (above the first 100) managed by the Core component, you must add 2 additional threads or vCPUs to the resources of the Core component.

ClickHouse must be deployed on solid-state drives (SSD). SSDs help improve data access speed.

* If the system usage profile does not involve running aggregation SQL queries to the Storage with a depth of over 24 hours, you can use HDD arrays (15,000-RPM SAS HDDs in RAID-10).

Hard drives can be used to store data using the HDFS technology.

Exported events are written to the drive of the Core component to the /opt/kaspersky/kuma/core/tmp/ temporary directory. The exported data is stored for 10 days and then automatically deleted. If you plan to export a large amount of events, you must allocate additional space.

Working in virtual environments

The following virtual environments are supported for installing KUMA:

• VMware 6.5 or later
• Hyper-V for Windows Server 2012 R2 or later
• QEMU-KVM 4.2 or later
• "Brest" virtualization software RDTSP.10001-02

Resource recommendations for the Collector component

Consider that for event processing efficiency, the CPU core count is more important than the clock rate. For example, eight CPU cores with a medium clock rate can process events more efficiently than four CPU cores with a high clock rate.

Consider also that the amount of RAM utilized by the collector depends on configured enrichment methods (DNS, accounts, assets, enrichment with data from Kaspersky CyberTrace) and whether aggregation is used (RAM consumption is influenced by the data aggregation window setting, the number of fields used for aggregation of data, volume of data in fields being aggregated). The utilization of computation resources by KUMA depends on the type of events being parsed and the efficiency of the normalizer.

For example, with an event stream of 1000 EPS and event enrichment disabled (event enrichment is disabled, event aggregation is disabled, 5000 accounts, 5000 assets per tenant), one collector requires the following resources:

• 1 CPU core or 1 virtual CPU

• 512 MB of RAM

• 1 GB of disk space (not counting event cache)

For example, to support 5 collectors that do not perform event enrichment, you must allocate the following resources: 5 CPU cores, 2.5 GB of RAM, and 5 GB of free disk space.

Kaspersky recommendations for storage servers

You must use high-speed protocols, such as Fibre Channel or iSCSI 10G for the connection of the data storage system to storage servers. We do not recommend using application-level protocols such as NFS or SMB to connect data storage systems.

On ClickHouse cluster servers, we recommend using the ext4 file system.

If you are using RAID arrays, we recommend using RAID 0 for high performance, or RAID 10 for high performance and high availability.

To ensure high availability and performance of the data storage subsystem, we recommend making sure that all ClickHouse nodes are deployed strictly on different disk arrays.

If you are using a virtualized infrastructure to host system components, we recommend deploying ClickHouse cluster nodes on different hypervisors. You must prevent any two virtual machines with ClickHouse from running on the same hypervisor.

For high-load KUMA installations, we recommend installing ClickHouse on physical servers.

Requirements for agent devices

You must install agents on network infrastructure devices that will send data to the KUMA collector. Device requirements are listed in the following table.

Requirements for client devices for managing the KUMA web interface

CPU: Intel Core i3 8th generation

RAM: 8 GB

Supported browsers:

• Google Chrome 110 or later
• Mozilla Firefox 110 or later

Device requirements for installing KUMA on Kubernetes

Minimum configuration of a Kubernetes cluster for deployment of a high-availability KUMA configuration:

• 1 load balancer node (not part of the cluster)
• 3 controller nodes
• 2 worker nodes

The minimum hardware requirements for devices for installing KUMA on Kubernetes are listed in the table below.

[Topic 230383]

KUMA interface

The application is managed using the web interface.

The window of the application web interface contains the following:

• Sections in the left part of the application web interface window
• Tabs in the upper part of the application web interface window for some sections of the application
• The workspace in the lower part of the application web interface window

The workspace displays the information that you choose to view in the sections and on the tabs of the application web interface window. It also contains controls that you can use to configure the display of the information.

While managing the application web interface, you can use shortcut keys to perform the following actions:

• In all sections: close the window that opens in the right side pane—Esc.
• In the Events section:
  • Switch between events in the right side pane—↑ and ↓.
  • Start a search (when focused on the query field)—Ctrl/Command+Enter.
  • Save a search query—Ctrl/Command+S.

[Topic 230384]

Compatibility with other applications

Kaspersky Endpoint Security for Linux

If KUMA components and the Kaspersky Endpoint Security for Linux application are installed on the same server, the report.db directory may grow very large and even take up the entire drive space. In addition, Kaspersky Endpoint Security for Linux scans all KUMA files by default, including service files, which may affect performance. To avoid these problems:

• Upgrade Kaspersky Endpoint Security for Linux to version 12.0 or later.
• We do not recommend enabling the network components of Kaspersky Endpoint Security for Linux.
• Add the following directories to general exclusions and to on-demand scan exclusions:
  1. On the KUMA Core server:
     • /opt/kaspersky/kuma/victoria-metrics/ — directory with Victoria Metrics data.
     • /opt/kaspersky/kuma/mongodb — directory with MongoDB data.
  2. On the storage server:
     • /opt/kaspersky/kuma/clickhouse/ — the ClickHouse directory.
     • /opt/kaspersky/kuma/storage/<storage ID>/buffers/ — directory with storage buffers.
  3. On the correlator server:
     • /opt/kaspersky/kuma/correlator/<correlator ID>/data/ — directories with dictionaries.
     • /opt/kaspersky/kuma/correlator/<correlator ID>/lists — directories with active lists.
     • /opt/kaspersky/kuma/correlator/<correlator ID>/ctxtables — directories with context tables.
     • /opt/kaspersky/kuma/correlator/<correlator ID>/buffers — directory with buffers.
  4. On the collector server:
     • /opt/kaspersky/kuma/collector/<collector ID>/buffers — directory with buffers.
     • /opt/kaspersky/kuma/collector/<collector>/data/ — directory with dictionaries.
  5. Directories with logs for each service.

For more details on scan exclusions, please refer to the Kaspersky Endpoint Security for Linux Online Help.

[Topic 217958]

Program architecture

The standard installation of the application includes the following components:

• The Core that includes a graphical user interface for monitoring and managing the settings of system components.
• Agents that are used to forward raw events from servers and workstations to KUMA destinations.
• One or more Collectors that receive messages from event sources and parse, normalize, and, if necessary, filter and/or aggregate them.
• Event routers that receive events from collectors and apply the configured filters to route the events to the configured destinations. In this way, these services balance the load on the network links.
• The Correlator that analyzes normalized events received from Collectors, performs the necessary actions with active lists, and creates alerts in accordance with the correlation rules.
• The Storage, which holds normalized events and registered alerts.

Events are transmitted between components over optionally encrypted, reliable transport protocols. You can configure load balancing to distribute load between service instances, and you can also enable automatic switchover to a backup component if the primary component becomes unavailable. If all components are unavailable, events are saved to the hard disk buffer to be sent later. The size of the buffer in the file system for temporary storage of events can be changed.

KUMA architecture

[Topic 217779]

Core

The Core is the central component of KUMA that serves as the foundation upon which all other services and components are built. The Core provides a graphical user interface that is intended for everyday use as well as for configuring the system as a whole.

The Core allows you to:

• Create and configure services (or components) of the application, as well as integrate the necessary software into the system.
• Manage services and user accounts of the application in a centralized way.
• Visualize application performance statistics.
• Investigate security threats based on the received events.

[Topic 217762]

Collector

A collector is an application component that receives messages from event sources, processes these messages, and sends them to a storage, correlator, and/or third-party services to identify alerts.

For each collector, one connector and one normalizer must be configured. You can also configure any number of additional normalizers, filters, enrichment rules, and aggregation rules. For the collector to send normalized events to other services, you must add destinations. Normally, two destinations are used: a storage and a correlator.

The collector iterates over the following steps:

1. Receive messages from event sources

   To receive messages, you must configure an active or passive connector. A passive connector only listens for messages from an event source, while an active connector actively polls an event source, such as a database management system.

   Connectors can have different types. The choice of connector type depends on the transport protocol used for messaging. For example, if your event source sends messages over TCP, you must install a connector of the TCP type.

   The application has the following connector types available:

   • tcp
   • udp
   • netflow
   • sflow
   • nats-jetstream
   • kafka
   • kata/edr
   • http
   • sql
   • file
   • 1c-xml
   • 1c-log
   • diode
   • ftp
   • nfs
   • vmware
   • wmi
   • wec
   • snmp-trap
   • elastic
   • etw
2. Parse and normalize events

   Events received by the connector are processed using a normalizer and normalization rules set by the user. The choice of normalizer depends on the format of messages coming from the event source. For example, if your event source sends messages in the CEF format, you must select a normalizer of the CEF type.

   The following normalizers are available in the application:

   • JSON
   • CEF
   • Regexp
   • Syslog (as per RFC3164 and RFC5424)
   • CSV
   • Key-value
   • XML
   • NetFlow (the same normalizer for NetFlow v5, NetFlow v9 and IPFIX)
   • NetFlow v5
   • NetFlow v9
   • SQL
   • IPFIX (v10)
3. Filter normalized events

   You can configure filters to identify events that satisfy certain conditions and only send such events for processing.

4. Enrich and convert normalized events

   Enrichment rules let you add supplementary information from internal and external sources to the events. The application can use the following enrichment sources:

   • constants
   • cybertrace
   • dictionaries
   • dns
   • events
   • ldap
   • templates
   • timezone data
   • geographic data

   Conversion rules let you convert the values of event fields in accordance with certain criteria. The application offers the following conversion methods:

   • lower: convert all characters to lower case.
   • upper: convert all characters to upper case.
   • regexp: extract a substring using RE2 regular expressions.
   • substring: extract a substring by giving its first and last characters.
   • replace: replace some text with a string.
   • trim: delete the specified characters.
   • append: add characters to the end of the field value.
   • prepend: adds characters to the beginning of the field value.
5. Aggregate normalized events

   You can configure aggregation rules to avoid sending many events of the same kind to the storage and/or correlator. Aggregation rules let you combine multiple events into one event. This can help reduce the load on the services responsible for further event processing, conserve storage space and the events per second (EPS) allowance of your license. For example, if you have many events for network connections between two IP addresses that use the same transport and application layer protocols, you can roll up such events for a certain period into one big event.

6. Send out normalized events

   Having passed through all processing steps, the event is sent to the configured destinations.

[Topic 217784]

Correlator

The Correlator is an application component that analyzes normalized events. As part of the correlation process, an event can be correlated with information from active lists and/or dictionaries.

The correlation analysis produces information that can be used for the following purposes:

• Generating alerts.
• Notifying about alerts.
• Managing active list content.
• Sending correlation events to configured destinations.

Events are correlated in real time. The operating principle of the correlator is based on signature analysis of events. This means that every event is processed in accordance with the correlation rules set by the user. When the application detects a sequence of events that match the correlation rule, a correlation event is created and sent to the Storage. The correlation event can also be sent to a correlator to be analyzed again, which lets you configure correlation rules that trigger on prior analysis results. Products of one correlation rule can be used by other correlation rules.

You can distribute correlation rules and the active lists they use among correlators, thereby balancing the load on services. In this arrangement, collectors will send normalized events to all available correlators.

A correlator iterates over the following steps:

1. Get an event

   The correlator receives a normalized event from a collector or another service.

2. Apply correlation rules

   You can configure correlation rules to trigger on a single event or a sequence of events. If correlation rules do not detect an alert, the event processing ends here.

3. Respond to an alert

   You can configure what happens when an alert is detected. The application offers the following actions:

   • Event enrichment
   • Operations with active lists
   • Sending notifications
   • Saving a correlation event
4. Send a correlation event

   When a sequence of events matches a correlation rule, a correlation event is created and sent to the storage. At this point, the correlator is done processing the event.

[Topic 218010]

Storage

A KUMA storage is used to store normalized events and ensure that KUMA can quickly and reliably access these events to extract analytical data. Access speed and high availability are made possible by the ClickHouse technology. This means that a storage is a ClickHouse cluster bound to a KUMA storage service. ClickHouse clusters can be supplemented with cold storage disks.

When choosing a ClickHouse cluster configuration, consider the specific event storage requirements of your organization. For more information, please refer to the ClickHouse documentation.

You can create spaces in repositories. Spaces let you structure the data in the cluster and, for example, store events of a certain type together.

[Topic 220211]

Basic entities

This section introduces the entities that KUMA works with.

[Topic 221264]

About tenants

KUMA supports the multitenancy mode in which one instance of KUMA installed in the infrastructure of the main organization (main tenant) allows its branches (tenants) to receive and process their own events in isolation.

The system is managed centrally through the shared web interface, however, the tenants operate independently of each other and have access only to their own resources, services, and settings. Events of tenants are stored separately.

A user can have access to multiple tenants at the same time. You can also select which tenants' data you want to be displayed in sections of the KUMA web interface.

Two tenants are created by default in KUMA:

• The Main tenant contains resources and services that belong to the main tenant. Only the general administrator has access to these resources.
• The shared tenant is where the general administrator can place resources, asset categories, and monitoring policies that are available to users of all tenants. You can restrict the access of individual users to the shared tenant.

  If in user settings, the Hide shared resources check box is selected, that user cannot gain access to the Shared folder belonging to the shared tenant in the KUMA web interface in the Resources → <resource type> section. This means that the user cannot view, edit, or otherwise use shared resources. The user is also unable to export shared resources and resource sets that incorporate resources from the shared tenant, either through the web interface or through the REST API.

  If any of the services available to the user use shared resources, the names of these resources are displayed in the service settings, but user cannot view or modify the resources. The content of an active list is available to the user even if the resource of that active list is shared.

  The limitation does not apply to shared asset categories. Shared resources are also always available to users with the general administrator role.

[Topic 217693]

About events

Events are information security events registered on the monitored elements of the corporate IT infrastructure. For example, events include login attempts, interactions with a database, and information sent by sensors. Each individual event may appear meaningless, but taken together, they paint a bigger picture of network activity that can help you identify security threats. This is the core functionality of KUMA.

KUMA receives events from logs and restructures them by bringing data from heterogeneous sources to a uniform format (this process is called normalization). The events are then filtered, aggregated, and sent to the correlator service for analysis and to the storage service where they are retained. When KUMA recognizes a specific event or a sequence of events, it creates correlation events, which are also analyzed and retained. If an event or sequence of events indicates a potential security threat, KUMA creates an alert. An alert is a notification about the threat bundled with all related data, which is brought to the attention of a security officer and can be investigated. If the nature of the data received by KUMA or the generated correlation events and alerts indicate a possible attack or vulnerability, the symptoms of such an occurrence can be combined into an incident.

For convenience of investigating alerts and processing incidents, make sure that time is synchronized on all devices involved in the event life cycle (event sources, KUMA servers, client hosts) with the help of Network Time Protocol (NTP) servers.

Throughout their life cycle, events undergo conversions and may be named differently. The following is an outline of the life cycle of a typical event:

The first steps are carried out in a collector.

1. Raw event. The original message from an event source received at a KUMA connector is called a raw event. This message is unprocessed, and KUMA cannot use it yet. To make it usable, it must be normalized to fit the KUMA data model. This happens at the next stage.
2. Normalized event. A normalizer transforms the data of the raw event to make it fit the KUMA data model. After this transformation, the original message turns into a normalized event, which KUMA can analyze. From this point on, KUMA handles only normalized events. Raw events are no longer used, but they can be kept as a part of normalized events inside the Raw field.

   The application has the following normalizers:

   • JSON
   • CEF
   • Regexp
   • Syslog (as per RFC3164 and RFC5424)
   • CSV/TSV
   • Key-value
   • XML
   • Netflow v5, v9, IPFIX (v10), sFlow v5
   • SQL

   At this point, normalized events can already be used for analysis.

3. Destination. After the collector has processed the event, the event can be sent to other KUMA services: a correlator and/or storage.

Subsequent steps of the event life cycle take place in the correlator.

The following event types are distinguished:

1. Base event. An event that has been normalized.
2. Aggregated event. When dealing with a large number of similar events, you can "merge" them into a single event to save processing time and resources. These act as base events and are processed in the same way, but In addition to all of the parameters of the parent events (the events that have been "merged"), an aggregated event has a counter that tells how many parent events it represents. Aggregated events also store the time when the first and last parent events were received.
3. Correlation event. When a sequence of events is detected that satisfies the conditions of a correlation rule, the application creates a correlation event. These events can be filtered, enriched, and aggregated. They can also be sent for storage or looped into the correlator pipeline.
4. Audit event. Audit events are created when certain security-related actions are performed in KUMA. These events are used to ensure system integrity. These events are automatically placed in a separate storage space and stored for at least 365 days.
5. Monitoring event. These events are used to track changes in the amount of data received by KUMA.

[Topic 217691]

About alerts

In KUMA, an alert is created when a received sequence of events triggers a correlation rule. Correlation rules are created by KUMA analysts to check incoming events for possible security threats, so when a correlation rule is triggered, a warning about possible malicious activity is displayed. Security officers responsible for data protection must investigate these alerts and respond if necessary.

KUMA automatically assigns a severity level to each alert. This parameter shows how important or numerous are the processes that triggered the correlation rule. Alerts with higher severity should be dealt with first. The severity value is automatically updated when new correlation events are received, but a security officer can also set it manually. In this case, the alert severity is no longer automatically updated.

Related events are linked to the alerts, which allows enriching alerts with data from these events. KUMA also offers drill down functionality for alert investigation.

You can use alerts to create incidents.

Alert management in KUMA is described in this section.

[Topic 220212]

About incidents

If the nature of the data received by KUMA or the generated correlation events and alerts indicate a possible attack or vulnerability, the symptoms of such an occurrence can be combined into an incident. This allows security officers to analyze threat manifestations in a comprehensive manner and facilitates response.

You can assign a category, type, and severity to an incident, and assign incidents to data protection officers for processing.

Incidents can be exported to NCIRCC.

[Topic 217692]

About assets

Assets are network devices registered in KUMA. Assets generate network traffic when they send and receive data. KUMA can be configured to track this activity and create base events with a clear indication of where the traffic is coming from and where it is going. The event can contain source and destination IP addresses, as well as DNS names. If you register an asset with certain parameters (for example, a specific IP address), this asset is linked to all events that mention these parameters (IP address in this example).

Assets can be logically grouped. This helps keep your network structure transparent and gives you additional ways to work with correlation rules. When an event linked to an asset is processed, the category of this asset is also taken into consideration. For example, if you assign a high severity value to a certain asset category, base events involving these assets will lead to correlation events with higher severity. This in turn cascades into higher-severity alerts and, therefore, more urgency when responding to such an alert.

We recommend registering network assets in KUMA because using assets allows formulating clear and versatile correlation rules, which makes event analysis more efficient.

Asset management in KUMA is described in this section.

[Topic 221640]

About resources

Resources are KUMA components that contain parameters for implementing various functions: for example, establishing a connection with a given web address or converting data in accordance with certain rules. These modular components are assembled into resource sets for services, which in turn are used to create KUMA services.

[Topic 221642]

About services

Services are the main components of KUMA that handle events by receiving, processing, analyzing, and storing them. Each service consists of two parts that work together:

• One part of the service is created in the KUMA web interface based on a resource set for services.
• The other part of the service is installed in the network infrastructure where KUMA is deployed, as one of KUMA components. The server part of a service can consist of multiple instances: for example, services of the same agent or storage can be installed on multiple devices at the same time.

The two parts of a service are linked to each other by the service ID.

[Topic 217690]

About agents

KUMA agents are services that forward raw events from servers and workstations to KUMA destinations.

The following types of agents are provided:

• wmi agents receive data from remote Windows devices using Windows Management Instrumentation. These are installed on Windows devices.
• wec agents receive Windows logs from the local device using Windows Event Collector. They are installed to Windows assets.
• tcp agents receive data over TCP. These are installed on Linux and Windows devices.
• udp agents receive data over UDP. They are installed to Linux and Windows assets.
• nats-jetstream agents are used for communication through NATS. They are installed to Linux and Windows assets.
• kafka agents are used for kafka communications. They are installed to Linux and Windows assets.
• http agents are used for communication over HTTP. They are installed to Linux and Windows assets.
• file agents get data from a file. They are installed to Linux and Windows assets.
• ftp agents receive data over the File Transfer Protocol. They are installed to Linux and Windows assets.
• nfs agents receive data over the Network File System protocol. They are installed to Linux and Windows assets.
• snmp agents receive data using the Simple Network Management Protocol. They are installed to Linux and Windows assets.
• diode agents are used together with data diodes to receive events from isolated network segments. They are installed to Linux and Windows assets.
• etw agents receive Event Tracing for Windows data. They are installed to Windows assets.

[Topic 217695]

About Priority

Severity reflects the relative importance of security-sensitive activity detected by a KUMA correlator. It suggests the order in which alerts should be processed, and indicates whether senior security officers should be involved.

The correlator automatically assigns a severity value to correlation events and alerts based on correlation rule settings. The severity of an alert also depends on the assets linked to the events being processed because correlation rules take into account the severity of these assets' category. If an alert or correlation event does not have any linked assets with a severity value, or if it does not have any linked assets at all, the alert or correlation event inherits the severity of the correlation rule that generated it. The severity of an alert or correlation event is always equal to or greater than the severity of the correlation rule that generated it.

The severity of an alert can be changed manually. A severity that has been manually modified is no longer automatically updated by correlation rules.

Possible severity values:

• Low
• Medium
• High
• Critical

[Topic 217959]

Program licensing

This section covers the main aspects of application licensing.

[Topic 222243]

About the End User License Agreement

The End User License agreement is a legal agreement between you and AO Kaspersky Lab that specifies the conditions under which you can use the application.

Read the terms of the End User License Agreement carefully before using the application for the first time.

You can familiarize yourself with the terms of the End User License Agreement in the following ways:

• Go to the directory with the extracted installer and read the ./roles/kuma/files/LICENSE text file.
• Go to the directory with the extracted installer and run the following command to display the text of the End User License Agreement:

  ./roles/kuma/files/kuma license --show

• On a host with any KUMA component installed (such as Core, collector, correlator, storage), run the following command to display the text of the End User License Agreement:

  /opt/kaspersky/kuma/kuma license --show

• On devices included in the kuma_storage, kuma_collector, kuma_correlator, or kuma_core groups in the inventory file, open the LICENSE file located in the /opt/kaspersky/kuma directory.

  On a host in the kuma_core group, you can view the End User License Agreement only if a non-cluster installation is selected.

• On the Windows agent, run the following command to display the text of the End User License Agreement:

  .\kuma.exe license --show

• On the Linux agent, go to the directory with the 'kuma' executable file and run the following command to display the text of the End User License Agreement:

  ./kuma license --show

You accept the terms of the End User License Agreement by confirming your acceptance of the End User License Agreement during the application installation. If you do not accept the terms of the End User License Agreement, you must cease the installation of the application and must not use the application.

[Topic 233460]

About the license

A License is a time-limited right to use the application, granted under the terms of the End User License Agreement.

A license entitles you to the following kinds of services:

• Use of the application in accordance with the terms of the End User License Agreement
• Getting technical support

The scope of services and the duration of usage depend on the type of license under which the application was activated.

A license is provided when the application is purchased. KUMA behavior in case no license is available:

• After the license expires, KUMA keeps working, but with limited functionality: collectors continue to receive and process events for 7 days, after which they restart and stop receiving new events. Old events remain available. Creating and editing resources, creating and running services also becomes impossible.
• If the license is removed, KUMA collectors stop receiving and processing new events immediately. Old events remain available. Creating and editing resources, creating and running services also becomes impossible.

To continue using KUMA with its full functionality, you need to renew your license.

We recommend that you renew your license no later than its expiration date to ensure maximum protection against cyberthreats.

[Topic 233471]

About the License Certificate

A License Certificate Is a document that is provided to you along with a key file or activation code.

The License Certificate contains the following information about the license being granted:

• License key or order number
• Information about the user who is granted the license
• Information about the application that can be activated under the provided license
• Restriction on the number of licensing units (for example, the number of events that can be processed per second)
• Start date of the license term
• License expiration date or license term
• License type

[Topic 233462]

About the license key

A license key is a sequence of bits that you can apply to activate and then use the application in accordance with the terms of the End User License Agreement. License keys are generated by Kaspersky specialists.

You can add a license key to the application by applying a key file. The license key is displayed in the application interface as a unique alphanumeric sequence after you add it to the application.

The license key may be blocked by Kaspersky in case the terms of the License Agreement have been violated. If the license key has been blocked, you need to add another one if you want to use the application.

A license key may be active or reserve.

An active license key is the license key currently used by the application. An active license key can be added for a trial or commercial license. The application cannot have more than one active license key.

A reserve license key is the license key that entitles the user to use the application but is not currently in use. The additional license key automatically becomes active when the license associated with the current active license key expires. An additional license key can be added only if an active license key has already been added.

A license key for a trial license can be added as an active license key. A license key for a trial license cannot be added as an additional license key.

[Topic 233467]

About the key file

The key file is a file named license.key provided to you by Kaspersky. The key file is used to add a license key that activates the application.

You receive a key file at the email address that you provided after purchasing KUMA.

You do not need to connect to Kaspersky activation servers in order to activate the application with a key file.

If the key file has been accidentally deleted, you can restore it. You may need a key file, for example, to register with Kaspersky CompanyAccount.

To restore the key file, you need to do one of the following:

• Contact the license seller.
• Get a key file on the Kaspersky website based on the available activation code.

[Topic 276582]

About the license code

A license code is a unique sequence of twenty Latin letters and numerals that allows you to activate the application. Kaspersky sends you a license code to the email address that you provided after purchasing KUMA.

Activation with a license code from the Core server requires constant internet access. If you are using KUMA 3.2.1 and having a FSTEC certificate is important for you, do not activate the application using a license code and activate it using a license key instead.

To activate with a license code, you need a connection to Kaspersky activation servers:

https://activation-v2.kaspersky.com:443

In the case of a closed infrastructure, you can specify a proxy server.

If the license code was accidentally deleted, you can get it again by contacting the license vendor.

When the license code is deleted from KUMA, the KUMA collectors immediately stop receiving and processing new events. Old events remain available. Creating and editing resources, creating and running services also becomes impossible.

The web interface of the application displays settings depending on the functionality covered by the license.

If you want to use a license code to activate KUMA, in the Settings → License section, in the Activation type drop-down list, select Activate by code.

If the new license fully matches the parameters of the license that was activated with a license file, the license code activation is performed seamlessly. If the parameters of the old license and the new license are different, the services are restarted

KUMA generates an audit event after adding a license, deleting a license, or a license expiring.

When switching from a license file to a license code, the previous license is automatically deleted. Before renewing your license, make sure that you have the old activation file in your possession.

[Topic 261327]

Data provision in Kaspersky Unified Monitoring and Analysis Platform

Data provided to third parties

KUMA functionality does not involve automatic provision of user data to third parties.

Locally processed data

Kaspersky Unified Monitoring and Analysis Platform (hereinafter KUMA or "application") is an integrated software solution that combines the following functionality:

• Receiving, processing, and storing information security events
• Analyzing and correlating incoming data
• Searching in received events
• Creation of notifications upon detecting symptoms of information security threats.
• Creation of alerts and incidents for processing information security threats.
• Displaying information about the status of the customer's infrastructure on the dashboard and in reports.
• Monitoring event sources.
• Device (asset) management — viewing information about assets, searching, adding, editing, and deleting assets, exporting asset information to a CSV file.

To perform its primary functions, KUMA may receive, store and process the following information:

• Information about devices on the corporate network.

  The KUMA Core server receives data if the corresponding integration is configured. You can add assets to KUMA in the following ways:

  • Import assets:
    • On demand from MaxPatrol.
    • On a schedule from Kaspersky Security Center and KICS for Networks.
  • Create assets manually through the web interface or via the API.

  KUMA stores the following device information:

  • Technical characteristics of the device.
  • Information specific to the source of the asset.
• Additional technical attributes of devices on the corporate network that the user specifies to send an incident to NCIRCC: IP addresses, domain names, URIs, email address of the attacked object, attacked network service, and port/protocol.
• Information about the organization: name, tax ID, address, email address for sending notifications.
• Active Directory information about organizational units, domains, users, and groups obtained as a result of querying the Active Directory network.

  The KUMA Core server receives this information if the corresponding integration is configured. To ensure the security of the connection to the LDAP server, the user must enter the server URL, the Base DN, connection credentials, and certificate in the KUMA console.

• Information for domain authentication of users in KUMA: root DN for searching access groups in the Active Directory directory service, URL of the domain controller, certificate (the root public key that the AD certificate is signed with), full path to the access group of users in AD (distinguished name).
• Information contained in events from configured sources.

  In the collector, the event source is configured, KUMA events are generated and sent to other KUMA services. Sometimes events can arrive first at the agent service, which relays events from the source to the collector.

• Information required for the integration of KUMA with other applications (Kaspersky Threat Lookup, Kaspersky CyberTrace, Kaspersky Security Center, Kaspersky Industrial CyberSecurity for Networks, Kaspersky Automated Security Awareness Platform, Kaspersky Endpoint Detection and Response, Security Orchestration, Automation and Response).

  It can include certificates, tokens, URLs or credentials for establishing a connection with the other application, or other data necessary for the basic functionality of KUMA, for example, email. The user enters this data in the KUMA console

• Information about sources from which event receipt is configured.

  It can include the source name, host name, IP address, the monitoring policy assigned to the source. The monitoring policy specifies the email address of the person responsible, to whom a notification will be sent if the policy is violated.

• User accounts: name, username, email address. The user can view their profile data in the KUMA console.
• User profile settings:
  • User role in KUMA. Assigned roles will be displayed.
  • Localization language, notification settings, display of non-printable characters.

    The user enters this data in the KUMA interface.

  • List of asset categories in the Assets section, default dashboard, TV mode flag for the dashboard, SQL query for default events, default preset.

    The user specifies these settings in the corresponding sections of the KUMA console.

• Data for domain authentication of users in KUMA:
  • Active Directory: root DN for searching access groups in the Active Directory directory service, URL of the domain controller, certificate (the root public key that the AD certificate is signed with), full path to the access group of users in AD (distinguished name).
  • Active Directory Federation Services: trusted party ID (KUMA ID in ADFS), URI for getting Connect metadata, URL for redirection from ADFS, and the ADFS server certificate.
  • FreeIPA: Base DN, URL, certificate (the public root key that was used to signed the FreeIPA certificate), custom integration credentials, connection credentials.
• Audit events

  KUMA automatically records audit events.

• KUMA log

  The user can enable verbose logging in the KUMA console. Log entries are stored on the user's device, no data is transmitted automatically.

• Information about the user accepting the terms and conditions of legal agreements with Kaspersky.
• Any information that the user enters in the KUMA interface.

The information listed above can find its way into KUMA in the following ways:

• The user enters information in the KUMA console.
• KUMA services (agent or collector) receive data if the user has configured a connection to event sources.
• Through the KUMA REST API.
• Device information can be obtained using the utility from MaxPatrol.

The listed information is stored in the KUMA database (MongoDB, ClickHouse, SQLite). Passwords are stored in an encrypted form (the hash of the password is stored).

All of the information listed above can be transmitted to Kaspersky only in dump files, trace files, or log files of KUMA components, including log files created by the installer and utilities.

Dump files, trace files, and log files of KUMA components may contain personal and confidential information. Dump files, trace files, and log files are stored on the device in unencrypted form. Dump files, trace files, and log files are not automatically submitted to Kaspersky, but the administrator can manually submit this information to Kaspersky at the request of Technical Support to help troubleshoot KUMA problems.

Kaspersky uses the collected data in anonymized form and only for general statistical purposes. Summary statistics is generated from the received raw data automatically and does not contain any personal or other confidential information. When new data accumulates, older data is erased (once a year). Summary statistics is stored indefinitely.

Kaspersky protects all received data in accordance with applicable law and Kaspersky policies. Data is transmitted over secure communication channels.

[Topic 217709]

Adding a license key to the program web interface

You can add an application license key in the KUMA web interface.

Only users with the Administrator role can add a license key.

To add a license key to the KUMA web interface:

1. Open the KUMA web interface and select Settings → License.

   The window with KUMA license conditions opens.

2. Select the key you want to add:
   • If you need to add an active key, click the Add active license key button.

     This button is not displayed if a license key has already been added to the application. If you want to add an active license key instead of the key that has already been added, the current license key must be deleted.

   • If you want to add a reserve key, click the Add reserve license key button.

     This button is inactive until an active key is added. If you want to add a reserve license key instead of the key that has already been added, the current reserve license key must be deleted.

   The license key file selection window appears on the screen.

3. Select a license file by specifying the path to the directory and the name of the license key file with the KEY extension.

The license key from the selected file will be loaded into the application. Information about the license key is displayed under Settings → License.

[Topic 218040]

Viewing information about an added license key in the program web interface

In the KUMA web interface, you can view information about the added license key. Information about the license key is displayed under Settings → License.

Only users with the Administrator role can view license information.

The License tab window displays the following information about added license keys:

• Expires on—date when the license key expires.
• Days remaining—number of days before the license is expired.
• EPS available—number of events processed per second supported by the license.
• EPS current per day is the current average amount of events processed by KUMA per day.
• License key—unique alphanumeric sequence.
• Company—name of the company that purchased the license.
• Client name—name of client who purchased the license.
• Modules—modules available for the license.

For an SMB license, the following settings are available in addition to the above:

• EPS current per day is the current average amount of events processed by KUMA per day.
• EPS current per hour is the current average amount of events processed by KUMA per hour.

If values of two settings are exceeded, the collector with the maximum EPS value stops receiving new events for 1 hour. After 1 hour, the collector resumes operation. Multiple collectors may be paused at the same time. A notification about the maximum EPS allowed by the license being exceeded is sent to the user with the General Administrator role.

[Topic 217963]

Removing a license key in the program web interface

In KUMA, you can remove an added license key from the application (for example, if you need to replace the current license key with a different key). After the license key is removed, collectors immediately stop receiving and processing events. Old events remain available. Creating and editing resources, creating and running services also becomes impossible. This functionality will be re-activated the next time you add a license key.

Only users with the administrator role can delete license keys.

To delete an added license key:

1. Open the KUMA web interface and select Settings → License.

   The window with KUMA license conditions opens.

2. Click the icon on the license that you want to delete.

   A confirmation window opens.

3. Confirm deletion of the license key.

The license key will be removed from the application.

[Topic 249526]

Administrator's guide

This section provides information about installing and configuring the KUMA SIEM system.

[Topic 217904]

Installing and removing KUMA

Expand all | Collapse all

To install KUMA, you need the distribution kit:

• kuma-ansible-installer-<build number>.tar.gz contains all necessary files for installing KUMA without the support for high availability configurations.
• kuma-ansible-installer-ha-<build number>.tar.gz contains all necessary files for installing KUMA in a high availability configuration.

To complete the installation, you need the install.sh installer file and an inventory file that describes your infrastructure. You can create an inventory file based on a template. Each distribution contains an install.sh installer file and the following inventory file templates:

• single.inventory.yml.template
• distributed.inventory.yml.template
• expand.inventory.yml.template
• k0s.inventory.yml.template

KUMA keeps its files in the /opt directory, so we recommend making /opt a separate partition and allocating 16 GB for the operating system and the remainder of the disk space for the /opt partition.

KUMA is installed in the same way on all hosts using the installer and your prepared inventory file in which you describe your configuration. We recommend taking time to think through the setup before you proceed.

The following installation options are available:

• Installation on a single server

  Single-server installation diagram

  

  Installation on a single server

  Example inventory file for installation on a single server

  all:

  vars:

  deploy_to_k8s: false

  need_transfer: false

  generate_etc_hosts: false

  deploy_example_services: true

  no_firewall_actions: false

  kuma:

  vars:

  ansible_connection: ssh

  ansible_user: root

  children:

  kuma_core:

  hosts:

  kuma1.example.com:

  mongo_log_archives_number: 14

  mongo_log_frequency_rotation: daily

  mongo_log_file_size: 1G

  kuma_collector:

  hosts:

  kuma1.example.com

  kuma_correlator:

  hosts:

  kuma1.example.com

  kuma_storage:

  hosts:

  kuma1.example.com:

  shard: 1

  replica: 1

  keeper: 1

  You can install all KUMA components on the same server. To do so, specify the same server in the single.inventory.yml inventory file for all components. An "all-in-one" installation can handle a small stream of events, up to 10,000 EPS. If you plan to use many dashboard layouts and process a lot of search queries, a single server might not be sufficient. In that case, we recommend the distributed installation.

• Distributed installation

  Distributed Installation diagram

  

  Distributed installation diagram

  Example inventory file for distributed installation

  all:

  vars:

  deploy_to_k8s: false

  need_transfer: false

  generate_etc_hosts: false

  deploy_example_services: false

  no_firewall_actions: false

  kuma:

  vars:

  ansible_connection: ssh

  ansible_user: root

  children:

  kuma_core:

  hosts:

  kuma-core-1.example.com:

  ip: 0.0.0.0

  mongo_log_archives_number: 14

  mongo_log_frequency_rotation: daily

  mongo_log_file_size: 1G

  kuma_collector:

  hosts:

  kuma-collector-1.example.com:

  ip: 0.0.0.0

  kuma_correlator:

  hosts:

  kuma-correlator-1.example.com:

  ip: 0.0.0.0

  kuma_storage:

  hosts:

  kuma-storage-cluster1-server1.example.com:

  ip: 0.0.0.0

  shard: 1

  replica: 1

  keeper: 0

  kuma-storage-cluster1-server2.example.com:

  ip: 0.0.0.0

  shard: 1

  replica: 2

  keeper: 0

  kuma-storage-cluster1-server3.example.com:

  ip: 0.0.0.0

  shard: 2

  replica: 1

  keeper: 0

  kuma-storage-cluster1-server4.example.com:

  ip: 0.0.0.0

  shard: 2

  replica: 2

  keeper: 0

  kuma-storage-cluster1-server5.example.com:

  ip: 0.0.0.0

  shard: 0

  replica: 0

  keeper: 1

  kuma-storage-cluster1-server6.example.com:

  ip: 0.0.0.0

  shard: 0

  replica: 0

  keeper: 2

  kuma-storage-cluster1-server7.example.com:

  ip: 0.0.0.0

  shard: 0

  replica: 0

  keeper: 3

  You can install KUMA services on different servers. You can describe the configuration for a distributed installation in the distributed.inventory.yml inventory file.

• Distributed installation in a high availability configuration

  Diagram of distributed installation in a high availability configuration

  

  Distributed installation in a high availability configuration

  Example inventory file for distributed installation in a high availability configuration

  all:

  vars:

  deploy_to_k8s: true

  need_transfer: true

  generate_etc_hosts: false

  airgap: true

  deploy_example_services: false

  no_firewall_actions: false

  kuma:

  vars:

  ansible_connection: ssh

  ansible_user: root

  children:

  kuma_core:

  hosts:

  kuma-core-1.example.com:

  mongo_log_archives_number: 14

  mongo_log_frequency_rotation: daily

  mongo_log_file_size: 1G

  kuma_collector:

  hosts:

  kuma-collector-1.example.com:

  ip: 0.0.0.0

  kuma-collector-2.example.com:

  ip: 0.0.0.0

  kuma_correlator:

  hosts:

  kuma-correlator-1.example.com:

  ip: 0.0.0.0

  kuma-correlator-2.example.com:

  ip: 0.0.0.0

  kuma_storage:

  hosts:

  kuma-storage-cluster1-server1.example.com:

  ip: 0.0.0.0

  shard: 1

  replica: 1

  keeper: 0

  kuma-storage-cluster1-server2.example.com:

  ip: 0.0.0.0

  shard: 1

  replica: 2

  keeper: 0

  kuma-storage-cluster1-server3.example.com:

  ip: 0.0.0.0

  shard: 2

  replica: 1

  keeper: 0

  kuma-storage-cluster1-server4.example.com:

  ip: 0.0.0.0

  shard: 2

  replica: 2

  keeper: 0

  kuma-storage-cluster1-server5.example.com:

  ip: 0.0.0.0

  shard: 0

  replica: 0

  keeper: 1

  kuma-storage-cluster1-server6.example.com:

  ip: 0.0.0.0

  shard: 0

  replica: 0

  keeper: 2

  kuma-storage-cluster1-server7.example.com:

  ip: 0.0.0.0

  shard: 0

  replica: 0

  keeper: 3

  kuma_k0s:

  vars:

  ansible_connection: ssh

  ansible_user: root

  children:

  kuma_lb:

  hosts:

  kuma_lb.example.com:

  kuma_managed_lb: true

  kuma_control_plane_master:

  hosts:

  kuma_cpm.example.com:

  ansible_host: 10.0.1.10

  kuma_control_plane_master_worker:

  kuma_control_plane:

  hosts:

  kuma_cp1.example.com:

  ansible_host: 10.0.1.11

  kuma_cp2.example.com:

  ansible_host: 10.0.1.12

  kuma_control_plane_worker:

  kuma_worker:

  hosts:

  kuma-core-1.example.com:

  ansible_host: 10.0.1.13

  extra_args: "--labels=kaspersky.com/kuma-core=true,kaspersky.com/kuma-ingress=true,node.longhorn.io/create-default-disk=true"

  kuma_worker2.example.com:

  ansible_host: 10.0.1.14

  extra_args: "--labels=kaspersky.com/kuma-core=true,kaspersky.com/kuma-ingress=true,node.longhorn.io/create-default-disk=true"

  You can install the KUMA Core on a Kubernetes cluster for high availability. Describe the configuration i nthe k0s.inventory.yml inventory file.

[Topic 231034]

Program installation requirements

General application installation requirements

You can install the application on the following operating systems:

• Oracle Linux
• Astra Linux
• Ubuntu 22.04 LTS
• RED OS 7.3.4 or 8

  Supported configurations are Server and Server with GUI support. In the Server with GUI support configuration, you do not need to install additional packages for reporting.

  RED OS 8 is supported without high availability (HA). When using RED OS 8 in the Server with GUI support configuration, you need to install the iscsi-initiator-utils package, and then run the following commands:

  systemctl enable iscsid

  systemctl start iscsid

Before deploying the application, make sure the following conditions are met:

• Servers on which you want to install the components satisfy the hardware and software requirements.
• Ports to be used by the installed instance of KUMA are available.
• KUMA components are addressed using the fully qualified domain name (FQDN) of the host in the hostname.example.com format. Before you install the application, make sure that the correct host FQDN is returned in the Static hostname field. To do so, run the following command:

  hostnamectl status

• The name of server on which you are running the installer is not localhost or localhost.<domain>.
• The name of the server on which you are installing KUMA Core does not start with a numeral.
• Time synchronization over Network Time Protocol (NTP) is configured on all servers with KUMA services.

Installation requirements for Oracle Linux, Astra Linux, Ubuntu 22.04 LTS, and RED OS 7.3.4 and 8

[Topic 267523]

Upgrading from Oracle Linux 8.x to Oracle Linux 9.x

To upgrade from Oracle Linux 8.x to Oracle Linux 9.x:

1. Run the following commands to disable KUMA services on the hosts where the services are installed:
   • sudo systemctl disable kuma-collector-<service ID>.service
   • sudo systemctl disable kuma-correlator-<service ID>.service
   • sudo systemctl disable kuma-storage-<service ID>.service
   • sudo systemctl disable kuma-grafana.service
   • sudo systemctl disable kuma-mongodb.service
   • sudo systemctl disable kuma-victoria-metrics.service
   • sudo systemctl disable kuma-vmalert.service
   • sudo systemctl disable kuma-core.service
2. Upgrade the OS on every host.
3. After the upgrade is complete, run the following command to install the compat-openssl11 package on the host where you want to deploy the KUMA Core outside of the cluster:

   yum install compat-openssl11

4. Run the following commands to enable the services on the hosts where the services are installed:
   • sudo systemctl enable kuma-core.service
   • sudo systemctl enable kuma-storage-<service ID>.service
   • sudo systemctl enable kuma-collector-<service ID>.service
   • sudo systemctl enable kuma-correlator-<service ID>.service
   • sudo systemctl enable kuma-grafana.service
   • sudo systemctl enable kuma-mongodb.service
   • sudo systemctl enable kuma-victoria-metrics.service
   • sudo systemctl enable kuma-vmalert.service
5. Restart the hosts.

As a result, the upgrade is completed.

[Topic 217770]

Ports used by KUMA during installation

For the application to run correctly, you need to ensure that the KUMA components are able to interact with other components and applications over the network using the protocols and ports specified during the installation of the KUMA components.

Before installing the Core on a device, make sure that the following ports are available:

• 9090: used by Victoria Metrics.
• 8880: used by VMalert.
• 27017: used by MongoDB.

The table below lists the default ports. The installer automatically opens the ports during KUMA installation.

Network ports used for the interaction of KUMA components

Ports used by predefined OOTB resources

The installer automatically opens these ports during KUMA installation.

Ports used by predefined OOTB resources:

• 7230/tcp
• 7231/tcp
• 7232/tcp
• 7233/tcp
• 7234/tcp
• 7235/tcp
• 5140/tcp
• 5140/udp
• 5141/tcp
• 5144/udp

KUMA Core traffic in a high availability configuration

The "KUMA Core traffic in a high availability configuration" table lists connection initiators (sources) and destinations. The port number of the initiator can be dynamic. Return traffic within the established connection must not be blocked.

KUMA Core traffic in a high availability configuration

[Topic 275543]

Reissuing internal CA certificates

The storage location of the self-signed CA certificate and the certificate reissue mechanism have been changed.
The certificate is stored in the database. The previous method of reissuing internal certificates by deleting certificates from the file system of the Core and restarting the Core is no longer allowed. The old method will cause the Core to fail to start. Do not connect new services to the Core until the certificate is successfully reissued.
After reissuing the internal CA certificates in the Settings → General → Reissue internal CA certificates section of the KUMA web interface, you must stop the services, delete the old certificates from the directories of the service, and manually restart all services. Only users with the General Administrator role can reissue internal CA certificates.

The Reissue internal CA certificates option is available only to a user with the General Administrator role.

The process of reissuing certificates for an individual service remains the same: in the KUMA web interface, in the Resources → Active services section, select the service; in the context menu, select Reset certificate, and delete the old certificate from the service installation directory. KUMA automatically generates a new certificate. You do not need to restart running services, the new certificate is applied automatically. A stopped service must be restarted to have the certificate applied.

To reissue internal CA certificates:

1. In the KUMA web interface, go to the Settings → General section, click Reissue internal CA certificates, and read the displayed warning. If you decide to proceed with reissuing certificates, click Yes.

   As a result, the CA certificates for KUMA services and the CA certificate for ClickHouse are reissued. Next, you must stop the services, delete old certificates from the service installation directories, restart the Core, and restart the stopped services to apply the reissued certificates.

2. Connect to the hosts where the collector, correlator, and event router services are deployed.
   1. Stop all services with the following command:

      sudo systemctl stop kuma-<collector/correlator/eventRouter>-<service ID>.service

   2. Delete the internal.cert and internal.key certificate files from the "/opt/kaspersky/kuma/<service type>/<service ID>/certificates" directories with the following command:

      sudo rm -f /opt/kaspersky/kuma/<service type>/<service ID>/certificates/internal.cert

      sudo rm -f /opt/kaspersky/kuma/<service type>/<service ID>/certificates/internal.key

3. Connect to the hosts where storage services are deployed.
   1. Stop all storage services.

      sudo systemctl stop kuma-<storage>-<service ID>.service

   2. Delete the internal.cert and internal.key certificate files from the "/opt/kaspersky/kuma/storage/<ID service>/certificates" directories.

      sudo rm -f /opt/kaspersky/kuma/storage/<service ID>/certificates/internal.cert

      sudo rm -f /opt/kaspersky/kuma/storage/<service ID>/certificates/internal.key

4. Delete all ClickHouse certificates from the "/opt/kaspersky/kuma/clickhouse/certificates" directory.

   sudo rm -f /opt/kaspersky/kuma/clickhouse/certificates/internal.cert

   sudo rm -f /opt/kaspersky/kuma/clickhouse/certificates/internal.key

5. Connect to the hosts where agent services are deployed.
   1. Stop the services of Windows agents and Linux agents.
   2. Delete the internal.cert and internal.key certificate files from the working directories of the agents.
6. Start the Core to apply the new CA certificates.
   • For an "all-in-one" or distributed installation of KUMA, run the following command:

     sudo systemctl restart kuma-core-00000000-0000-0000-0000-000000000000.service

   • For KUMA in a high availability configuration, to restart the Core, run the following command on the primary controller:

     sudo k0s kubectl rollout restart deployment/core-deployment -n kuma

     You do not need to restart victoria-metrics.

     The Core must be restarted using the command because restarting the Core in the KUMA interface affects only the Core container and not the entire pod.

7. Restart all services that were stopped as part of the procedure.

   sudo systemctl start kuma-<collector/correlator/eventRouter/storage>-<service ID>.service

8. Restart victoria-metrics.

   sudo systemctl start kuma-victoria-metrics.service

Internal CA certificates are reissued and applied.

[Topic 217747]

Modifying the self-signed web console certificate

You can use your company's certificate and key instead of the self-signed certificate of the web console. For example, if you want to replace the self-signed CA certificate of the Core with a certificate issued by your corporate CA, you must provide an external.cert and an unencrypted external.key in PEM format.

The following example shows how to replace a self-signed CA certificate of the Core with your corporate certificate in PFX format. You can use instructions in this section as an example and adapt the steps according to your needs.

To replace the certificate of the KUMA web console with an external certificate:

1. If you are using a certificate and key in a PFX container, use OpenSSL to convert the PFX file to a certificate and encrypted key in PEM format:

   openssl pkcs12 -in kumaWebIssuedByCorporateCA.pfx -nokeys -out external.cert

   openssl pkcs12 -in kumaWebIssuedByCorporateCA.pfx -nocerts -nodes -out external.key

   Enter the password of the PFX key when prompted (Enter Import Password).

   The command creates the external.cert certificate and the external.key key in PEM format.

2. In the KUMA web interface, go to the Settings → Common → Core settings section under External TLS pair, click Upload certificate and Upload key and upload the external.cert file and the unencrypted external.key file in PEM format.
3. Restart KUMA:

   systemctl restart kuma-core

4. Refresh the web page or restart the browser that you are using to manage the KUMA web interface.

Your company certificate and key are replaced.

[Topic 255123]

Synchronizing time on servers

To configure time synchronization on servers:

1. Install chrony:

   sudo apt install chrony

2. Configure the synchronization of system time with an NTP server:
   1. Make sure the virtual machine has internet access.

      If the virtual machine has internet access, go to step b.

      If the virtual machine does not have internet access, edit the /etc/chrony.conf file to replace 2.pool.ntp.org with the name or IP address of your corporate NTP server.

   2. Start the system time synchronization service:

      sudo systemctl enable --now chronyd

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

      sudo timedatectl | grep 'System clock synchronized'

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

Synchronization is configured.

[Topic 255188]

About the inventory file

You can install, update, or remove KUMA components by changing to the directory with the extracted kuma-ansible-installer and using the Ansible tool and a prepared inventory file. You can specify KUMA configuration settings in the inventory file; the installer then uses these settings ​​when deploying, updating, and removing the application. The inventory file must conform to the YAML format.

You can create an inventory file based on the templates included in the distribution kit. The following templates are provided:

• single.inventory.yml.template can be used when installing KUMA on a single server. This template contains the minimum set of settings optimized for installation on a single device without using a Kubernetes cluster.
• distributed.inventory.yml.template can be used for the initial distributed installation of KUMA without using a Kubernetes cluster, for expanding an all-in-one installation to a distributed installation, and for updating KUMA.
• expand.inventory.yml.template can be used in some reconfiguration scenarios, such as adding collector and correlator servers, expanding an existing storage cluster, or adding a new storage cluster. If you use this inventory file to modify the configuration, the installer does not stop services in the entire infrastructure. If you reuse the inventory file, the installer can stop only services on hosts that are listed in the expand.inventory.yml file.
• k0s.inventory.yml.template can be used to install or migrate KUMA to a Kubernetes cluster.

We recommend saving a backup copy of the inventory file that you used to install the application. You can use it to add components to the system or remove KUMA.

[Topic 244406]

KUMA settings in the inventory file

The inventory file may include the following blocks:

• all
• kuma
• kuma_k0s

For each host, you must specify the FQDN in the <host name>.<domain> format and, if necessary, an IPv4 or IPv6 address. The KUMA Core domain name and its subdomains may not start with a numeral.

The 'all' block

In this block, you can specify the variables that apply to all hosts listed in the inventory file, including the implicitly specified localhost on which the installation is started. Variables can be overridden at the level of host groups or individual hosts.

Example of overriding variables in the inventory file

The table below lists all possible variables in the vars section and their descriptions.

List of possible variables in the 'vars' section

The 'kuma' block

In this block, you can specify the settings of KUMA components deployed outside of the Kubernetes cluster. The kuma block can contain the following sections:

• vars contains variables that apply to all hosts specified in the kuma block.
• children contains groups of settings for components:
  • kuma_core contains settings of the KUMA Core. You can specify only one host and the following MongoDB database log rotation settings for the host:
    • mongo_log_archives_number is the number of previous logs that you want to keep when rotating the MongoDB database log.
    • mongo_log_file_size is the size of the MongoDB database log, in gigabytes, at which rotation begins. If the MongoDB database log never exceeds the specified size, no rotation occurs.
    • mongo_log_frequency_rotation is the interval for checking the size of the MongoDB database log for rotation purposes. Possible values:
      • hourly means the size of the MongoDB database log is checked every hour.
      • daily means the size of the MongoDB database log is checked every day.
      • weekly means the size of the MongoDB database log is checked every week.

    The MongoDB database log is stored in the /opt/kaspersky/kuma/mongodb/log directory.

    • raft_node_addr is the FQDN on which you want raft to listen for signals from other nodes. This value must be specified in the <host FQDN>:<port> format. If this setting is not specified explicitly, <host FQDN> defaults to the FQDN of the host on which the KUMA Core is deployed, and <port> defaults to 7209. You can specify an address of your choosing to adapt the KUMA Core to the configuration of your infrastructure.
  • kuma_collector contains settings of KUMA collectors. You can specify multiple hosts.
  • kuma_correlator contains settings of KUMA correlators. You can specify multiple hosts.
  • kuma_storage contains settings of KUMA storage nodes. You can specify multiple hosts as well as shard, replica, and keeper IDs for hosts using the following settings:
    • shard is the shard ID.
    • replica is the replica ID.
    • keeper is the keeper ID.

    The specified shard, replica, and keeper IDs are used only if you are deploying demo services as part of a fresh KUMA installation. In other cases, the shard, replica, and keeper IDs that you specified in the KUMA web interface when creating a resource set for the storage are used.

The 'kuma_k0s' block

In this block, you can specify the settings of the Kubernetes cluster that ensures high availability of KUMA. This block is specified only in an inventory file based on k0s.inventory.yml.template.

For test and demo installations in environments with limited computational resources, you must also set low_resources: true in the all block. In this case, the minimum size of the KUMA Core installation directory is reduced to 4 GB and the limitations of other computational resources are ignored.

For each host in the kuma_k0s block, a unique FQDN and IP address must be specified in the ansible_host variable, except for the host in the kuma_lb section. For the host in the kuma_lb section, only the FQDN must be specified. Hosts must be unique within a group.

For a demo installation, you may combine a controller with a worker node. Such a configuration does not provide high availability of the KUMA Core and is only intended for demonstrating the functionality or for testing the software environment.
The minimal configuration that ensures high availability is 3 controllers, 2 worker nodes, and 1 nginx load balancer. In production, we recommend using dedicated worker nodes and controllers. If a cluster controller is under workload and the pod with the KUMA Core is hosted on the controller, if the controller goes down, access to the KUMA Core will be completely lost.

The kuma_k0s block can contain the following sections:

• vars contains variables that apply to all hosts specified in the kuma block.
• сhildren contains settings of the Kubernetes cluster that provides high availability of KUMA.

The following table lists possible variables in the vars section and their descriptions.

List of possible variables in the vars section

[Topic 217908]

Installation on a single server

To install KUMA components on a single server, complete the following steps:

1. Ensure that hardware, software, and installation requirements for KUMA are met.
2. Prepare the single.inventory.yml inventory file.

   Use the single.yml.template inventory file template from the distribution kit to create a single.inventory.yml inventory file and describe the network structure of application components in that file. The installer uses the single.inventory.yml file to deploy KUMA.

3. Install the application.

   Install the application and log in to the web interface using the default credentials.

If necessary, you can move application components to different servers to continue with a distributed configuration.

[Topic 222158]

Preparing the single.inventory.yml inventory file

KUMA components can be installed, updated, and removed in the directory containing the extracted installer by using the Ansible tool and the user-created YML inventory file containing a list of the hosts of KUMA components and other settings. If you want to install all KUMA components on the same server, you must specify the same host for all components in the inventory file.

To create an inventory file for installation on a single server:

1. Copy the archive with the kuma-ansible-installer-<version>.tar.gz installer to the server and extract it using the following command (about 2 GB of disk space is required):

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

2. Go to the KUMA installer directory by executing the following command:

   cd kuma-ansible-installer

3. Copy the single.inventory.yml.template and create an inventory file named single.inventory.yml:

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

4. Edit the settings in the single.inventory.yml inventory file.

   If you want predefined services to be created during the installation, set deploy_example_services to true.

   deploy_example_services: true

   The predefined services will appear only as a result of the initial installation of KUMA. If you are upgrading the system using the same inventory file, the predefined services are not re-created.

5. Replace all kuma.example.com strings in the inventory file with the name of the host on which you want to install KUMA components.

The inventory file is created. Now you can use it to install KUMA on a single server.

We recommend backing up the inventory file that you used to install the program. You can use it to add components to the system or remove KUMA.

Example inventory file for installation on a single server

[Topic 222159]

Installing the program on a single server

You can install all KUMA components on a single server using the Ansible tool and the single.inventory.yml inventory file.

To install Kuma on a single server:

1. Download the kuma-ansible-installer-<build number>.tar.gz KUMA distribution kit to the server and extract it. The archive is extracted into the kuma-ansibleinstaller directory.
2. Go to the directory with the extracted installer.
3. Depending on the type of license activation that you are planning to use, do one of the following:
   • If you want to activate your license with a file, place the file with the license key in <installer directory>/roles/kuma/files/.

     The key file must be named license.key.

     sudo cp <key file>.key <installer directory>/roles/kuma/files/license.key

   • If you want to activate with a license code, go to the next step of the instructions.

     Activation using a license code is available starting with KUMA 3.4. For earlier versions of KUMA, you must activate the license with a file.

4. Run the following command to start the component installation with your prepared single.inventory.yml inventory file:

   sudo ./install.sh single.inventory.yml

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

   If you do not accept the terms and conditions of the End User License Agreement, the application cannot be installed.

   Depending on the type of license activation, running the installer has one of the following results:

   • If you want to activate the license using a file and have placed the file with the license key in "<installer directory>/roles/kuma/files/", running the installer with the "single.inventory.yml" inventory file installs KUMA Core, all services specified in the inventory file, and OOTB resources. If example_services=true is set in the inventory, demo services are installed.
   • If you want to activate with a license code or provide a license file later, running the installer with the "single.inventory.yml" inventory file installs only KUMA Core.

     To install the services, specify the license code on the command line. Then run the postinstall.sh installer with the "single.inventory.yml" inventory file.

     sudo ./postinstall.sh single.inventory.yml

     This creates the specified services. You can select the resources that you want to import from the repository.

6. After the installation is complete, log in to the KUMA web interface and enter the address of the KUMA web interface in the address bar of your browser, then enter your credentials on the login page.

   The address of the KUMA web interface is https://<FQDN of the host where KUMA is installed>:7220.

   Default login credentials:
   - login: admin
   - password: mustB3Ch@ng3d!

   After logging in for the first time, change the password of the admin account

All KUMA components are installed and you are logged in to the web interface.

We recommend saving a backup copy of the inventory file that you used to install the application. You can use this inventory file to add components to the system or remove KUMA.

You can expand the installation to a distributed installation.

[Topic 217917]

Distributed installation

The distributed installation of KUMA involves multiple steps:

1. Verifying that the hardware, software, and installation requirements for KUMA are satisfied.
2. Preparing the control machine.

   The control machine is used during the application installation process to extract and run the installer files.

3. Preparing the target machines.

   The application components are installed on the target machines.

4. Preparing the distributed.inventory.yml inventory file.

   Create an inventory file with a description of the network structure of application components. The installer uses this inventory file to deploy KUMA.

5. Installing the application.

   Install the application and log in to the web interface.

6. Creating services.

   Create the client part of the services in the KUMA web interface and install the server part of the services on the target machines.

   Make sure the KUMA installation is complete before you install KUMA services. We recommend installing services in the following order: storage, collectors, correlators, agents.

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

If necessary, you can change the KUMA web console certificate to your company's certificate.

[Topic 222083]

Preparing the test machine

To prepare the control machine for installing KUMA:

1. Ensure that hardware, software, and installation requirements of the application are met.
2. Generate an SSH key for authentication on the SSH servers of the target machines:

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

   If SSH root access is blocked on the control machine, generate an SSH key for authentication on the SSH servers of the target machines for a user from the sudo group:

   If the user that you want to use does not have sudo rights, add the user to the sudo group:

   usermod -aG sudo user

   ssh-keygen -f /home/<name of the user from the sudo group>/.ssh/id_rsa -N "" -C kuma-ansible-installer

   As a result, the key is generated and saved in the user's home directory. To make the key available during installation, you must specify the full path to the key in the inventory file, in the ansible_ssh_private_key_file setting.

3. Make sure that the control machine has network access to all the target machines by host name and copy the SSH key to each target machine:

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

   If SSH root access is blocked on the control machine and you want to use the SSH key from the home directory of the user from the sudo group, make sure that the control machine has network access to all target machines by host name and copy the SSH key to each target machine:

   ssh-copy-id -i /home/<name of the user in the sudo group>/.ssh/id_rsa <name of the user in the sudo group>@<host name of the control machine>

4. Copy the installer archive kuma-ansible-installer-<version>.tar.gz to the control machine and extract it using the following command (approximately 2 GB of disk space is required):

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

The control machine is prepared for installing KUMA.

[Topic 217955]

Preparing the target machine

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

1. Ensure that hardware, software, and installation requirements are met.
2. Specify the host name. We recommend specifying a FQDN. For example, kuma1.example.com.

   Do 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 application components.

3. Register the target machine in your organization's DNS zone to allow host names to be resolved 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.

4. To get the hostname that you must specify when installing KUMA, run the following command and record the result:

   hostname -f

   The control machine must be able to access the target machine using this name.

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

[Topic 222085]

Preparing the distributed.inventory.yml inventory file

To create the distributed.inventory.yml inventory file:

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

   cd kuma-ansible-installer

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

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

3. Edit the settings in the distributed.inventory.yml.

We recommend backing up the inventory file that you used to install the program. You can use it to add components to the system or remove KUMA.

Example inventory file for distributed installation

[Topic 217914]

Installing the program in a distributed configuration

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

To install KUMA:

1. On the control machine, go to the directory containing the extracted installer.

   cd kuma-ansible-installer

2. Depending on the type of license activation that you plan to use, do one of the following:
   • If you want to activate your license with a file, place the file with the license key in <installer directory>/roles/kuma/files/.

     The key file must be named license.key.

     sudo cp <key file>.key <installer directory>/roles/kuma/files/license.key

   • If you want to activate with a license code, go to the next step of these instructions.
3. From the directory with the extracted installer, start the installation of components using the prepared inventory file, distributed.inventory.yml:

   sudo ./install.sh distributed.inventory.yml

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

   If you do not accept the terms and conditions of the End User License Agreement, the application cannot be installed.

   Depending on the type of license activation, the installer produces one of the following results:

   • If you want to activate the license using a file and have placed the file with the license key in "<installer directory>/roles/kuma/files/", running the installer with the "distributed.inventory.yml" inventory file installs KUMA Core, all services specified in the inventory file, and OOTB resources.
   • If you want to activate with a license code or provide a license file later, running the installer with the "distributed.inventory.yml" inventory file installs only KUMA Core.

     To install the services, specify the license code on the command line. Then run the postinstall.sh installer with the "distrtibuter.inventory.yml" inventory file.

     sudo ./postinstall.sh distributed.inventory.yml

     This creates the specified services. You can select the resources that you want to import from the repository.

5. After the installation is complete, log in to the KUMA web interface and enter the address of the KUMA web interface in the address bar of your browser, then enter your credentials on the login page.

   The address of the KUMA web interface is https://<FQDN of the host where KUMA is installed>:7220.

   Default login credentials:
   - login: admin
   - password: mustB3Ch@ng3d!

   After logging in for the first time, change the password of the admin account

All KUMA components are installed and you are logged in to the web interface.

We recommend saving a backup copy of the inventory file that you used to install the application. You can use this inventory file to add components to the system or remove KUMA.

[Topic 244396]

Distributed installation in a high availability configuration

The high availability configuration of KUMA involves deploying the KUMA Core on a Kubernetes cluster and using an external TCP traffic balancer.

To create a high availability KUMA installation, use the kuma-ansible-installer-ha-<build number>.tar.gz installer and prepare the k0s.inventory.yml inventory file by specifying the configuration of your cluster. For a new installation in a high availability configuration, OOTB resources are always imported. You can also perform an installation with deployment of demo services. To do this, set "deploy_example_services: true" in the inventory file.

You can deploy KUMA Core on a Kubernetes cluster in the following ways:

• Install KUMA on a Kubernetes cluster from scratch.
• Migrate the Core of an existing KUMA installation to a Kubernetes cluster.

Minimum configuration

Kubernetes has 2 node roles:

• Controllers (control-plane). Nodes with this role manage the cluster, store metadata, and balance the workload.
• Workers (worker). Nodes with this role bear the workload by hosting KUMA processes.

To deploy KUMA in a high availability configuration, you need:

• 3 dedicated controllers
• 2 worker nodes
• 1 TCP balancer

You must not use the balancer as the control machine for running the KUMA installer.

To ensure the adequate performance of the KUMA Core in Kubernetes, you must allocate 3 dedicated nodes that have only the controller role. This will provide high availability for the Kubernetes cluster itself and will ensure that the workload (KUMA processes and other processes) cannot affect the tasks involved in managing the Kubernetes cluster. If you are using virtualization tools, make sure that the nodes are hosted on different physical servers and that these physical servers are not being used as worker nodes.

For a demo installation of KUMA, you may combine the controller and worker roles. However, if you are expanding an installation to a distributed installation, you must reinstall the entire Kubernetes cluster and allocate 3 dedicated nodes with the controller role and at least 2 nodes with the worker role. KUMA cannot be upgraded to later versions if any of the nodes combine the controller and worker roles.

[Topic 244399]

Additional requirements for deploying KUMA Core in Kubernetes

If you plan to protect KUMA's network infrastructure using Kaspersky Endpoint Security for Linux, first install KUMA in the Kubernetes cluster and only then deploy Kaspersky Endpoint Security for Linux. When updating or removing KUMA, you must first stop Kaspersky Endpoint Security for Linux using the following command:

systemctl stop kesl

When you install KUMA in a high availability configuration, the following requirements must be met:

• General application installation requirements.
• The hosts that you plan to use for Kubernetes cluster nodes must not use IP addresses from the following Kubernetes ranges:
  • serviceCIDR: 10.96.0.0/12
  • podCIDR: 10.244.0.0/16

  Traffic to proxy servers must excluded for the IP addresses from these ranges.

• Each host must have a unique ID (/etc/machine-id).
• The firewalld or uwf firewall management tool must be installed and enabled on the hosts for adding rules to iptables.
• The nginx load balancer must be installed and configured (for details, please refer to the nginx load balancer documentation). You can install the nginx load balancer using one of the following commands:
  • sudo yum install nginx (for Oracle Linux)
  • sudo apt install nginx-full (for Astra Linux)
  • sudo apt install nginx libnginx-mod-stream (for Ubuntu)
  • sudo yum install nginx nginx-all-modules (for RED OS)

  If you want the nginx load balancer to be configured automatically during the KUMA installation, install the nginx load balancer and allow SSH access to it in the same way as for the Kubernetes cluster hosts.

  Example of an automatically created nginx configuration

  The installer creates the /etc/nginx/kuma_nginx_lb.conf configuration file. An example of this file contents is provided below. The upstream sections are generated dynamically and contain the IP addresses of the Kubernetes cluster controllers (in the example, 10.0.0.2-4 in the upstream kubeAPI_backend, upstream konnectivity_backend, controllerJoinAPI_backend sections) and the IP addresses of the worker nodes (in the example 10.0.1.2-3), for which the inventory file contains the "kaspersky.com/kuma-ingress=true" value for the extra_args variable.

  The "include /etc/nginx/kuma_nginx_lb.conf;" line must be added to the end of the /etc/nginx/nginx.conf file to apply the generated configuration file. If you have a large number of active services and users, you may need to increase the limit of open files in the nginx.conf settings.

  Configuration file example:

  # Ansible managed

  #

  # LB KUMA cluster

  #

  stream {

      server {

          listen          6443;

          proxy_pass      kubeAPI_backend;

      }

      server {

          listen          8132;

          proxy_pass      konnectivity_backend;

      }

      server {

          listen          9443;

          proxy_pass      controllerJoinAPI_backend;

      }

      server {

          listen          7209;

          proxy_pass      kuma-core-hierarchy_backend;

          proxy_timeout   86400s;

      }

      server {

          listen          7210;

          proxy_pass      kuma-core-services_backend;

          proxy_timeout   86400s;

      }

      server {

          listen          7220;

          proxy_pass      kuma-core-ui_backend;

          proxy_timeout   86400s;

      }

      server {

          listen          7222;

          proxy_pass      kuma-core-cybertrace_backend;

          proxy_timeout   86400s;

      }

      server {

          listen          7223;

          proxy_pass      kuma-core-rest_backend;

          proxy_timeout   86400s;

      }

      upstream kubeAPI_backend {

          server 10.0.0.2:6443;

          server 10.0.0.3:6443;

          server 10.0.0.4:6443;

      }

      upstream konnectivity_backend {

          server 10.0.0.2:8132;

          server 10.0.0.3:8132;

          server 10.0.0.4:8132;

      }

      upstream controllerJoinAPI_backend {

          server 10.0.0.2:9443;

          server 10.0.0.3:9443;

          server 10.0.0.4:9443;

      }

      upstream kuma-core-hierarchy_backend {

          server 10.0.1.2:7209;

          server 10.0.1.3:7209;

      }

      upstream kuma-core-services_backend {

          server 10.0.1.2:7210;

          server 10.0.1.3:7210;

      }

      upstream kuma-core-ui_backend {

          server 10.0.1.2:7220;

          server 10.0.1.3:7220;

      }

      upstream kuma-core-cybertrace_backend {

          server 10.0.1.2:7222;

          server 10.0.1.3:7222;

      }

      upstream kuma-core-rest_backend {

          server 10.0.1.2:7223;

          server 10.0.1.3:7223;

  }

   worker_rlimit_nofile 1000000;

  events {

  worker_connections 20000;

  }

  # worker_rlimit_nofile is the limit on the number of open files (RLIMIT_NOFILE) for workers. This is used to raise the limit without restarting the main process.

  # worker_connections is the maximum number of connections that a worker can open simultaneously.

• An access key from the device on which KUMA is installed must be added to the nginx load balancer server.
• On the nginx load balancer server, the SELinux module must be disabled in the operating system.
• The tar, systemctl packages are installed on the hosts.

During KUMA installation, the hosts are automatically checked to see if they meet the following hardware requirements:

• CPU cores (threads): 12 or more
• RAM: 22,528 MB or more
• Free disk space in the /opt partition: 1000 GB or more.
• For an installation from scratch, the /var/lib partition must have at least 32 GB of free space. If the cluster already has been installed on this node, the size of the required free space is reduced by the size of the /var/lib/k0s directory.

If these conditions are not satisfied, the installation is aborted. For a demo installation, you can disable the check of these conditions by setting low_resources: true in the inventory file.

Additional requirements when installing on Astra Linux or Ubuntu operating systems.

• Installing KUMA in a high availability configuration is supported for Astra Linux Special Edition RUSB.10015-01 (2022-1011SE17MD, update 1.7.2.UU.1). Kernel version 5.15.0.33 or later is required.
• The following packages must be installed on the machines intended for deploying a Kubernetes cluster:
  • open-iscsi
  • wireguard
  • wireguard-tools

  To install the packages, run the following command:

  sudo apt install open-iscsi wireguard wireguard-tools

Additional requirements when installing on the Oracle Linux, RED OS, or Red Hat Enterprise Linux operating systems

The following packages must be installed on the machines intended for deploying the Kubernetes cluster:

• iscsi-initiator-utils
• wireguard-tools

Before installing the packages on Oracle Linux, you must add the EPEL repository as a source of packages using one of the following commands:

• sudo yum install oracle-epel-release-el8 (for Oracle Linux 8)
• sudo yum install oracle-epel-release-el9 (for Oracle Linux 9)

To install the packages, run the following command:

sudo yum install iscsi-initiator-utils wireguard-tools

[Topic 269330]

Installing KUMA on a Kubernetes cluster from scratch

The distributed installation of KUMA involves several steps:

1. Verifying that the hardware, software, and installation requirements for KUMA are satisfied.
2. Preparing the control machine.

   The control machine is used during the application installation process to extract and run the installer files.

3. Preparing the target machines.

   The program components are installed on the target machines.

4. Preparing the k0s.inventory.yml inventory file.

   Create an inventory file with a description of the network structure of program components. The installer uses this inventory file to deploy KUMA.

5. Installing the program.

   Install the application and log in to the web interface.

6. Creating services.

   Create the client part of the services in the KUMA web interface and install the server part of the services on the target machines.

   Make sure the KUMA installation is complete before you install KUMA services. We recommend installing services in the following order: storage, collectors, correlators, agents.

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

If necessary, you can change the certificate of KUMA web console to use your company's certificate.

[Topic 269332]

Preparing the test machine

To prepare the control machine for installing KUMA:

1. Ensure that hardware, software, and installation requirements of the application are met.
2. Generate an SSH key for authentication on the SSH servers of the target machines:

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

   If SSH root access is blocked on the control machine, generate an SSH key for authentication on the SSH servers of the target machines for a user from the sudo group:

   If the user that you want to use does not have sudo rights, add the user to the sudo group:

   usermod -aG sudo user

   ssh-keygen -f /home/<name of the user from the sudo group>/.ssh/id_rsa -N "" -C kuma-ansible-installer

   As a result, the key is generated and saved in the user's home directory. To make the key available during installation, you must specify the full path to the key in the inventory file, in the ansible_ssh_private_key_file setting.

3. Make sure that the control machine has network access to all the target machines by host name and copy the SSH key to each target machine:

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

   If SSH root access is blocked on the control machine and you want to use the SSH key from the home directory of the user from the sudo group, make sure that the control machine has network access to all target machines by host name and copy the SSH key to each target machine:

   ssh-copy-id -i /home/<name of the user in the sudo group>/.ssh/id_rsa <name of the user in the sudo group>@<host name of the test machine>

4. Copy the kuma-ansible-installer-ha-<version number> .tar.gz installer archive to the control machine and extract it using the following command:

   sudo tar -xpf kuma-ansible-installer-ha-<version number>.tar.gz

The test machine is ready for the KUMA installation.

[Topic 269334]

Preparing the target machine

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

1. Ensure that hardware, software, and installation requirements are met.
2. Specify the host name. We recommend specifying a FQDN. For example, kuma1.example.com.

   Do 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 application components.

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

   The option of using the /etc/hosts file is not available when the Core is deployed in Kubernetes.

4. To get the hostname that you must specify when installing KUMA, run the following command and record the result:

   hostname -f

   The control machine must be able to access the target machine using this name.

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

[Topic 269310]

Preparing the k0s.inventory.yml inventory file

Expand all | Collapse all

To create the k0s.inventory.yml inventory file:

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

   cd kuma-ansible-installer-ha

2. Copy the k0s.inventory.yml.template file to create the expand.inventory.yml inventory file:

   cp k0s.inventory.yml.template k0s.inventory.yml

3. Edit the inventory file settings in k0s.inventory.yml.

   Example inventory file for a demo installation with the Core in Kubernetes

   all:

   vars:

   ansible_connection: ssh

   ansible_user: root

   deploy_to_k8s: true

   need_transfer: false

   generate_etc_hosts: false

   deploy_example_services: true

   kuma:

   children:

   kuma_core:

   hosts:

   kuma.example.com:

   mongo_log_archives_number: 14

   mongo_log_frequency_rotation: daily

   mongo_log_file_size: 1G

   kuma_collector:

   hosts:

   kuma.example.com:

   kuma_correlator:

   hosts:

   kuma.example.com:

   kuma_storage:

   hosts:

   kuma.example.com:

   shard: 1

   replica: 1

   keeper: 1

   kuma_k0s:

   children:

   kuma_control_plane_master_worker:

   hosts:

   kuma-cpw.example.com:

   ansible_host: 10.0.2.11

   extra_args: "--labels=kaspersky.com/kuma-core=true,kaspersky.com/kuma-ingress=true,node.longhorn.io/create-default-disk=true"

   For a demo installation, set deploy_example_services: true. KUMA will deploy demo services on the specified hosts and assign the shard, replica, and keeper roles to the specified host; configuring these roles in the KUMA web interface is not necessary for a demo installation.

   Example inventory file for a distributed installation in a high availability configuration with 3 controllers, 2 worker nodes, and 1 balancer

   all:

   vars:

   ansible_connection: ssh

   ansible_user: root

   deploy_to_k8s: true

   need_transfer: false

   generate_etc_hosts: false

   deploy_example_services: false

   kuma:

   children:

   kuma_core:

   hosts:

   kuma-core.example.com:

   mongo_log_archives_number: 14

   mongo_log_frequency_rotation: daily

   mongo_log_file_size: 1G

   kuma_collector:

   hosts:

   kuma-collector.example.com:

   kuma_correlator:

   hosts:

   kuma-correlator.example.com:

   kuma_storage:

   hosts:

   kuma-storage-cluster1.server1.example.com

   kuma-storage-cluster1.server2.example.com

   kuma-storage-cluster1.server3.example.com

   kuma-storage-cluster1.server4.example.com

   kuma-storage-cluster1.server5.example.com

   kuma-storage-cluster1.server6.example.com

   kuma-storage-cluster1.server7.example.com

   kuma_k0s:

   children:

   kuma_lb:

   hosts:

   kuma-lb.example.com:

   kuma_managed_lb: true

   kuma_control_plane_master:

   hosts:

   kuma_cpm.example.com:

   ansible_host: 10.0.1.10

   kuma_control_plane_master_worker:

   kuma_control_plane:

   hosts:

   kuma_cp2.example.com:

   ansible_host: 10.0.1.11

   kuma_cp3.example.com:

   ansible_host: 10.0.1.12

   kuma_control_plane_worker:

   kuma_worker:

   hosts:

   kuma-w1.example.com:

   ansible_host: 10.0.2.11

   extra_args: "--labels=kaspersky.com/kuma-core=true,kaspersky.com/kuma-ingress=true,node.longhorn.io/create-default-disk=true"

   kuma-w2.example.com:

   ansible_host: 10.0.2.12

   extra_args: "--labels=kaspersky.com/kuma-core=true,kaspersky.com/kuma-ingress=true,node.longhorn.io/create-default-disk=true"

   For such a configuration, specify the parameters as follows: need_transfer: false, deploy_example_services: false; in the kuma_storage section, list the servers for the storage cluster. After the installation is complete, you can use the KUMA web interface to assign the shard, replica and keeper roles to the servers specified in the inventory.

   Example inventory file for migrating the Core from a distributed installation to a Kubernetes cluster to ensure high availability

   all:

   vars:

   ansible_connection: ssh

   ansible_user: root

   deploy_to_k8s: true

   need_transfer: true

   generate_etc_hosts: false

   deploy_example_services: false

   kuma:

   children:

   kuma_core:

   hosts:

   kuma-core.example.com:

   mongo_log_archives_number: 14

   mongo_log_frequency_rotation: daily

   mongo_log_file_size: 1G

   kuma_collector:

   hosts:

   kuma-collector.example.com:

   kuma_correlator:

   hosts:

   kuma-correlator.example.com:

   kuma_storage:

   hosts:

   kuma-storage-cluster1.server1.example.com

   kuma-storage-cluster1.server2.example.com

   kuma-storage-cluster1.server3.example.com

   kuma-storage-cluster1.server4.example.com

   kuma-storage-cluster1.server5.example.com

   kuma-storage-cluster1.server6.example.com

   kuma-storage-cluster1.server7.example.com

   kuma_k0s:

   children:

   kuma_lb:

   hosts:

   kuma-lb.example.com:

   kuma_managed_lb: true

   kuma_control_plane_master:

   hosts:

   kuma_cpm.example.com:

   ansible_host: 10.0.1.10

   kuma_control_plane_master_worker:

   kuma_control_plane:

   hosts:

   kuma_cp2.example.com:

   ansible_host: 10.0.1.11

   kuma_cp3.example.com:

   ansible_host: 10.0.1.12

   kuma_control_plane_worker:

   kuma_worker:

   hosts:

   kuma-w1.example.com:

   ansible_host: 10.0.2.11

   extra_args: "--labels=kaspersky.com/kuma-core=true,kaspersky.com/kuma-ingress=true,node.longhorn.io/create-default-disk=true"

   kuma-w2.example.com:

   ansible_host: 10.0.2.12

   extra_args: "--labels=kaspersky.com/kuma-core=true,kaspersky.com/kuma-ingress=true,node.longhorn.io/create-default-disk=true"

   The kuma_core, kuma_collector, kuma_correlator, kuma_storage sections of your k0s.inventory.yml inventory file must contain the same hosts that were used in the distributed.inventory.yml file when KUMA was upgraded from version 2.1.3 to version 3.0.3 and then to version 3.2, or when a new installation was performed. In the k0s.inventory.yml inventory file, set deploy_to_k8s: true, need_transfer: true, deploy_example_services: false.