Настройка и запуск Агента СМЭВ4 ================================ Порядок загрузки данных и программ ------------------------------------ Администратор УВ осуществляет развёртывание, запуск и настройку Агента СМЭВ4 с помощью данного руководства. .. _start_without_docker: Подготовка и настройка системы для запуска Агента СМЭВ4 без использования docker ---------------------------------------------------------------------------------- Состав и содержание дистрибутивного пакета ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Состав дистрибутива Агента СМЭВ4 (``/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СSP; - ``/distr/einfahrt/bellsoft-jdk17.0.7-linux-amd64.tar.gz`` – дистрибутив Java. Путь ``/distr/einfahrt`` указан в качестве примера. Есть возможность использовать любой другой путь, скорректировав соответствующим образом упоминаемые ниже команды. .. _pre_requisites: Предварительные операции (установка "пре-реквизитов") ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Перед запуском Агента СМЭВ4 выполнить от имени пользователя **root** либо используя команду sudo следующие действия: 1. Создать пользователя {{user}} и группу {{user_group}}, под которым будет работать Агент СМЭВ4. 2. Установить java .. code-block:: bash cd /distr/einfahrt tar zxvf bellsoft-jdk17.0.7-linux-amd64.tar.gz 3. Установить системные переменные .. code-block:: bash export JAVA_HOME=/distr/einfahrt/jdk-17.0.7 export PATH=$PATH:$JAVA_HOME/bin Переменные должны устанавливаться автоматически также после перезагрузки сервера. Для этого рекомендуется внести данную настройку в **profile** пользователя либо в настройки ОС. 4. Установить пакет java-csp-5.0.42119-A: .. code-block:: bash 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}} команду. .. code-block:: bash java -cp :/distr/einfahrt/cryptopro/* ru.CryptoPro.JCP.tools.License -serial "{{ jcp_serial }}" -store В случае отсутствия лицензионного кода, CryptoPro JCP будет работать в режиме trial лицензии. .. attention:: Срок действия trial лицензии – 90 дней с момента установки CryptoPro JCP. Для сохранения работоспособности Агента СМЭВ4 по окончании данного периода вам необходимо приобрести лицензию на CryptoPro JCP и внести её в систему как указано выше. 5. Установить CryptoPro CSP: .. code-block:: bash 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 выполнить команду: .. code-block:: bash sudo /opt/cprocsp/sbin/amd64/cpconfig -license -set {{cprocsp_license_code}} В случае отсутствия лицензионного кода, CryptoPro CSP будет работать в режиме trial лицензии. .. attention:: Срок действия trial лицензии – 90 дней с момента установки CryptoPro CSP. Для сохранения работоспособности Агента СМЭВ4 по окончании данного периода, вам необходимо приобрести лицензию на CryptoPro CSP и внести её в систему как указано выше. 6. Установить контейнер ключа CryptoPro в директорию ``/var/opt/cprocsp/keys/{{user}}/``. Пользователь {{user}} должен быть владельцем данной директории и файлов в ней. 7. Для установки TLS соединения, который использует алгоритмы в соответствии с ГОСТ-2012, требуется использовать доверенное хранилище с корневыми сертификатами удостоверяющих центров (УЦ), которое находится в дистрибутиве (файл cp_ca_store). .. attention:: Ключ CryptoPro должен содержать цепочку сертификатов промежуточных УЦ (кроме корневого). :numref:`annex_a` настоящего документа содержит сведения о добавлении промежуточных сертификатов в ключ. 8. Выложить в каталог ``/distr/enfahrt`` конфигурационный файл ``application.yml``, подготовленный согласно :numref:`config_descrption`. 9. В файл ``/etc/hosts`` добавить следующие записи: .. code-block:: 172.20.59.5 podd.gosuslugi.ru 172.20.59.5 podd-cross.gosuslugi.ru 109.207.15.26 podd1.gosuslugi.ru 109.207.15.58 podd2.gosuslugi.ru 109.207.15.154 podd3.gosuslugi.ru 109.207.15.186 podd4.gosuslugi.ru 109.207.15.26 podd1-cross.gosuslugi.ru 109.207.15.58 podd2-cross.gosuslugi.ru 109.207.15.154 podd3-cross.gosuslugi.ru 109.207.15.186 podd4-cross.gosuslugi.ru .. _agent_start: Запуск Агента СМЭВ4 ~~~~~~~~~~~~~~~~~~~ Убедитесь, что пользователь {{user}} имеет доступ к директории, в которой установлен Агент СМЭВ4 (``/distr/einfahrt``). Пример раздела конфигурации скрипта для запуска Агента СМЭВ4 с использованием сервиса **systemd**: .. code-block:: bash [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 \ --add-exports=java.base/sun.net=ALL-UNNAMED \ --add-opens=java.base/jdk.internal.misc=ALL-UNNAMED \ --add-opens=java.base/java.lang=ALL-UNNAMED \ --add-opens=java.base/java.nio=ALL-UNNAMED \ --add-opens=java.xml/org.w3c.dom=ALL-UNNAMED \ --add-opens=java.base/java.util=ALL-UNNAMED \ -Dio.netty.tryReflectionSetAccessible=true \ -Dsaffron.default.charset=UTF-16LE \ -Dsaffron.default.collation.name='UTF-16LE$en_US' \ -Dsaffron.default.nationalcharset=UTF-16LE \ -XX:MaxRAMPercentage=80.0" 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/``. Далее выполнить команды по включению, запуску сервиса и проверке его статуса: .. code-block:: bash sudo systemctl daemon-reload sudo systemctl enable einfahrt sudo systemctl start einfahrt sudo systemctl -l status einfahrt .. _log_rotate: Настройка ротации логов (опционально) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Во избежание переполнения диска лог-файлами, рекомендуется настроить ротацию лог-файлов **systemd** сервиса. Настройка логирования осуществляется с помощью файлов конфигурации **logrotate** и **systemd** сервиса. Если этих файлов не существует, их необходимо создать. Первоначально необходимо установить пакет **logrotate**, для rpm-base дистрибутивов необходимо выполнить команду: .. code-block:: bash sudo yum install logrotate Добавьте в файл **systemd** сервиса (``/etc/systemd/system/einfahrt.service``) следующие настройки логирования: .. code-block:: bash ... [Service] Type=simple StandardOutput=append:/var/log/{{ file_name }} StandardError=append:/var/log/{{ file_name }} ... Создайте файл конфигурации **logrorate** ``/etc/logrotate.cron/einfahrt.conf`` и поместите в него следующее содержимое: .. code-block:: bash /var/log/{{ file_name }} { rotate {{ rotate }} size {{ file_size }} create nocompress copytruncate } где: - ``rotate`` – какое количество лог файлов оставлять, - ``file_size`` – размер лог-файла при котором будет происходить ротация. Создайте файл с скриптом запуска утилиты **logrotate**, поместите скрипт по пути ``/etc/logrotate.cron/einfahrt.sh`` .. code-block:: bash #!/bin/bash /usr/sbin/logrotate /etc/logrotate.cron/einfahrt.conf Добавьте права на запуск командой: .. code-block:: bash chmod +x /etc/logrotate.cron/einfahrt.sh Создайте правила cron, создайте файл ``/etc/cron.d/einfahrt`` и поместите в него содержимое ниже: .. code-block:: bash */1 * * * * root /etc/logrotate.cron/einfahrt_logrotate.sh Далее перезагрузите **systemd** сервис: .. code-block:: bash sudo systemctl daemon-reload sudo systemctl restart einfahrt .. _start_with_docker: Настройка и запуск Агента СМЭВ4 с использованием docker -------------------------------------------------------- Предварительные условия ~~~~~~~~~~~~~~~~~~~~~~~~~~ 1. На сервере должен быть установлен docker версии не ниже 20.10.12. 2. Создан пользователь, который будет запускать Агент СМЭВ4. 3. Этот пользователь должен иметь права на загрузку докер-образов и запуск/остановку контейнеров (т.е. добавлен в группу docker). Настройка ротации лог-файлов в docker (опционально) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Во избежание переполнения диска лог-файлами, рекомендуется настроить ротацию лог-файлов контейнеров в docker. Настройка логирования в Docker осуществляется с помощью файла конфигурации ``/etc/docker/daemon.json``. Если этого файла не существует, его необходимо создать. Добавьте в файл следующие настройки логирования: .. code-block:: json { "log-opts": { "max-file": "3", "max-size": "100m" } } где: - ``max-file`` – ограничение по количеству файлов (настройки ротации). Максимальное количество файлов журнала, которые могут быть созданы. При превышении количества самый старый файл удаляется. Действует только при установленном параметре ``max-size``. Положительное целое число. По умолчанию 1; - ``max-size`` – устанавливает ограничение по размеру лог-файла (k, m или g). По умолчанию -1 (не ограничено). Состав и содержание дистрибутивного пакета ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Ниже приведён состав дистрибутива Агента СМЭВ4 для docker. ``/distr/einfahrt`` – Агент СМЭВ4: - ``/distr/einfahrt/image.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`` использован для примера, не является фиксированным и может быть изменен на любой другой по желанию пользователя, с соответствующим внесением корректировок при его упоминаниях ниже. Ниже в качестве примера будет использоваться данный путь. .. _pre_start_docker: Подготовка к запуску ~~~~~~~~~~~~~~~~~~~~ Для запуска Агента СМЭВ4 необходимо после распаковки пакета сформировать конфигурационный файл ``application.yml``, как указано в :numref:`config` , и выложить его в каталог ``/distr/einfahrt``. .. attention:: При использовании скрипта из пакета поставки для запуска Агента параметр ``trust-store.path`` в конфигурационном файле необходимо задать строго ``/egov/java/certs/cp_ca_store``. Пример: .. code-block:: yaml trust-store: path: /egov/java/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 согласно :numref:`set_timeout`, сформированный файл выложить в каталог ``/distr/einfahrt/certs``. - выложить файл ``postgresql.json`` из пакета поставки; При наличии файла расширенных настроек логирования ``customLogLevels.xml`` выложить его в каталог ``/distr/einfahrt``. Для запуска Агента СМЭВ4 под docker полученный docker образ необходимо загрузить в локально установленный docker на машине, где будет работать Агент СМЭВ4. Для этого необходимо выложить архив с образом на локальный диск этой машины и выполнить команду: .. code-block:: bash docker load < image.tgz где ``image.tgz`` – имя полученного архива с docker image Агента СМЭВ4 из пакета поставки. Загрузка должна завершиться без ошибок. Проверить успешность загрузки можно командой: .. code-block:: bash docker images | grep einfahrt Вывод будет содержать информацию вида: .. code-block:: bash einfahrt latest c7511824117e 5 days ago 1.2G .. _start_docker: Запуск Агента СМЭВ4 ~~~~~~~~~~~~~~~~~~~~ Для запуска Агента СМЭВ4 используется скрипт ``run_agent.sh``, входящий в пакет поставки. Скрипт не требует указания параметров. При выполнении всех шагов, перечисленных в :numref:`pre_start_docker`, Агент СМЭВ4 будет успешно запущен, с сообщением о доступных портах. При повторном выполнении скрипта контейнер будет остановлен и запущен заново. Для сохранения лога Агента СМЭВ4 в файл, запустите скрипт ``log-save.sh``. Лог будет сохранен в файле ``log-дата-время.txt``. Для просмотра лога в режиме реального времени запустите скрипт ``log.sh``. В случае необходимости сбора диагностической информации для отправки в службу поддержки запустите скрипт ``diag.sh``. Остановка контейнера осуществляется скриптом ``stop.sh``. .. note:: В ряде случаев может наблюдаться остановка контейнера через несколько секунд после запуска, с сообщением в логе ``java.lang.IllegalStateException: Ошибка вызова функции acquireContext: 0x8009001a``. В этом случае следует изменить владельца каталога ``keys`` и вложенных подкаталогов и файлов на пользователя с id=1000 (потребуются root права): ``chown -R 1000 keys`` после чего повторить выполнение скрипта запуска контейнера. .. _cryptopro_lisence: Информация по лицензированию CryptoPro ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Входящие в поставку версии CryptoPro не имеют предустановленной лицензии, и могут работать как trial в течение трех месяцев с момента создания образа (не с момента первого запуска!) **Для использования trial версии CryptoPro не требуется каких-либо дополнительных действий, касающихся лицензирования.** В случае, если у Вас есть полная лицензия на CryptoPro CSP и CryptoPro JCP, предусмотрена возможность передачи номеров лицензий CSP и JCP при запуске контейнера, при передаче валидных лицензий соответствующие компоненты CryptoPro будут лицензированы на этапе запуска. Для этого необходимо, чтобы текстовый файл, содержащий сроку с лицензией на CryptoPro CSP, был при запуске контейнера доступен внутри контейнера по пути ``/egov/csp.lic``. Аналогично, лицензия для CryptoPro JCP должна быть доступна внутри контейнера в текстовом файле ``/egov/jcp.lic``. При запуске под docker-ом можно для этого монтировать внешние файлы, содержащие номера лицензий, по указанным выше путям. **Для того, чтобы прилагаемый скрипт запуска применил лицензии CryptoPro, при их наличии, их необходимо поместить в текстовые файлы ``licenses/jcp.txt`` и ``licenses/csp.txt`` соответственно. При отсутствии лицензии и использовании trial версий CryptoPRO не создавайте указанные файлы.** .. attention:: Срок действия trial лицензии – 90 дней с момента создания docker image используемого Вами Агента. Для сохранения работоспособности Агента СМЭВ4 по окончании данного периода необходимо приобрести лицензии на CryptoPro CSP и JCP и внести их в систему, как указано выше. Настройка предустановленного профиля Витрины в Агенте СМЭВ4 ------------------------------------------------------------ Раздел применим только при использовании Витрины и заданной настройке использования предустановленного профиля Витрины в Агенте СМЭВ4 (см. :numref:`reg_set`). *Файл профиля имеет настройки по умолчанию. Вносить изменения следует только в том случае, если значения по умолчанию не подходят для данной Витрины.* Настройки задаются после установки Агента ПОДД в файле ``postgresql.json``, расположенном в директории: 1. при установке без использования docker (см. :numref:`start_without_docker`): ``/директория_установленного_Агента_СМЭВ4/postgresql.json``. По умолчанию ``/distr/einfahrt/postgresql.json`` 2. при установке с использованием docker (см. :numref:`start_with_docker`): ``/egov/java/postgresql.json``. Пример предустановленного профиля Витрины в Агенте ПОДД: .. code-block:: json { "sqlDialect": "POSTGRESQL", "parameterNotionType": "QUESTION", "aggFunctions": [ ... ], "otherFunctions": [ ... ], "forSystemTimeParameterSupport": false, "subQueryParamSupport": "DYNAMIC_PARAM_SUPPORT" } где: 1) ``subQueryParamSupport`` – способ передачи подзапроса при выполнении РЗ с параметрами на сторону Витрины, возможные значения: - ``NOT_SUPPORTED`` - отправка подзапроса с параметрами, подставленными в SQL-выражение; - ``DYNAMIC_PARAM_SUPPORT`` - отправка подзапроса с блоком динамических параметров, подстановка осуществляется на стороне Адаптера Витрины; - ``NAMED_PARAM_SUPPORT`` - отправка подзапроса с блоком именованных параметров, подстановка осуществляется на стороне Адаптера Витрины. 2) ``forSystemTimeParameterSupport`` – поддержка системного параметра РЗ для запроса ак-туальных на заданный момент времени данных из Витрины: - ``false`` - Адаптер Витрины не поддерживает обработку параметра; - ``true`` - Адаптер Витрины поддерживает обработку параметра. .. _metrics: Настройка сбора метрик Агента СМЭВ4 (опционально) --------------------------------------------------- Настройка Агента СМЭВ4 для передачи метрик в Prometheus ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Агент поддерживает возможность передачи метрик работы во внешнюю систему сбора метрик **Prometheus**. Для включения возможности передачи необходимо добавить в конфигурационный файл следующие параметры: .. code-block:: yaml metrics: implementation: PROMETHEUS # порт, при обращении к которому Агент отдаёт значения метрик endpointPort: 8381 **Prometheus** следует настроить на опрос адреса, на котором запущен Агент СМЭВ4, по указанному порту. При запуске Агента под docker также необходимо добавить указанный порт в список **expose ports** в скрипте запуска Агента. Полный список метрик приведен в :numref:`annex_b`.