Тип sql

Развернуть все | Свернуть все

KUMA поддерживает работу с несколькими типами баз данных.

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

Для коннектора на вкладке Основные параметры вам требуется задать значения следующих параметров:

• Название (обязательно) – уникальное имя ресурса. Имя должно содержать от 1 до 128 символов Юникода.
• Тип (обязательно) – тип коннектора, sql.
• Тенант (обязательно) – название тенанта, которому принадлежит ресурс.
• Запрос по умолчанию (обязательно) – SQL-запрос, который выполняется при подключении к базе данных.
• Переподключаться к БД каждый раз при отправке запроса – по умолчанию флажок снят.
• Интервал запросов, мс – период выполнения SQL-запросов. Значение указывается в секундах. Значение по умолчанию – 10 секунд.
• Описание – описание ресурса: до 4000 символов Юникода.

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

• В раскрывающемся списке Тип базы данных вы можете выбрать тип базы данных, к которой вы хотите подключиться. После выбора типа базы данных в поле URL отображается префикс, соответствующий протоколу обмена данными. Например, для базы данных ClickHouse поле URL содержит префикс clickhouse://.
• Если установлен флажок Секрет отдельно, в окне отображается обязательное поле URL, в котором можно указать URL подключения, и раскрывающийся список Секрет с секретами типа "credentials". Таким образом вы сможете просматривать информацию о подключении без необходимости повторно создавать большое количество подключений, если изменился пароль учетной записи, которую вы использовали для подключений. Если флажок снят, для выбора или создания секрета типа "urls" доступно только поле URL. По умолчанию флажок снят.
• URL (обязательно) – секрет, в котором хранится список URL-адресов для подключения к базе данных.
  • Поле для выбора или создания секрета типа "urls", в котором хранится список URL для подключения к базе данных. Поле доступно, если снят флажок Секрет отдельно.

    При необходимости вы можете изменить или создать секрет.

    1. Нажмите на кнопку .

       Откроется окно секрета.

    2. Укажите значения для следующих параметров:
       1. Название – имя добавляемого секрета.
       2. Тип – urls.

          Значение установлено по умолчанию, его редактирование недоступно.

       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>&encrypt=disable

            В качестве плейсхолдера используются символы @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>&encrypt=disable

            В качестве плейсхолдера используются символы @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-адресу, указанному в списке адресов.

    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 не используется.
  • Включено – шифрование используется, но без проверки сертификата.
  • Нестандартный CA – используется шифрование с проверкой сертификата, который должен быть подписан центром сертификации. Секрет с сертификатом выбирается в раскрывающемся списке "Нестандартный CA", который отображается при выборе этого пункта.

    Создание сертификата, подписанного центром сертификации

    Для использования этого режима TLS необходимо выполнить следующие действия на сервере Ядра 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, который затем нужно выбрать в раскрывающемся списке Нестандартный 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 и особенности их использования

Поддерживаются следующие типы 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.

• 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 и в коннекторе выбран режим "Выключено" (или наоборот), подключение с базой данных не устанавливается.

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

  В параметрах SQL-коннектора для подключения ClickHouse необходимо указать режим TLS. Значение Выключено не разрешено, если для аутентификации используется сертификат. Если вы выбрали Нестандартный CA, в поле Столбец идентификатора укажите идентификатор секрета типа "certificate".

  Также нужно указать тип Авторизация:

  • Если указано значение Выключено, значение Столбец идентификатора не задано.
  • Тип Обычная используется, когда установлен флажок Секрет отдельно и идентификатор секрета типа "credentials" указан в поле Столбец идентификатора.
  • Тип PublicPki используется, когда установлен флажок Секрет отдельно и в поле Столбец идентификатора указан идентификатор секрета типа "PublicPki".

  Флажок Секрет отдельно позволяет указать URL отдельно, а не как часть секрета.

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

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