4. Настройка и запуск Агента ПОДД

4.1. Порядок загрузки данных и программ

Администратор УВ осуществляет развёртывание, запуск и настройку Агента ПОДД СМЭВ с помощью данного руководства.

4.2. Подготовка и настройка системы для запуска Агента без использования docker

4.2.1. Состав и содержание дистрибутивного пакета

Состав дистрибутива Агента ПОДД СМЭВ (/distr/einfahrt):

/distr/einfahrt/app/app.jar – исполняемый файл;
/distr/einfahrt/csp-5.0.11455.tar.gz – дистрибутив CryptoPro CSP;
/distr/einfahrt/java-csp-5.0.42119-A.zip – дистрибутив CryptoPro JСP;
/distr/einfahrt/bellsoft-jdk17.0.7-linux-amd64.tar.gz – дистрибутив Java.

Путь /distr/einfahrt указан в качестве примера. Есть возможность использовать любой другой путь, скорректировав соответствующим образом упоминаемые ниже команды.

4.2.2. Предварительные операции (установка «пре-реквизитов»)

Перед запуском Агента ПОДД СМЭВ выполнить от имени пользователя root следующие действия:

Создать пользователя {{user}} и группу {{user_group}}, под которым будет работать Агент ПОДД СМЭВ.
Установить java

cd /distr/einfahrt
tar zxvf bellsoft-jdk17.0.7-linux-amd64.tar.gz

Установить системные переменные

export JAVA_HOME=/distr/einfahrt/jdk-17.0.7
export PATH=$PATH:$JAVA_HOME/bin

Рекомендуется внести данную настройку в profile пользователя.

Установить CryptoPro JCP:

cd /distr/einfahrt
mkdir -p /distr/einfahrt/cryptopro
unzip java-csp-5.0.42119-A.zip
cd java-csp-5.0.42119-A
./configure.sh
cp -f *.jar /distr/einfahrt/cryptopro/
cd /distr/einfahrt
rm -rf java-csp-5.0.42119-A

При наличии лицензионного кода CryptoPro JCP выполнить от имени пользователя {{user}} команду.

java -cp :/distr/einfahrt/cryptopro/* ru.CryptoPro.JCP.tools.License -serial "{{ jcp_serial }}" -store

В случае отсутствия лицензионного кода, CryptoPro JCP будет работать в режиме trial лицензии.

Внимание

Срок действия trial лицензии – 90 дней с момента установки CryptoPro JCSP. Для сохранения работоспособности Агента ПОДД по окончании данного периода вам необходимо приобрести лицензию на CryptoPro JCSP и внести её в систему как указано выше.

Установить CryptoPro CSP:

cd /distr/einfahrt
tar xzvf csp-5.0.11455.tar.gz
rm -f csp-5.0.11455.tar.gz
cd csp-5.0.11455 yum -y install lsb-cprocsp-base*.rpm lsb-cprocsp-rdr-64*.rpm lsb-cprocsp-kc1-64*.rpm lsb-cprocsp-capilite-64*.rpm lsb-cprocsp-devel*.rpm lsb-cprocsp-kc2-64*.rpm cprocsp-curl-64*.rpm
./install.sh
cd ..

При наличии лицензионного кода CryptoPro CSP выполнить пользователем root команду:

/opt/cprocsp/sbin/amd64/cpconfig -license -set {{cprocsp_license_code}}

В случае отсутствия лицензионного кода, CryptoPro CSP будет работать в режиме trial лицензии.

Внимание

Срок действия trial лицензии – 90 дней с момента установки CryptoPro CSP. Для сохранения работоспособности Агента ПОДД по окончании данного периода, вам необходимо приобрести лицензию на CryptoPro CSP и внести её в систему как указано выше.

Установить контейнер с ключами CryptoPro в директорию /var/opt/cprocsp/keys/{{user}}/. Пользователь {{user}} должен быть владельцем данной директории и файлов в ней.
Для установки TLS соединения, который использует алгоритмы в соответствии с ГОСТ-2012, требуется использовать доверенное хранилище с корневыми сертификатами удостоверяющих центров (УЦ), которое находится в дистрибутиве (файл cp_ca_store).

Внимание

Ключ CryptoPro должен содержать цепочку сертификатов промежуточных УЦ (кроме корневого). Приложение А Добавление промежуточных сертификатов в ключ CryptoPro настоящего документа содержит сведения о добавлении промежуточных сертификатов в ключ.

Выложить в каталог /distr/enfahrt конфигурационный файл application.yml, подготовленный согласно Описание конфигурационного файла.
В файл /etc/hosts добавить следующие записи:

20.59.5 podd.gosuslugi.ru
207.15.26 podd1.gosuslugi.ru
207.15.58 podd2.gosuslugi.ru
207.15.154 podd3.gosuslugi.ru
207.15.186 podd4.gosuslugi.ru

4.2.3. Запуск Агента ПОДД

Убедитесь, что пользователь {{user}} имеет доступ к директории, в которой установлен Агент ПОДД СМЭВ (/distr/einfahrt).

Пример раздела конфигурации скрипта для запуска Агента ПОДД СМЭВ с использованием сервиса systemd:

[Unit]
Description="Service for einfahrt"
After=syslog.target

[Service]
Type=simple

WorkingDirectory=/distr/einfahrt
LimitNOFILE=1048576:1048576

# Важно! Запуск должен производиться от имени того пользователя, для которого ранее были выложены ключи КриптоПро!
User={{user}}
Group={{user_group}}

Environment="JAVA_HOME=/distr/einfahrt/jdk-17.0.7"
Environment="JDK_JAVA_OPTIONS=--add-exports=java.base/sun.security.util=ALL-UNNAMED \
    --add-exports=java.base/sun.security.x509=ALL-UNNAMED \
    --add-exports=java.base/sun.security.pkcs=ALL-UNNAMED \
    --add-exports=java.base/sun.security.provider=ALL-UNNAMED \
    --add-exports=java.base/sun.security.tools.keytool=ALL-UNNAMED \
    -Dsaffron.default.charset=UTF-16LE \
    -Dsaffron.default.collation.name='UTF-16LE$en_US' \
    -Dsaffron.default.nationalcharset=UTF-16LE \
    -XX:MaxRAMPercentage=80.0 \
    -XX:+UnlockExperimentalVMOptions \
    -XX:InitiatingHeapOccupancyPercent=16 \
    -XX:+UseStringDeduplication \
    -XX:+G1EagerReclaimHumongousObjects \
    -XX:+G1EagerReclaimHumongousObjectsWithStaleRefs \
    -XX:G1HeapWastePercent=2 \
    -XX:G1MaxNewSizePercent=25 \
    -XX:G1MixedGCLiveThresholdPercent=15 \
    -XX:+UseG1GC"
ExecStart=/distr/einfahrt/jdk-17.0.7/bin/java -cp app/*:cryptopro/* -jar app/app.jar

[Install]
WantedBy=multi-user.target

Соответствующий файл скрипта, для примера с названием einfahrt.service, необходимо положить в каталог /etc/systemd/system/.

Далее от имени пользователя root выполнить команду по включению, запуску сервиса и проверке его статуса:

systemctl daemon-reload
systemctl enable einfahrt
systemctl start einfahrt
systemctl -l status einfahrt

4.2.4. Настройка ротации логов (опционально)

Во избежание переполнения диска лог-файлами, рекомендуется настроить ротацию лог-файлов systemd сервиса.

Настройка логирования осуществляется с помощью файлов конфигурации logrotate и systemd сервиса. Если этих файлов не существует, их необходимо создать. Первоначально необходимо установить пакет logrotate, для rpm-base дистрибутивов необходимо выполнит команду:

yum install logrotate

Добавьте в файл systemd сервиса (/etc/systemd/system/einfahrt.service) следующие настройки логирования:

...
[Service]
Type=simple

StandardOutput=append:/var/log/{{ file_name }}
StandardError=append:/var/log/{{ file_name }}

...

Создайте файл конфигурации logrorate /etc/logrotate.cron/einfahrt.conf и поместите в него следующее содержимое:

/var/log/{{ file_name }} {
    rotate {{ rotate }}
    size {{ file_size }}
    create
    nocompress
    copytruncate
}

где:

rotate – какое количество лог файлов оставлять,
file_size – размер лог-файла при котором будет происходить ротация.

Создайте файл с скриптом запуска утилиты logrotate, поместите скрипт по пути /etc/logrotate.cron/einfahrt.sh

#!/bin/bash
/usr/sbin/logrotate /etc/logrotate.cron/einfahrt.conf

Добавьте права на запуск командой:

chmod +x /etc/logrotate.cron/einfahrt.sh

Создайте правила cron, создайте файл /etc/cron.d/einfahrt и поместите в него содержимое ниже:

*/1 * * * * root /etc/logrotate.cron/einfahrt_logrotate.sh

Далее перезагрузите systemd сервис:

systemctl daemon-reload
systemctl restart einfahrt

4.3. Настройка и запуск Агента ПОДД с использованием docker

4.3.1. Предварительные условия

На сервере должен быть установлен docker версии не ниже 20.10.12.
Создан пользователь, который будет запускать Агент ПОДД.
Этот пользователь должен иметь права на загрузку докер-образов и запуск/остановку контейнеров (т.е. добавлен в группу docker).

4.3.2. Настройка ротации лог-файлов в docker (опционально)

Во избежание переполнения диска лог-файлами, рекомендуется настроить ротацию лог-файлов контейнеров в docker.

Настройка логирования в Docker осуществляется с помощью файла конфигурации /etc/docker/daemon.json. Если этого файла не существует, его необходимо создать. Добавьте в файл следующие настройки логирования:

{
"log-opts": {
    "max-file": "3",
    "max-size": "100m"
    }
}

где: - max-file – ограничение по количеству файлов (настройки ротации). Максимальное количество файлов журнала, которые могут быть созданы. При превышении количества самый старый файл удаляется. Действует только при установленном параметре max-size. Положительное целое число. По умолчанию 1; - max-size – устанавливает ограничение по размеру лог-файла (k, m или g). По умолчанию -1 (не ограничено).

4.3.3. Состав и содержание дистрибутивного пакета

Ниже приведён состав дистрибутива Агента ПОДД СМЭВ для docker.

/distr/einfahrt – Агент ПОДД СМЭВ:

/distr/einfahrt/einfahrt.tgz – docker image для загрузки в систему. Включает в себя также все необходимые версии CryptoPro;
/distr/einfahrt/run_agent.sh – скрипт для запуска и перезапуска агента;
/distr/einfahrt/stop.sh – скрипт для остановки агента;
/distr/einfahrt/log_save.sh – скрипт для сохранения лога агента в файл;
/distr/einfahrt/log.sh – скрипт для просмотра лога агента в реальном времени;
/distr/einfahrt/diag.sh – скрипт для сбора диагностической информации при обращении в службу поддержки.

Путь /distr/einfahrt использован для примера, не является фиксированным и может быть изменен на любой другой по желанию пользователя, с соответствующим внесением корректировок при его упоминаниях ниже.

Ниже в качестве примера будет использоваться данный путь.

4.3.4. Подготовка к запуску

Для запуска Агента необходимо после распаковки пакета сформировать конфигурационный файл application.yml, как указано в Формирование конфигурационного файла , и выложить его в каталог /distr/einfahrt.

Внимание

При использовании скрипта из пакета поставки для запуска Агента параметр trust-store.path в конфигурационном файле необходимо задать строго /egov/java/certs/cp_ca_store.

Пример:

trust-store:
  path: /distr/einfahrt/certs/cp_ca_store
  password: *** ПАРОЛЬ К TRUST STORE ***

где:

path – фактический путь к файлу cp_ca_store из дистрибутива (в данном примере – /distr/einfahrt/certs/cp_ca_store);
password – пароль от cp_ca_store.

В каталоге /distr/einfahrt:

создать подкаталог keys, выложить в него полученный ключ CryptoPro в распакованном виде;
создать подкаталог certs, выложить в него файл cp_ca_store из пакета поставки;
(только при использовании https API gateway) подготовить файл cacerts согласно Настройка организации информационного обмена через API Gateway (опционально), сформированный файл выложить в каталог /distr/einfahrt/certs.
выложить файл postgresql.json из пакета поставки;

При наличии файла расширенных настроек логирования customLogLevels.xml выложить его в каталог /distr/einfahrt.

Для запуска Агента ПОДД под docker полученный docker образ необходимо загрузить в локально установленный docker на машине, где будет работать Агент ПОДД.

Для этого необходимо выложить архив с образом на локальный диск этой машины и выполнить команду:

docker load < einfahrt.tgz

где einfahrt.tgz – имя полученного архива с docker image Агента ПОДД из пакета поставки.

Загрузка должна завершиться без ошибок.

Проверить успешность загрузки можно командой:

docker images | grep einfahrt

Вывод будет содержать информацию вида:

einfahrt     latest      c7511824117e     5 days ago      1.2G

4.3.5. Запуск Агента ПОДД

Для запуска Агента используется скрипт run_agent.sh, входящий в пакет поставки. Скрипт не требует указания параметров. При выполнении всех шагов, перечисленных в Подготовка к запуску, Агент будет успешно запущен, с сообщением о доступных портах. При повторном выполнении скрипта контейнер будет остановлен и запущен заново.

Для сохранения лога Агента в файл, запустите скрипт log-save.sh. Лог будет сохранен в файле log-дата-время.txt.

Для просмотра лога в режиме реального времени запустите скрипт log.sh.

В случае необходимости сбора диагностической информации для отправки в службу поддержки запустите скрипт diag.sh.

Остановка контейнера осуществляется скриптом stop.sh.

Примечание

В ряде случаев может наблюдаться остановка контейнера через несколько секунд после запуска, с сообщением в логе java.lang.IllegalStateException: Ошибка вызова функции acquireContext: 0x8009001a. В этом случае следует изменить владельца каталога keys и вложенных подкаталогов и файлов на пользователя с id=1000 (потребуются root права): chown -R 1000 keys после чего повторить выполнение скрипта запуска контейнера.

4.3.6. Информация по лицензированию CryptoPro

Входящие в поставку версии CryptoPro не имеют предустановленной лицензии, и могут работать как trial в течение трех месяцев с момента создания образа (не с момента первого запуска!)

Для использования trial версии CryptoPro не требуется каких-либо дополнительных действий, касающихся лицензирования.

В случае, если у Вас есть полная лицензия на CryptoPro CSP и CryptoPro JCSP, предусмотрена возможность передачи номеров лицензий CSP и JCSP при запуске контейнера, при передаче валидных лицензий соответствующие компоненты CryptoPro будут лицензированы на этапе запуска.

Для этого необходимо, чтобы текстовый файл, содержащий сроку с лицензией на CryptoPro CSP, был при запуске контейнера доступен внутри контейнера по пути /egov/csp.lic. Аналогично, лицензия для CryptoPro JCSP должна быть доступна внутри контейнера в текстовом файле /egov/jcp.lic.

При запуске под docker-ом можно для этого монтировать внешние файлы, содержащие номера лицензий, по указанным выше путям.

Для того, чтобы прилагаемый скрипт запуска применил лицензии CryptoPro, при их наличии, их необходимо поместить в текстовые файлы licenses/jcp.txt и licenses/csp.txt соответственно. При отсутствии лицензии и использовании trial версий CryptoPRO не создавайте указанные файлы.

Внимание

Срок действия trial лицензии – 90 дней с момента создания docker image используемого Вами Агента. Для сохранения работоспособности Агента ПОДД по окончании данного периода необходимо приобрести лицензии на CryptoPro CSP и JCSP и внести их в систему, как указано выше.

4.4. Настройка предустановленного профиля Витрины в Агенте ПОДД

Раздел применим только при использовании Витрины и заданной настройке использования предустановленного профиля Витрины в Агенте ПОДД (см. раздел Настройка регистрации Витрин данных и подключения к kafka (при использовании Витрин)).

Файл профиля имеет настройки по умолчанию. Вносить изменения следует только в том случае, если значения по умолчанию не подходят для данной Витрины.

Настройки задаются после установки Агента ПОДД в файле postgresql.json, расположенном в директории:

1. при установке без использования docker (см. раздел Подготовка и настройка системы для запуска Агента без использования docker): /директория_установленного_Агента_ПОДД/postgresql.json. По умолчанию /distr/einfahrt/postgresql.json

при установке с использованием docker (см. раздел Настройка и запуск Агента ПОДД с использованием docker): /egov/java/postgresql.json

Пример предустановленного профиля Витрины в Агенте ПОДД:

{
  "sqlDialect": "POSTGRESQL",
  "parameterNotionType": "QUESTION",
  "aggFunctions": [
  ...
  ],
  "otherFunctions": [
  ...
  ],
  "forSystemTimeParameterSupport": false,
  "subQueryParamSupport": "DYNAMIC_PARAM_SUPPORT"
}

где:

subQueryParamSupport – способ передачи подзапроса при выполнении РЗ с параметрами на сторону Витрины, возможные значения:

NOT_SUPPORTED - отправка подзапроса с параметрами, подставленными в SQL-выражение;
DYNAMIC_PARAM_SUPPORT - отправка подзапроса с блоком динамических па-раметров, подстановка осуществляется на стороне Адаптера Витрины;
NAMED_PARAM_SUPPORT - отправка подзапроса с блоком именованных пара-метров, подстановка осуществляется на стороне Адаптера Витрины.

forSystemTimeParameterSupport – поддержка системного параметра РЗ для запроса ак-туальных на заданный момент времени данных из Витрины:

false - Адаптер Витрины не поддерживает обработку параметра;
true - Адаптер Витрины поддерживает обработку параметра.

4.5. Настройка сбора метрик Агента ПОДД (опционально)

4.5.1. Настройка Агента для передачи метрик в prometheus

Агент поддерживает возможность передачи метрик работы во внешнюю систему сбора метрик Prometheus.

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

metrics:
  implementation: PROMETHEUS
  # порт, при обращении к которому Агент отдаёт значения метрик
  endpointPort: 8381

Prometheus следует настроить на опрос адреса, на котором запущен Агент, по указанному порту.

При запуске Агента под docker также необходимо добавить указанный порт в список expose ports в скрипте запуска Агента.

Полный список метрик приведен в Приложение B Список метрик Агента.