<note warning>Перед обновлением X-Road настоятельно рекомендуется снять snapshot сервера и backup конфигурации X-Road!</note>
 
====== Обновление Security Server X-Road с версии 7.3.2 до версии 7.4.2 на Ubuntu 22.04 ======
 
В этом документе описываются шаги, необходимые для обновления программного обеспечения X-Road Security Server с версии 7.3.2 до версии 7.4.2 на Ubuntu 22.04 LTS. Пожалуйста, внимательно прочитайте весь документ перед началом процесса обновления. Предполагается, что читатель знаком с дистрибутивом Ubuntu Linux и имеет опыт администрирования серверов безопасности X-Road.
 
<note tip>Данное обновление не затрагивает версию операционной системы и PostgreSQL. Обновляется только программное обеспечение X-Road.</note>

<note important>Внимание! В версии 7.4.0 произошли крупные изменения платформы:
  * Минимальная версия Java повышена с 11 до **17** (apt подтянет автоматически как зависимость).
  * Akka заменён на gRPC — устаревшие параметры ''akka.*'' в ''local.ini'' необходимо удалить вручную.
  * UI обновлён с Vue 2 на Vue 3, серверная часть — со Spring Boot 2 на Spring Boot 3.
  * Алгоритм хеширования глобальной конфигурации переключён с SHA-1 на SHA-256.
</note>
 
==== Подготовка ====
 
  * Убедитесь, что текущая версия X-Road — 7.3.2:
<code>
dpkg -l | grep xroad
</code>

Все пакеты должны показывать версию **7.3.2**.
 
  * Убедитесь, что все пакеты системы обновлены:
<code>
sudo apt update && sudo apt full-upgrade
</code>
 
  * ОПЦИОНАЛЬНО: убедитесь, что у вас есть актуальная резервная копия (или моментальный снимок виртуальной машины) сервера.
 
  * Сделайте резервную копию конфигурации Security Server через пользовательский интерфейс:
    * Откройте веб-интерфейс **https://SECURITYSERVER:4000/**
    * Перейдите в **Settings → Back Up and Restore**
    * Нажмите **Back Up Configuration** и скачайте файл бэкапа в безопасное место.
 
  * Дополнительно сделайте резервную копию базы данных (ОПЦИОНАЛЬНО):
<code>
sudo -iu postgres pg_dump -d serverconf -F c -f /var/lib/xroad/backup/serverconf_backup_$(date +%Y%m%d).sql
</code>
 
  * Сделайте резервную копию конфигурационных файлов X-Road:
<code>
sudo cp -r /etc/xroad /etc/xroad.backup.$(date +%Y%m%d)
</code>

  * Проверьте наличие устаревших Akka-параметров в локальной конфигурации:
<code>
sudo grep -i akka /etc/xroad/conf.d/local.ini 2>/dev/null
</code>

Если команда вернула какие-либо строки (например, ''*.akka.remote.artery.advanced.maximum-frame-size'') — эти параметры нужно удалить или закомментировать перед обновлением, так как Akka больше не используется в 7.4.0+.
 
<note warning>Не пропускайте этап резервного копирования. В случае неудачного обновления бэкап позволит восстановить работоспособность сервера.</note>
 
==== Обновление X-Road ====
 
=== Шаг 1. Остановить службы X-Road и убедиться что службы остановлены ===
 
<code>
sudo systemctl stop "xroad-*" && sudo systemctl list-units "xroad*"
</code>

<code>
UNIT LOAD ACTIVE SUB DESCRIPTION
0 loaded units listed. Pass --all to see loaded but inactive units, too.
To show all installed unit files use 'systemctl list-unit-files'.
</code>
 
=== Шаг 2. Заменить репозиторий пакетов ===

Если GPG-ключ ''/etc/apt/keyrings/xroad.asc'' отсутствует, предварительно выполните:
<code>
sudo wget -qO - https://deb.tunduk.kg/key.pub | sudo tee /etc/apt/keyrings/xroad.asc
</code>

Заменить репозиторий на версию 7.4.2 и выполнить полное обновление пакетов:
<code>
sudo rm /etc/apt/sources.list.d/xroad.list && echo "deb [signed-by=/etc/apt/keyrings/xroad.asc] https://deb.tunduk.kg/ubuntu22.04-7.4.2 /" | sudo tee /etc/apt/sources.list.d/xroad.list && sudo apt-get update && sudo apt-get -y full-upgrade
</code>
 
 
=== Шаг 3. Запустить службы X-Road ===
 
<code>
sudo systemctl start "xroad-*"
</code>
 
Или запустить через основной сервис:
<code>
sudo systemctl start xroad-proxy
</code>
 
==== Проверка после обновления ====
 
=== Проверка версии пакетов ===
 
<code>
dpkg -l | grep xroad
</code>
 
Все пакеты должны показывать версию **7.4.2**.
 
=== Проверка состояния служб ===
 
<code>
sudo systemctl list-units "xroad*"
</code>
 
Ожидаемый результат:
<code>
  UNIT                           LOAD   ACTIVE SUB     DESCRIPTION               
  xroad-addon-messagelog.service loaded active running X-Road Messagelog Archiver
  xroad-base.service             loaded active exited  X-Road initialization     
  xroad-confclient.service       loaded active running X-Road confclient         
  xroad-monitor.service          loaded active running X-Road Monitor            
  xroad-opmonitor.service        loaded active running X-Road opmonitor daemon   
  xroad-proxy-ui-api.service     loaded active running X-Road Proxy UI REST API  
  xroad-proxy.service            loaded active running X-Road Proxy              
  xroad-signer.service           loaded active running X-Road signer
</code>

=== Настройка портов точки доступа информационной системы ===

<note warning>Внимание! В версии 7.4.0 на Ubuntu порты точки доступа информационной системы по умолчанию изменены с 80/443 на 8080/8443. Чтобы сервер безопасности продолжил принимать запросы от информационных систем на портах 80 и 443, необходимо вручную переопределить значения в конфигурационном файле.</note>

  * Открыть (или создать, если отсутствует) файл локальных переопределений конфигурации
<code>sudo nano /etc/xroad/conf.d/local.ini</code>

  * Добавить секцию ''[proxy]'' (если её нет):
<code>
[proxy]
client-http-port=80
client-https-port=443
</code>

  * Установить корректные права и владельца файла
<code>
sudo chown xroad:xroad /etc/xroad/conf.d/local.ini
sudo chmod 640 /etc/xroad/conf.d/local.ini
</code>

  * Перезапустить службу proxy
<code>sudo systemctl restart xroad-proxy</code>

  * Убедиться, что порты сменились на 80 и 443
<code>sudo ss -tlnp | grep -E ':(80|443|8080|8443)\s'</code>
 
=== Проверка веб-интерфейса ===
 
Откройте **https://SECURITYSERVER:4000/** в веб-браузере. Для входа используйте учётную запись, заданную при установке.
 
<note tip>Для запуска веб-интерфейса требуется некоторое время. Вы можете увидеть ошибку «502 Bad Gateway» — подождите 1-2 минуты и обновите страницу.</note>

=== Проверка глобальной конфигурации ===

Перейдите в раздел **Diagnostics** в веб-интерфейсе и убедитесь, что статус **Global configuration** — «OK».

<note tip>Если статус «Failure» или «Error» — возможно, требуется новый файл привязки глобальной конфигурации (configuration anchor), сгенерированный после обновления Central Server. Запросите актуальный anchor у администраторов СМЭВ "Тундук" и загрузите его через **Settings → System Parameters → Configuration Anchor → Upload**.</note>
 
=== Проверка OCSP статуса сертификатов ===
 
Перейдите в раздел **Keys and Certificates** и убедитесь, что OCSP статус сертификатов — «Good».
 
<note tip>Если OCSP статус «Unknown» — перезапустите службу ''systemctl restart xroad-proxy'' или дождитесь автоматического обновления (по умолчанию раз в 48 минут). Также можно проверить статус в разделе **Diagnostics**.</note>
 
=== Проверка логов ===
 
<code>
sudo journalctl -u xroad-proxy -n 100 --no-pager
sudo journalctl -u xroad-signer -n 50 --no-pager
</code>
 
Убедитесь, что в логах нет критических ошибок.

=== Проверка версии Java ===

<code>
java -version
</code>

Ожидаемый результат должен содержать ''openjdk version "17.x.x"''. Java 17 ставится автоматически как зависимость при обновлении пакетов X-Road 7.4.2.

<note important>Если в файле ''/etc/xroad/services/local.conf'' есть строка с ''JAVA_HOME'' — удалите её. Это актуально только для серверов, которые обновлялись с версий до 7.0.0.</note>
 
==== Пост-обновление: что нужно знать ====
 
=== Автоматические бэкапы ===
 
Начиная с версии 7.3.0, расписание автоматических бэкапов задаётся не через cron, а через параметр в файле ''/etc/xroad/conf.d/local.ini''.
 
Если вы ранее изменяли расписание бэкапов в файле ''/etc/cron.d/xroad-proxy'', перенесите настройку вручную:
 
<code>
sudo nano /etc/xroad/conf.d/local.ini
</code>
 
Добавьте или отредактируйте секцию:
<code>
[configuration-client]
proxy-configuration-backup-cron=0 15 3 * * ?
</code>
 
После изменения перезапустите конфигурационный клиент:
<code>
sudo systemctl restart xroad-confclient
</code>
 
=== Удалённые и переименованные свойства конфигурации ===

В версии 7.4.0 на Security Server **полностью удалены** следующие параметры rate limiting — если они присутствуют в ''local.ini'', их необходимо убрать:

  * ''ratelimit.requests.per.second''
  * ''ratelimit.requests.per.minute''

Следующие свойства считаются устаревшими (deprecated), но продолжают работать:
 
^ Старое свойство ^ Новое свойство ^
| ''request.sizelimit.regular'' | ''proxy-ui-api.request-sizelimit-regular'' |
| ''request.sizelimit.binary.upload'' | ''proxy-ui-api.request-sizelimit-binary-upload'' |
 
Рекомендуется при возможности перейти на новые имена свойств.

=== Akka-параметры ===

После замены Akka на gRPC в 7.4.0 любые параметры вида ''*.akka.*'' в ''/etc/xroad/conf.d/local.ini'' игнорируются и должны быть удалены вручную (см. раздел «Подготовка»).
 
==== Откат обновления ====
 
В случае проблем после обновления:
 
=== Вариант 1: Восстановление из snapshot ===
 
Если перед обновлением был сделан snapshot виртуальной машины — восстановите его.
 
=== Вариант 2: Откат пакетов на версию 7.3.2 ===
 
Удалить репозиторий 7.4.2:
<code>
sudo rm /etc/apt/sources.list.d/xroad.list
</code>
 
Добавить репозиторий 7.3.2:
<code>
echo "deb [signed-by=/etc/apt/keyrings/xroad.asc] https://deb.tunduk.kg/ubuntu22.04-7.3.2 /" | sudo tee /etc/apt/sources.list.d/xroad.list
</code>
 
Выполнить переустановку:
<code>
sudo apt-get update
sudo apt-get install --reinstall xroad-securityserver xroad-addon-opmonitoring
</code>

<note tip>Остальные пакеты X-Road подтянутся автоматически как зависимости основного метапакета.</note>
 
=== Вариант 3: Восстановление конфигурации из бэкапа ===
 
Если конфигурация повреждена, восстановите её из резервной копии:
<code>
sudo -u xroad /usr/share/xroad/scripts/restore_xroad_proxy_configuration.sh \
  -s <security server ID> \
  -f /var/lib/xroad/backup/<backup_file>.tar
</code>
 
==== Поиск неисправностей ====
 
=== Службы не стартуют после обновления ===
 
Проверьте логи конкретного сервиса:
<code>
sudo journalctl -u xroad-proxy -n 200 --no-pager
sudo journalctl -u xroad-signer -n 200 --no-pager
sudo journalctl -u xroad-proxy-ui-api -n 200 --no-pager
</code>
 
=== Ошибка «502 Bad Gateway» не пропадает ===
 
Убедитесь, что сервис ''xroad-proxy-ui-api'' запущен:
<code>
sudo systemctl status xroad-proxy-ui-api
</code>
 
Если сервис не запускается, проверьте лог:
<code>
sudo tail -100 /var/log/xroad/proxy_ui_api.log
</code>
 
=== Проблемы с базой данных ===
 
Проверьте доступность базы данных:
<code>
sudo -u postgres psql -c "SELECT pg_database.datname, 
       pg_size_pretty(pg_database_size(pg_database.datname)) AS size 
FROM pg_database 
WHERE datname IN ('serverconf', 'messagelog', 'op-monitor');"
</code>
 
При необходимости восстановите базу данных из резервной копии:
<code>
sudo -iu postgres pg_restore -d serverconf -c /var/lib/xroad/backup/serverconf_backup_YYYYMMDD.sql
</code>
 
=== Проблемы с токеном ===
 
Если после обновления токен не активен:
 
  * Перейдите в **Keys and Certificates**
  * Нажмите **Log In** на нужном токене и введите PIN-код
 
----
 
Автор Кирилл Захаров, Даниил Горбенко