Тип sql

KUMA поддерживает работу с несколькими типами баз данных. При создании коннектора с типом sql вам нужно указать значения для общих параметров коннектора и индивидуальных параметров подключения к базе данных. Доступные параметры коннектора с типом sql описаны в таблицах ниже.

Вкладка Основные параметры

Параметр	Описание
Название	Уникальное имя ресурса. Максимальная длина имени: до 128 символов в кодировке Unicode. Обязательный параметр.
Тип	Тип коннектора. Вам нужно выбрать sql. Обязательный параметр.
Тенант	Название тенанта, которому принадлежит ресурс. Обязательный параметр.
Запрос по умолчанию	SQL-запрос, который выполняется при подключении к базе данных. Обязательный параметр.
Переподключаться к БД каждый раз при отправке запроса	Коннектор переподключается к базе данных каждый раз при отправке запроса. По умолчанию флажок снят.
Интервал запросов, сек.	Интервал выполнения SQL-запросов в секундах. Значение по умолчанию: 10 секунд.
Описание	Описание ресурса. Максимальная длина описания: до 4000 символов в кодировке Unicode.

Раздел Соединение

Параметр

Описание

Тип базы данных

Тип базы данных для подключения. При выборе типа базы данных в поле URL отображается префикс, соответствующий протоколу взаимодействия. Например, для типа базы данных ClickHouse в поле URL отображается префикс clickhouse://.

Секрет отдельно

Просмотр информации о подключении. Если флажок установлен, в окне отображаются следующие параметры:

URL – URL-адрес подключения.
Секрет – секрет типа credentials.
Вы сможете просматривать информацию о подключении, и вам не придется повторно создавать большое количество подключений при изменении пароля учетной записи, которую вы использовали для подключений.

Если флажок снят, доступно только поле URL для выбора или создания секрета типа urls.

По умолчанию флажок снят.

URL

Поле для указания одного из следующих значений:

Если вы сняли флажок Секрет отдельно, вам нужно указать в поле секрет urls, в котором хранится список URL-адресов для подключения к базе данных.
При необходимости вы можете изменить или создать секрет.
Чтобы создать секрет:
1. Нажмите на кнопку .
  Откроется окно секрета.
2. Укажите значения для следующих параметров:
  1. Название – имя добавляемого секрета.
  2. Тип. Значение установлено по умолчанию, его редактирование недоступно.
  3. URL – URL-адрес базы данных.
    Вам требуется учитывать, что для подключения к каждому типу базы данных используется свой формат URL-адреса.
    
    Доступные форматы URL-адресов:
    - Для SQLite:
      sqlite3://file:<file_path>
      
      В качестве плейсхолдера используется знак вопроса: ?.
    - Для MsSQL:
      sqlserver://<user>:<password>@<server:port>/<instance_name>?database=<database> (рекомендуется)
      sqlserver://<user>:<password>@<server>?database=<database>
      В качестве плейсхолдера используются символы @p1.
    - Для MySQL:
      mysql://<user>:<password>@tcp(<server>:<port>)/<database>
      
      В качестве плейсхолдера используются символы %s.
    - Для PostgreSQL:
      postgres://<user>:<password>@<server>/<database>?sslmode=disable
      
      В качестве плейсхолдера используются символы $1.
    - Для Cockroach:
      postgres://<user>:<password>@<server>:<port>/<database>?sslmode=disable
      В качестве плейсхолдера используются символы $1.
    - Для Firebird:
      firebirdsql://<user>:<password>@<server>:<port>/<database>
      
      В качестве плейсхолдера используется знак вопроса: ?.
  4. Описание – дополнительная информация о секрете.
3. При необходимости нажмите на кнопку Добавить и укажите дополнительный URL-адрес. В этом случае при недоступности одного URL-адреса программа подключается к следующему URL-адресу, указанному в списке адресов.
4. Нажмите на кнопку Сохранить.
Чтобы изменить секрет:
1. Нажмите на кнопку .
  Откроется окно секрета.
2. Укажите значения для параметров, которые требуется изменить.
  Вы можете изменить значения для следующих параметров:
  1. Название – имя добавляемого секрета.
  2. URL – URL-адрес базы данных.
    Вам нужно учитывать, что для подключения к каждому типу базы данных используется свой формат URL-адреса.
    
    Доступные форматы URL-адресов:
    - Для SQLite:
      sqlite3://file:<file_path>
      
      В качестве плейсхолдера используется знак вопроса: ?.
    - Для MsSQL:
      sqlserver://<user>:<password>@<server:port>/<instance_name>?database=<database> (рекомендуется)
      sqlserver://<user>:<password>@<server>?database=<database>
      В качестве плейсхолдера используются символы @p1.
    - Для MySQL:
      mysql://<user>:<password>@tcp(<server>:<port>)/<database>
      
      В качестве плейсхолдера используется символ ?.
    - Для PostgreSQL:
      postgres://<user>:<password>@<server>/<database>?sslmode=disable
      
      В качестве плейсхолдера используются символы $1.
    - Для Cockroach:
      postgres://<user>:<password>@<server>:<port>/<database>?sslmode=disable
      
      В качестве плейсхолдера используются символы $1.
    - Для Firebird:
      firebirdsql://<user>:<password>@<server>:<port>/<database>
      
      В качестве плейсхолдера используется знак вопроса: ?.
  3. Описание – дополнительная информация о секрете.
3. При необходимости нажмите на кнопку Добавить и укажите дополнительный URL-адрес. В этом случае при недоступности одного URL-адреса программа подключается к следующему URL-адресу, указанному в списке URL-адресов.
4. Нажмите на кнопку Сохранить.
При создании подключений могут неправильно обрабатываться строки с учетными данными, содержащими специальные символы. Если при создании подключения возникает ошибка, но вы уверены в том, что указали правильные значения параметров, укажите специальные символы в процентной кодировке.

Коды специальных символов

!

#

$

%

&

'

(

)

*

+

%21

%23

%24

%25

%26

%27

%28

%29

%2A

%2B

,

/

:

;

=

?

@

[

]

\

%2C

%2F

%3A

%3B

%3D

%3F

%40

%5B

%5D

%5C

Следующие специальные символы не поддерживаются в паролях доступа к базам SQL: пробел, [, ], :, /, #, %, \.
Если вы установили флажок Секрет отдельно, вам нужно указать в поле URL-адрес подключения. URL-адрес используется с секретом типа credentials.

Секрет

Секрет типа credentials. Этот параметр доступен, если вы установили флажок Секрет отдельно.

Авторизация

Тип авторизации при подключении к указанному URL-адресу. Доступные значения:

Выключена. Значение по умолчанию.
Обычная. При выборе этого значения вам нужно указать секрет, содержащий данные учетной записи пользователя для авторизации при подключении к коннектору.
PublicPKI. При выборе этого значения вам нужно указать секрет, содержащий закрытый ключ PEM, закодированный в base64, и открытый ключ.

Режим TLS

Режим шифрования TLS. Доступные значения:

Выключено – не использовать шифрование TLS. Значение по умолчанию.
Включено – использовать шифрование TLS, но без верификации сертификатов.
Нестандартный CA – использовать шифрование TLS с верификацией сертификата, подписанного центром сертификации. При выборе этого значения вам нужно выбрать секрет с сертификатом, подписанным центром сертификации, в раскрывающемся списке Нестандартный CA.
Как создать сертификат, подписанный центром сертификации?
Вы можете создать сертификат, подписанный центром сертификации, на сервере Ядра KUMA (в примерах команд ниже используется OpenSSL).

Чтобы создать сертификат, подписанный центром сертификации:
1. Создайте ключ, который будет использоваться центром сертификации, например:
  openssl genrsa -out ca.key 2048
2. Создайте сертификат для созданного ключа, например:
  openssl req -new -x509 -days 365 -key ca.key -subj "/CN=<общее имя хоста центра сертификации>" -out ca.crt
3. Создайте приватный ключ и запрос на его подписание в центре сертификации, например:
  openssl req -newkey rsa:2048 -nodes -keyout server.key -subj "/CN=<общее имя хоста сервера KUMA>" -out server.csr
4. Создайте сертификат, подписанный центром сертификации. Вам нужно включить в переменную subjectAltName доменные имена или IP-адреса сервера, для которого вы создаете сертификат, например:
  openssl x509 -req -extfile <(printf "subjectAltName=DNS:domain1.ru,DNS:domain2.com,IP:192.168.0.1") -days 365 -in server.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out server.crt
5. Загрузите созданный сертификат server.crt в веб-интерфейсе KUMA в секрет типа certificate, после чего выберите секрет типа certificate в раскрывающемся списке Нестандартный CA.
При использовании шифрования TLS вы не можете указать IP-адрес в качестве URL-адреса.

Особенности работы режима шифрования TLS

Доступные версии протокола TLS для коннектора типа sql определяются драйвером базы данных, используемом для подключения. Драйверы баз данных добавлены в KUMA статически.

В зависимости от используемой базы данных режим TLS может быть указан в строке подключения или в файле конфигурации. Если режим TLS не указан явно в конфигурации подключения, драйвер поддерживает криптонаборы и версию протокола TLS, которые определены для него в библиотеке std языка Go.

Версии 1.0 и 1.1 протокола TLS в языке Go отключены. Подробнее см. https://go.dev/doc/go1.18#tls10.

Столбец идентификатора

Название столбца, содержащего идентификатор для каждой строки таблицы.

Обязательный параметр.

Начальное значение идентификатора

Значение в столбце идентификатора для определения строки, с которой требуется начать считывание данных из SQL-таблицы.

Запрос

Дополнительный SQL-запрос, который выполняется вместо SQL-запроса по умолчанию.

Интервал запросов, сек.

Интервал выполнения SQL-запросов в секундах. Указанный интервал используется вместо интервала, указанного по умолчанию для коннектора. Значение по умолчанию: 10 секунд.

Описание

Описание ресурса. Максимальная длина описания: до 4000 символов в кодировке Unicode.

Вкладка Дополнительные параметры

Параметр	Описание
Кодировка символов	Кодировка символов. Значение по умолчанию: `UTF-8`. KUMA конвертирует ответы SQL в кодировку UTF-8. Вы можете настроить SQL-сервер на отправку ответов в кодировке UTF-8 или выбрать их кодировку на стороне KUMA.
Отладка	Логирование ресурса. По умолчанию переключатель выключен.

Параметр

Описание

Кодировка символов

Кодировка символов. Значение по умолчанию: UTF-8.

KUMA конвертирует ответы SQL в кодировку UTF-8. Вы можете настроить SQL-сервер на отправку ответов в кодировке UTF-8 или выбрать их кодировку на стороне KUMA.

Отладка

Логирование ресурса. По умолчанию переключатель выключен.

В рамках одного коннектора вы можете создать подключение для нескольких поддерживаемых баз данных. Если коллектор с коннектором типа sql не удаётся запустить, вам нужно проверить, пуст ли state-файл /opt/kaspersky/kuma/collector/<идентификатор коллектора>/sql/state-<идентификатор файла>. Если state-файл пуст, вам нужно его удалить и перезапустить коллектор.

Поддерживаемые типы SQL и особенности их использования

Поддерживаются следующие типы SQL:

MSSQL.
Например:
- sqlserver://{user}:{password}@{server:port}/{instance_name}?database={database}
Мы рекомендуем использовать этот вариант URL.
- sqlserver://{user}:{password}@{server}?database={database}
В качестве плейсхолдера в SQL-запросе используются символы @p1.

Если вы хотите подключиться с доменными учетными данными, укажите имя учетной записи в формате <домен>%5C<пользователь>. Например: sqlserver://domain%5Cuser:password@ksc.example.com:1433/SQLEXPRESS?database=KAV.
MySQL.
Например:

mysql://{user}:{password}@tcp({server}:{port})/{database}

В качестве плейсхолдера в SQL-запросе используются символ ?.
MariaDB.
Например:

mysql://{user}:{password}@tcp({server}:{port})/{database}

В качестве плейсхолдера в SQL-запросе используются символ ?.
PostgreSQL.
Например: postgres://{user}:{password}@{server}/{database}?sslmode=disable

В качестве плейсхолдера в SQL-запросе используются символы $1.
CockroachDB.
Например:

postgres://{user}:{password}@{server}:{port}/{database}?sslmode=disable

В качестве плейсхолдера в SQL-запросе используются символы $1.
SQLite3.
Например:

sqlite3://file:{file_path}

В качестве плейсхолдера в SQL-запросе используется знак вопроса: ?.

При обращении к SQLite3, если начальное значение идентификатора используется в формате datetime, вам нужно добавить преобразование даты с помощью функции sqlite datetime в SQL-запрос. Например:

select * from connections where datetime(login_time) > datetime(?, 'utc') order by login_time

В этом примере connections – это таблица SQLite, а значение переменной ? берется из поля Начальное значение идентификатора, и его требуется указывать в формате {<дата>}T{<время>}Z, например 2021-01-01T00:10:00Z).
Oracle DB.
Начиная с версии 2.1.3 KUMA использует новый драйвер для подключения к oracle. При обновлении KUMA переименует секрет для подключения в oracle-deprecated и коннектор продолжит работу. Если после запуска коллектора с типом драйвера oracle-deprecated не удается получить события, создайте новый секрет с драйвером oracle и используйте его для подключения. Мы рекомендуем использовать новый драйвер.

Пример URL секрета с новым драйвером oracle:

oracle://{user}:{password}@{server}:{port}/{service_name}

oracle://{user}:{password}@{server}:{port}/?SID={SID_VALUE}

Если время выполнения запроса превышает 30 секунд. драйвер oracle прерывает SQL-запрос и в журнале коллектора появится ошибка user requested cancel of current operation. Для увеличения времени выполнения SQL-запроса укажите в строке подключения значение параметра timeout в секундах, например:

oracle://{user}:{password}@{server}:{port}/{service_name}?timeout=300

Пример URL секрета с прежним драйвером oracle-deprecated:

oracle-deprecated://{user}/{password}@{server}:{port}/{service_name}

В качестве плейсхолдера в SQL-запросе используется переменная :val.

При обращении к Oracle DB, если начальное значение идентификатора используется в формате datetime, требуется учитывать тип поля в базе данных и при необходимости добавить дополнительные преобразования строки со временем в SQL-запросе для обеспечения правильной работы SQL-коннектора. Например, если в базе создана таблица Connections, в которой есть поле login_time, возможны следующие преобразования:
- Если у поля login_time тип TIMESTAMP, в зависимости от параметров базы данных в поле login_time может быть указано значение в формате YYYY-MM-DD HH24:MI:SS, например 2021-01-01 00:00:00. В этом случае вам нужно указать значение 2021-01-01T00:00:00Z в поле Начальное значение идентификатора, а в SQL-запросе произвести преобразование с помощью функции to_timestamp, например:
  select * from connections where login_time > to_timestamp(:val, 'YYYY-MM-DD"T"HH24:MI:SS"Z"')
- Если у поля login_time тип TIMESTAMP WITH TIME ZONE, в зависимости от параметров базы данных в поле login_time может быть указано значение в формате YYYY-MM-DD"T"HH24:MI:SSTZH:TZM, например 2021-01-01T00:00:00+03:00. В этом случае вам нужно указать значение 2021-01-01T00:00:00+03:00 в поле Начальное значение идентификатора, а в SQL-запросе произвести преобразование с помощью функции to_timestamp_tz, например:
  select * from connections_tz where login_time > to_timestamp_tz(:val, 'YYYY-MM-DD"T"HH24:MI:SSTZH:TZM')
  
  Подробнее о функциях to_timestamp и to_timestamp_tz см. в официальной документации Oracle.
Для обращения к Oracle DB вам нужно установить пакет Astra Linux libaio1.
Firebird® SQL.
Например:

firebirdsql://{user}:{password}@{server}:{port}/{database}

В качестве плейсхолдера в SQL-запросе используется знак вопроса: ?.

Если возникает проблема подключения к firebird на Windows, используйте полный путь до файла с базой данных, например:

firebirdsql://{user}:{password}@{server}:{port}/C:\Users\user\firebird\db.FDB
ClickHouse.
При использовании шифрования TLS по умолчанию коннектор работает с ClickHouse только по порту 9000. Если шифрование TLS не используется, по умолчанию коннектор работает с ClickHouse только по порту 9440. Если на сервере с ClickHouse настроен режим шифрования TLS, а в параметрах коннектора в раскрывающемся списке Режим TLS выбрано Выключено или наоборот, соединение с базой данных не будет установлено.

Если вы хотите подключиться к ClickHouse KUMA, вам нужно в параметрах коннектора с типом SQL указать тип секрета PublicPki, который содержит закрытый ключ PEM, закодированный в base64, и открытый ключ.

В параметрах коннектора с типом SQL для типа соединения ClickHouse вам нужно выбрать Выключено в раскрывающемся списке Режим TLS. Это значение недопустимо указывать, если для аутентификации используется сертификат. Если в раскрывающемся списке Режим TLS вы выбираете Нестандартный CA, в поле Столбец идентификатора вам нужно указать ID секрета типа certificate. Вам также нужно выбрать одно из следующих значений в раскрывающемся списке Тип Авторизации:
- Выключено. При выборе этого значения вам нужно оставить пустым значение в поле Столбец идентификатора.
- Обычная. Вам нужно выбрать это значение, если установлен флажок Секрет отдельно и в поле Столбец идентификатора указан ID секрета типа credentials.
- PublicPki. Вам нужно выбрать это значение, если установлен флажок Секрет отдельно и в поле Столбец идентификатора указан ID секрета типа PublicPki.
Флажок Секрет отдельно используется, чтобы можно было указать URL отдельно, а не в секрете.

В SQL-запросах поддерживается последовательный запрос сведений из базы данных. Например, если в поле Запрос указать SQL-запрос select * from <название таблицы с данными> where id > <плейсхолдер>, при первом обращении к таблице в качестве значения плейсхолдера будет использоваться значение поля Начальное значение идентификатора. При этом в сервисе, в котором используется SQL-коннектор, сохраняется идентификатор последней прочитанной записи, и во время следующего обращения к базе данных в качестве значения плейсхолдера в запросе будет использоваться идентификатор этой записи.

Примеры SQL-запросов

В начало