Установка logging_module#

Описание logging_module#

LoggingModule предназначен для записи логов в БД. LoggingModule принимает сообщения из Kafka и сохраняет их в базу данных.

Типы принимаемых сообщений:

  1. SendHazelcastStatusNf

  2. SendNodeStatusNf

  3. SendConfigReportNf

  4. SendLogExpandedNf

  5. SendLogNf

  6. ConfigHashSum: сообщение из Config_Module в формате JSON, где указываются hashes актуальных конфигурационных файлов в каждом сегменте

  7. CertStorageData: содержит информацию с именем node ТФС, именами хранилищ сертификатов который ей используются, информацией о сертификатах
    которые содержатся в хранилищах.

Установка#

Описание структуры каталога поставки LoggingModule#

  1. Для разворачивания LoggingModule необходимо скопировать содержимое пакета поставки в рабочую директорию приложений ( например, /u01/tfsApp) под пользователем, например, tfs99usr.

   tfs_logging_module-xxx.jar -> tfs_logging_module.jar
   LoggingModule_Start.sh -> LoggingModule_Start.sh
   application.properties -> resources/application.properties
   
   configroute.properties -> resources/configroute.properties
   log4j2.xml -> resources/log4j2.xml
   scheme_cert_confighash.json -> resources/scheme_cert_confighash.json
   SrvLogsTransferMgmt_(v1.0)_Fin_2017_06_22.xsd -> resources/SrvLogsTransferMgmt_(v1.0)_Fin_2017_06_22.xsd

  1. Убедиться, что в LoggingModule_Start.sh:
    2.1 Проставлена правильная версия jdk
    2.2 В APPNAME= прописан jar-ник с актуальной версией
    2.3 Есть строки
    -Dspring.config.location=./resources/application.properties \
    -jar $APPNAME 2> $StartLog > &

  2. В этом же каталоге создать папку lib_extensions и поместить в нее библиотеки, если это необходимо.

Управление приложением#

  • Старт: ./LoggingModule_Start.sh start

  • Остановка: ./LoggingModule_Start.sh stop

  • Перезапуск: ./LoggingModule_Start.sh restart

Настройка приложения#

Имя узла

spring.application.name=

  • application.name: Имя узла. Используется для поиска узла в БД и добавления данных по сертификатам.
    Обязательно к заполнению.
    Заполняется значением имени node из таблицы "NODE".

Подключение к БД

spring.datasource.url=jdbc:postgresql://host:port/TFSDB
spring.datasource.username=
spring.datasource.password=
spring.jpa.properties.hibernate.default_schema=

Указываются данные подключения для Postgresql

  • url - url для подключения к БД;

  • username - Имя пользователя для подключения к БД;

  • password - Пароль для подключения к БД;

  • default_schema - Указывает на схему базы данных, которая будет использоваться по умолчанию для всех таблиц.

Подключение к Kafka

kafka.kafka.brokers=localhost:0000
kafka.consumer.group-id=test
kafka.consumer.client-id=client
kafka.topics=TEST.IN
spring.kafka.consumer.client-id=myClient
kafka.is-ssl-enabled=true
kafka.ssl.endpoint.identification.algorithm=
kafka.ssl.keystore-location=
kafka.ssl.keystore-password=
kafka.ssl.truststore.location=
kafka.ssl.truststore.password=
kafka.ssl.cipher.suites=
kafka.ssl.enabled.protocols=
kafka.ssl.protocol=
kafka.exponential-back-off.initial-interval-sec=
kafka.exponential-back-off.max-interval-sec=
kafka.exponential-back-off.multiplier=
kafka.exponential-back-off.max-elapsed-time-sec=

Конфигурация потребителя Kafka:

  • kafka.brokers: Список брокеров в формате host:port, разделенных запятыми.

  • consumer.group-id: Имя группы потребителей.

  • consumer.client-id: Имя клиента.

  • topics: Список topics, разделенных запятыми.

  • is-ssl-enabled: Флаг, указывающий на использование SSL. true: SSL включен, false или не указано: SSL выключен.

Параметры SSL (при включенном is-ssl-enabled)

  • ssl.endpoint.identification.algorithm: Алгоритм проверки подлинности идентификации удаленного сервера при установлении SSL-соединения.
    Для выставления значения по умолчанию параметр пуст или не указывается.

  • ssl.keystore-location: Указывает путь к хранилищу ключей (keystore), где хранятся личный ключ и сертификат клиента.

  • ssl.keystore-password: Пароль для доступа к хранилищу ключей.

  • ssl.truststore.location: Указывает путь к хранилищу доверенных сертификатов (truststore), где хранятся сертификаты доверенных центров сертификации.

  • ssl.truststore.password: Пароль для доступа к хранилищу доверенных сертификатов.

  • ssl.cipher.suites: Набор поддерживаемых шифров.
    по умолчанию поддерживаются все доступные наборы шифров если параметр пуст или не указан.

  • ssl.enabled.protocols: Список разрешенных протоколов для SSL-соединений.
    Список протоколов, разрешенных для SSL-соединений. Значение по умолчанию - TLSv1.2,TLSv1.3 при запуске с Java 11 или новее,
    TLSv1.2 в другом случае. При значении по умолчанию для Java 11 клиенты и серверы предпочтут TLSv1.3, если оба поддерживают его,
    и вернутся к TLSv1.2 в другом случае (при условии, что оба поддерживают по крайней мере TLSv1.2).
    Также смотрите пункт по конфигурации ssl.protocol.
    Для выбора значения по умолчанию, оставить незаполненным или не указывать параметр.

  • ssl.protocol: протокол SSL, используемый для создания SSLContext. По умолчанию используется TLSv1.3 при работе с Java 11 или более новой версией,
    в другом случае - TLSv1.2. При значении по умолчанию для этого параметра и ssl.enabled.protocols, клиенты понизят версию до TLSv1.2, если сервер не поддерживает TLSv1.3.
    Для выбора значения по умолчанию, оставить незаполненным или не указывать параметр.

Параметры для управления kafka retry:
В случае возникновения ошибки при попытке записать сообщение в бд запустится механизм переотправки.
Для данного сообщения в kafka topic не будет вызван commit и оно будет повторно обработано.
по умолчанию переотправка будет длиться бесконечно.
Пример со значениями по умолчанию: initial-interval-sec: 20 сек, max-interval-sec: 300 сек, multiplier: 1.5

попытка

время, сек

1

20

2

30

3

45

4

67

5

101

6

151

7

227

8

300

9

300

10

300

  • exponential-back-off.initial-interval-sec: Задает время первой попытки переотправки для механизма kafka retry, по умолчанию: 20 секунд.
    Для выбора значения по умолчанию, оставить незаполненным или не указывать параметр.

  • exponential-back-off.max-interval-sec: Задает предел времени между попытками переотправки, по умолчанию: 300 секунд.
    Для выбора значения по умолчанию, оставить незаполненным или не указывать параметр.

  • exponential-back-off.multiplier: Множитель для exponential-back-off.initial-interval-sec, на основании него будет изменяться время каждой последующей попытки,
    по умолчанию: 1.5.
    Для выбора значения по умолчанию, оставить незаполненным или не указывать параметр.

  • exponential-back-off.max-elapsed-time-sec: Время в течении которого будет производиться повторная попытка обработки сообщения, по умолчанию: бесконечно.
    Для выбора значения по умолчанию, оставить незаполненным или не указывать параметр.

Ссылка на xsd

messages.validation.xsd.xsdPath=./resources/SrvLogsTransferMgmt (v1.0) Fin 2017 06 22.xsd

  • xsdPath - путь до xsd схемы;

Ссылка на JSON-схему

messages.validation.json.scheme=./resources/scheme_cert_confighash.json

  • json.scheme - путь до JSON схемы;

Ссылка на хранилище jks и пароль

security.jks.keyStore=
security.jks.keyStorePassword=

  • keyStore - Имя хранилища;

  • keyStorePassword - Пароль хранилища в base64;

Параметры для отправки данных сертификата используемого модулем логирования

certificate.metadata-logging.enabled=true
certificate.check-interval-millis=50000
certificate.json-result-indent-output=true

  • metadata-logging.enabled: Включает логику формирования метаданных сертификатов используемых модулем для отправки в бд, по умолчанию true.

  • check-interval-millis: Интервал запуска проверки и отправки данных по сертификатам, по умолчанию если не заполнен 43200000 мс(12 часов).

  • json-result-indent-output: Форматирование JSON для удобства чтения, по умолчанию false.

Интеграция с Hashicorp Vault#

Настройки#

Добавляются следующие настройки в application.properties:
(пример заполнения полей для подключения в namespace DEV_DZO)

spring.cloud.vault.fail-fast=true
spring.config.import=optional:vault://A/DEV/TFSX/KV/LOG_MODULE
vault.cert-path=./resources/certs2
vault.data-version=(local)
vault.cert-list=spring.jks.keyStore.jks
vault.key-list=vault.data-version, spring.datasource.username, spring.datasource.password, spring.jks.keyStore, spring.jks.keyStorePassword
vault.refresh.rate_sec=120
spring.cloud.vault.fail-fast-conf.retry.maxAttempts=3
spring.cloud.vault.fail-fast-conf.retry.maxInterval=60

spring.cloud.vault.authentication=approle
spring.cloud.vault.app-role.role-id=(role-id)
spring.cloud.vault.app-role.secret-id=(secret-id)
spring.cloud.vault.uri=http://test:8282
spring.cloud.vault.namespace=DEV_DZO
# refresh lease token before expired
spring.cloud.vault.session.lifecycle.enabled=true
spring.cloud.vault.session.lifecycle.refresh-before-expiry=30m
spring.cloud.vault.session.lifecycle.expiry-threshold=1m
spring.cloud.refresh.extra-refreshable=com.zaxxer.hikari.HikariDataSource

  • spring.cloud.vault.enabled - включить/выключить чтение секретов из Vault.

  • spring.config.import - путь в Vault до блока секретов.

  • vault.cert-path - путь на локальной машине для размещения сертификатов из Vault.

  • vault.data-version - справочное поле, позволяющее определить произошел ли маппинг значений из Vault. В локальном файле настроек рекомендуется значение (local), в Vault - номер изменения.

  • vault.cert-list - список сертификатов, которые нужно вычитать из Vault в формате "(ключ).(тип)"

  • vault.key-list - список ключей, которые должны сопоставляться из Vault. Данный список используется только для контроля в logger VAULT_DIAGS, сам механизм сопоставления из Vault работает для любых значений.

  • vault.refresh.rate_sec - период обновления данных из Vault в сек. (Обновление отключено при отсутствии переменной или значениях <= 0)

  • spring.cloud.vault.fail-fast-conf.retry.maxAttempts - количество попыток обновления до завершения приложения. Данный параметр относится к стратегии fail-fast

  • spring.cloud.vault.fail-fast-conf.retry.maxIntervall - интервал между попытками обновления секретов(мс). Данный параметр относится к стратегии fail-fast

  • spring.cloud.vault.authentication - метод аутентификации в Vault

  • spring.cloud.vault.app-role.role-id - role-id при методе approle, задается при конфигурировании приложения.

  • spring.cloud.vault.app-role.secret-id - secret-id при методе approle, задается при конфигурировании приложения.

  • spring.cloud.vault.uri - корневой uri сервера Vault.

  • spring.cloud.vault.namespace - пространство имен секретов

  • spring.cloud.vault.fail-fast - параметр активации стратегии fail-fast

  • spring.cloud.vault.session.lifecycle.enabled - включение механизма поддержания сессии в Vault с при использовании временных токенов.

  • spring.cloud.vault.session.lifecycle.refresh-before-expiry - время до истечения срока валидности токена, когда нужно повторно запрашивать аутентификацию в Vault.

  • spring.cloud.vault.session.lifecycle.expiry-threshold - время до истечения срока валидности токена, когда следует начать планировать его обновление. (Должно быть > refresh-before-expiry )

  • spring.cloud.refresh.extra-refreshable - классы, которые нужно обновлять по RefreshEvent.

Настройки безопасности "нулевого секрета"#

Чтобы не хранить secret-id в настроечном файле в открытом виде, можно задействовать настройку "нулевого секрета":
В этом случае оригинальный secret-id шифруется симметричным ключом. Зашифрованный secret-id передается как системный параметр при запуске приложения (-Dspring.cloud.vault.app-role.secret-id=xxx).
А ключ шифрования помещается в файл в формате Base64, с правами доступа только для пользователя, от которого работает приложение.

Путь до файла задается параметром -Dspring.cloud.vault.zero-path=zzz. Если не указан, по умолчанию это ./zero или ./resources/zero

Особенность хранения сертификатов в Hashicorp Vault#

Тело сертификата хранится в виде текста на соответствующем ключе, как обычная строка.

Бинарные сертификаты типа .jks, .p12 должны быть переведены в формат Вase64. При считывании из Vault перед помещением в файл сервис будет декодировать из Вase64 все типы отличные от "pem". Сертификаты типа .pem и так являются текстовыми, поэтому записываются без преобразования как-есть.

При инициализации приложения считывается список vault.cert-list где перечислены требуемые сертификаты в виде xxx.тип.
При отсутствии интеграции с Vault локальный сертификат xxx задается путем до файла.
При наличии интеграции с Vault ему должен соответствовать ключ секрета с суффиксом xxx-base64, в котором хранится тело сертификата.
При загрузке из Vault сертификат будет записан в файл по имени xxx.тип, как он перечислен в списке vault.cert-list.
Файлы сертификатов складываются в папку, заданную переменной vault.cert-path.
Переменной xxx присваивается полный путь до нового файла сертификата, полученного из Vault: vault.cert-path/xxx.тип.

Логирование интеграции#

Для диагностики монтирования настроек из Vault используется logger VAULT_DIAGS. Он работает на уровне "debug". По умолчанию он зарегистрирован с уровнем info, что фактически означает "выключен". Для отображения отладочных сообщений - перевести в уровень debug. (Выводит список смонтированных настроек, и их актуальных значений для контроля). Пароли маскируются звездочками: "p***d" .

    <!-- Логирует состояние маппинга атрибутов из Vault
        Для активации перевести в уровень DEBUG -->
<Logger level="info" name="VAULT_DIAGS" additivity="false">
    <AppenderRef ref="STDOUT"/>
</Logger>

Пример лога:

[DEBUG][13/06/23 11:54:42:072 MSK] [main] VAULT_DIAGS:99 ---------------------------------------- 
[DEBUG][13/06/23 11:54:42:072 MSK] [main] VAULT_DIAGS:100 Actual Configuration properties 
[DEBUG][13/06/23 11:54:42:072 MSK] [main] VAULT_DIAGS:105 	vault.data-version = 1 
[DEBUG][13/06/23 11:54:42:072 MSK] [main] VAULT_DIAGS:105 	spring.datasource.username = postgres 
[DEBUG][13/06/23 11:54:42:074 MSK] [main] VAULT_DIAGS:105 	spring.datasource.password = p***s 
[DEBUG][13/06/23 11:54:42:075 MSK] [main] VAULT_DIAGS:105 	spring.jks.keyStore = ./resources/certs2/spring.jks.keyStore.jks 
[DEBUG][13/06/23 11:54:42:075 MSK] [main] VAULT_DIAGS:105 	spring.jks.keyStorePassword = k***1 
[DEBUG][13/06/23 11:54:42:075 MSK] [main] VAULT_DIAGS:107 ----------------------------------------

Обновление данных из Vault (Hot Reload)#

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

Обновление по таймеру - включается настройкой, где указывается период обновления в секундах:

vault.refresh.rate_sec=120

Если эта переменная отсутствует или <= 0, а также если интеграция с Vault отключена, то периодическое обновление не будет активировано.

После обновления будет повторно инициализирован DataSource если он указан в переменной spring.cloud.refresh.extra-refreshable и перезаписаны файлы сертификатов, содержимое которых изменилось.

*Примечание: для DataSource in-memory H2 БД обновление HikariDataSource в текущей конфигурации приведет к пересозданию БД и потери всех данных в памяти.