Тип sql
KUMA поддерживает работу с несколькими типами баз данных.
При создании коннектора вам требуется задать значения для общих параметров коннектора и индивидуальных параметров подключения к базе данных.
Для коннектора на вкладке Основные параметры вам требуется задать значения следующих параметров:
- Название (обязательно) – уникальное имя ресурса. Должно содержать от 1 до 128 символов в кодировке Unicode.
- Тип (обязательно) – тип коннектора, sql.
- Тенант (обязательно) – название тенанта, которому принадлежит ресурс.
- Запрос по умолчанию (обязательно) – SQL-запрос, который выполняется при подключении к базе данных.
- Переподключаться к БД каждый раз при отправке запроса – по умолчанию флажок снят.
- Интервал запросов, сек. – интервал выполнения SQL-запросов. Указывается в секундах. Значение по умолчанию: 10 секунд.
- Описание – описание ресурса: до 4000 символов в кодировке Unicode.
Для подключения к базе данных на вкладке Основные параметры вам требуется задать значения следующих параметров в разделе Соединение:
- Тип базы данных – в раскрывающемся списке вы можете выбрать тип базы данных для подключения. Когда вы выберете тип базы данных, в поле URL будет указан префикс, соответствующий протоколу взаимодействия. Например, для типа базы данных ClickHouse в поле URL будет указан префикс clickhouse://
- Секрет отдельно – если флажок установлен, в окне отобразится обязательное поле URL, где вы можете указать URL подключения, и раскрывающийся список Секрет с секретами типа credentials. Таким образом вы сможете просматривать информацию о подключении и вам не придется заново создавать большое количество подключений, если изменился пароль учетной записи, которую вы использовали для подключений. Если флажок не установлен, доступно только поле URL для выбора или создания секрета типа urls. По умолчанию флажок не установлен.
- URL (обязательно):
- поле для выбора или создания секрета urls, в котором хранится список URL-адресов для подключения к базе данных. Доступно, если снят флажок Секрет отдельно.
При необходимости вы можете изменить или создать секрет.
При создании подключений могут некорректно обрабатываться строки с учетными данными, содержащими специальные символы. Если при создании подключения возникает ошибка, но вы уверены в том, что значения параметров корректны, укажите специальные символы в процентной кодировке.
- поле для указания URL подключения. Используется вместе с секретом типа credentials. Доступно, если установлен флажок Секрет отдельно.
- поле для выбора или создания секрета urls, в котором хранится список URL-адресов для подключения к базе данных. Доступно, если снят флажок Секрет отдельно.
- Секрет - раскрывающийся список для выбора существующего или создания нового секрета типа credentials. Раскрывающийся список доступен, если установлен флажок Секрет отдельно.
- Авторизация - тип авторизации при подключении к указанному URL Доступны следующие значения:
- Выключена – значение по умолчанию.
- Обычная – при выборе этого варианта требуется указать секрет, содержащий данные учетной записи пользователя для авторизации при подключении к коннектору.
- PublicPKI – при выборе этого варианта требуется указать секрет, содержащий закрытый ключ PEM, закодированный в base64, и открытый ключ.
- Режим TLS – использование шифрования TLS. Доступные значения:
- Выключено: значение по умолчанию, не использовать шифрование TLS.
- Включено: использовать шифрование, но без верификации сертификата.
- Нестандартный CA: использовать шифрование с верификацией сертификата, подписанного центром сертификации. Секрет с сертификатом выбирается в раскрывающемся списке Нестандартный CA, который отображается при выборе этого пункта.
Создание сертификата, подписанного центром сертификации
При использовании TLS невозможно указать IP-адрес в качестве URL.
- Столбец идентификатора (обязательно) – название столбца, содержащего идентификатор для каждой строки таблицы.
- Начальное значение идентификатора (обязательно) – значение в столбце идентификатора, по которому будет определена строка, с которой требуется начать считывание данных из SQL-таблицы.
- Запрос – поле для дополнительного SQL-запроса. Запрос, указанный в этом поле, выполняется вместо запроса по умолчанию.
- Интервал запросов, сек. – интервал выполнения SQL-запросов. Интервал, указанный в этом поле, используется вместо интервала, указанного по умолчанию для коннектора.
Указывается в секундах. Значение по умолчанию: 10 секунд.
.
.Для коннектора на вкладке Дополнительные параметры вам требуется задать значения следующих параметров:
- Кодировка символов – кодировка символов. Значение по умолчанию:
UTF-8.KUMA конвертирует ответы SQL в кодировку UTF-8. Вы можете настроить SQL-сервер на отправку ответов в кодировке UTF-8 или выбрать их кодировку на стороне KUMA.
- Отладка – переключатель, с помощью которого можно указать, будет ли включено логирование ресурса. По умолчанию положение Выключено.
В рамках одного коннектора вы можете создать подключение для нескольких поддерживаемых баз данных.
Если коллектор с коннектором типа sql не удаётся запустить, необходимо проверить, пуст ли state-файл /opt/kaspersky/kuma/collector/<идентификатор коллектора>/sql/state-<идентификатор файла>.
Если state-файл пуст, необходимо его удалить и выполнить перезапуск коллектора.
Поддерживаемые типы SQL и особенности их использования
Оператор UNION не поддерживается коннекторами типа SQL.
Поддерживаются следующие типы SQL:
- MSSQL
Примеры URL:
sqlserver://{user}:{password}@{server:port}/{instance_name}?database={database}– (рекомендуемый вариант)sqlserver://{user}:{password}@{server}?database={database}
В качестве плейсхолдера в SQL-запросе используются символы
@p1.Если вам требуется подключиться с доменными учетными данными, укажите имя учетной записи в формате
<домен>%5C<пользователь>. Например:sqlserver://domain%5Cuser:password@ksc.example.com:1433/SQLEXPRESS?database=KAV. - MySQL
Пример URL:
mysql://{user}:{password}@tcp({server}:{port})/{database}В качестве плейсхолдера в SQL-запросе используются символ
?. - PostgreSQL
Пример URL:
postgres://{user}:{password}@{server}/{database}?sslmode=disableВ качестве плейсхолдера в SQL-запросе используются символы
$1. - CockroachDB
Пример URL:
postgres://{user}:{password}@{server}:{port}/{database}?sslmode=disableВ качестве плейсхолдера в SQL-запросе используются символы
$1. - SQLite3
Пример URL:
sqlite3://file:{file_path}В качестве плейсхолдера в SQL-запросе используется знак вопроса:
?.При обращении к SQLite3, если начальное значение идентификатора используется в формате datetime, в SQL-запрос нужно добавить преобразование даты с помощью функции sqlite datetime. Например, select * from connections where datetime(login_time) > datetime(?, 'utc') order by login_time. В этом примере
connections– это таблица SQLite, а значение переменной?берется из поля Начальное значение идентификатора, и его следует указывать в формате {date}T{time}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}
Пример URL секрета с прежним драйвером oracle-deprecated:
oracle-deprecated://{user}/{password}@{server}:{port}/{service_name}
В качестве плейсхолдера в SQL-запросе используется переменная
:val.При обращении к Oracle DB, если начальное значение идентификатора используется в формате datetime, нужно учитывать тип поля в самой базе данных и при необходимости добавить дополнительные преобразования строки со временем в запросе для обеспечения корректной работы 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, а в запросе произвести преобразование с помощью функции 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, а в запросе произвести преобразование с помощью функции 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.
- Если у поля login_time тип TIMESTAMP, то в зависимости от настроек базы в поле login_time может лежать значение в формате YYYY-MM-DD HH24:MI:SS (например, 2021-01-01 00:00:00). Тогда в поле Начальное значение идентификатора следует указать значение 2021-01-01T00:00:00Z, а в запросе произвести преобразование с помощью функции to_timestamp. Например:
- Firebird® SQL
Пример URL:
firebirdsql://{user}:{password}@{server}:{port}/{database}В качестве плейсхолдера в SQL-запросе используется знак вопроса:
?.Если возникает проблема подключения к firebird на Windows, используйте полный путь до файла с базой данных. Например:
firebirdsql://{user}:{password}@{server}:{port}/C:\Users\user\firebird\db.FDB - ClickHouse
Коннектор работает с ClickHouse только по TCP порту 9000 по умолчанию без шифрования TLS и 9440 по умолчанию, если используется режим TLS. Если на сервере с ClickHouse настроен режим шифрования TLS настроен, а в коннекторе выбран режим Выключено, или наоборот, соединение с базой данных не будет установлено.
Если вы хотите подключиться к ClickHouse KUMA, следует в параметрах коннектора SQL указать тип секрета PublicPki, который содержит закрытый ключ PEM, закодированный в base64, и открытый ключ.
В параметрах SQL коннектора для типа соединения ClickHouse требуется указывать Режим TLS: режим Выключено недопустимо указывать, если для аутентификации используется сертификат. Если вы выбираете параметр НестандартныйCA, в поле Столбец идентификатора следует указывать ID секрета типа certificate.
Также требуется указывать Тип Авторизации:
- Выключено: если используется этот параметр, значение параметра Столбец идентификатора остается пустым.
- Обычная: используется, когда установлен флажок Секрет отдельно и в поле Столбец идентификатора указан ID секрета типа credentials.
- PublicPki: используется, когда установлен флажок Секрет отдельно и в поле Столбец идентификатора указан ID секрета типа PublicPki.
Флажок Секрет отдельно используется, чтобы можно было указать URL отдельно, не в секрете.
В SQL-запросах поддерживается последовательный запрос сведений из базы данных. Например, если в поле Запрос указать запрос select * from <название таблицы с данными> where id > <плейсхолдер>, то при первом обращении к таблице в качестве значения плейсхолдера будет использоваться значение поля Начальное значение идентификатора. При этом в сервисе, в котором используется SQL-коннектор, сохраняется идентификатор последней прочитанной записи, и во время следующего обращения к базе данных в качестве значения плейсхолдера в запросе будет использоваться идентификатор этой записи.
