Zodiac.ITM: установка на Astra Linux 1.8

1. Назначение

Данная инструкция описывает AIO-развёртывание Zodiac.ITM на Astra Linux 1.8 x86-64.

AIO-развёртывание (all-in-one, «всё в одном») означает размещение всех серверных компонентов Zodiac.ITM, Keycloak и PostgreSQL на одном хосте. Такая схема подходит для небольших автономных инсталляций и пилотных внедрений.
При масштабировании компоненты можно будет разнести по отдельным узлам.

Версии ПО, используемые в данной инструкции:

Для использования в продуктивной среде необходимо заменить пароли и самоподписанный сертификат, настроить резервное копирование, ограничить административные порты. Минимальная конфигурация для тестового AIO-развёртывания - 4 CPU и 8 Gb RAM.

2. Топология и имена AIO-развёртывания

В данной инструкции все компоненты установлены на одном сервере:

Если DNS по какой-то причине не настроен, например выполняется тестовое развертывание, то нужно будет на сервере и на каждом клиенте добавьте DNS-имена в /etc/hosts (или C:\Windows\System32\drivers\etc\hosts). В том числе на компьютере администратора Zodiac, через браузер которого осуществляется настройка и работа с Zodiac.ITM
Но более правильным решением является настрока DNS и внесении соответствующих записей.

Ниже в инструкции используется условный внутренний адрес 192.168.1.100; замените его на фактический IP сервера в вашей сети:

192.168.1.100 keycloak.test zodiac-admin.test zodiac-comm.test zodiac-ra.test zodiac-relay.test

В рабочей сети используйте корпоративный DNS.

3. Минимальные требования

Требуется:

• минимум 2 CPU;
• минимум 4 Gb RAM для AIO-развёртывания;
• минимум 20 Gb свободного места для AIO-развёртывания, рекомендуемый объем диска - от 100 Gb;
• доступ к репозиториям Astra;
• дистрибутив Zodiac.

Учетная запись для установки

Установку выполняйте под обычным административным пользователем, например
zodiac-installer, имеющим право выполнять команды через sudo. Если в
системе уже создан другой административный пользователь, используйте его и
замените zodiac-installer в примерах на его имя.

Прямой вход по SSH под пользователем root для установки не требуется и не
рекомендуется. Проверьте права текущего пользователя:

whoami
sudo -v

Команды без sudo выполняются от имени текущего административного пользователя.
Системные изменения выполняются с префиксом sudo. Пользователи postgres и
keycloak используются только для отдельных операций через sudo -u и не
являются учетными записями для входа администратора.

Рабочий каталог дистрибутива

Команды с путями, начинающимися с ./, выполняйте из корня распакованного
дистрибутива Zodiac. Перед выполнением таких команд перейдите в его каталог,
например в данном развертывании будет использоваться:

cd /home/zodiac-installer/zodiac

Путь /home/zodiac-installer/zodiac приведён как пример: замените его на
фактический каталог, в который распакован дистрибутив. Пути ./dbscripts/...,
./certtool/... и ./*.deb являются относительными путями к этому каталогу.
Пути системной конфигурации (/etc, /opt, /var, /tmp) в инструкции
указаны абсолютными и не зависят от текущего рабочего каталога.

Установите базовые пакеты (если отсутствуют):

sudo apt update
sudo apt install -y ca-certificates curl openssl unzip ufw chrony postgresql postgresql-contrib
sudo systemctl enable --now chrony postgresql

Проверьте:

cat /etc/os-release
uname -a
psql --version
timedatectl status
systemctl is-active postgresql chrony

4. Firewall

Настройте сетевой фильтр до запуска Keycloak и серверов Zodiac. Сначала
убедитесь, что правило SSH добавлено, чтобы не потерять удалённый доступ:

sudo ufw allow 22/tcp comment 'SSH'
sudo ufw allow 8443/tcp comment 'Keycloak HTTPS'
sudo ufw allow 3000/tcp comment 'Zodiac Administration'
sudo ufw allow 3001/tcp comment 'Zodiac Communication'
sudo ufw allow 21118/tcp comment 'Zodiac Remote Assistance Server'
sudo ufw allow 21119/tcp comment 'Zodiac Remote Assistance Relay'
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw --force enable
sudo ufw status verbose

PostgreSQL 5432 наружу не открывайте в AIO-развёртывании.

5. PostgreSQL

В AIO-развёртывании используется отдельная техническая роль:

Role: zodiac
Database: zodiac
Password: zodiac

Для рабочей установки используйте длинный случайный пароль и не храните его в shell history.

При выполнении команд, возможно появление стандартного предупреждения:
could not change directory to "/root": Отказано в доступе
Оно появляется, когда команда запускается от имени postgres, но текущий рабочий каталог остаётся /root, куда пользователь postgres не имеет доступа. Его появление не влияет на успешность установки.

Создайте роль и базу:

sudo -u postgres psql

Выполните:

CREATE ROLE zodiac LOGIN PASSWORD 'zodiac';
CREATE DATABASE zodiac OWNER zodiac ENCODING 'UTF8' TEMPLATE template0;
\q

Распакуйте из дистрибутива файл dbscripts/create-or-migrate-db.sql и выполните его от имени владельца базы:

PGPASSWORD=zodiac psql -h 127.0.0.1 -p 5432 -U zodiac -d zodiac -f ./dbscripts/create-or-migrate-db.sql

Проверьте схему:

PGPASSWORD=zodiac psql -h 127.0.0.1 -U zodiac -d zodiac -c '\dt'
unset PGPASSWORD

Не открывайте PostgreSQL наружу в AIO-развёртывании. listen_addresses='*' и широкие правила pg_hba.conf нужны только при обоснованном удаленном доступе.

6. Сертификат и доверие

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

1. корневой самоподписанный CA-сертификат;
2. транспортный сертификат сервера, подписанный этим CA.

Корневой CA-сертификат должен быть добавлен в доверенные хранилища всех
серверных и клиентских машин в контуре. Транспортный сертификат вместе с
закрытым ключом устанавливается на серверы, которые принимают HTTPS-соединения:
Keycloak, Administration Server, Communication Server и Remote Assistance.
В Zodiac транспортный сертификат дополнительно импортируется через
CertificateTool, а его Thumbprint указывается в секциях [Certificate].

В этой инструкции для AIO тестового стенда используется упрощённый
вариант с одним самоподписанным сертификатом. Он может работать после явного
добавления сертификата в доверенные, но для рабочей сети предпочтительна
двухуровневая цепочка с отдельным CA.

Для теста создайте сертификат с SAN для всех имен:

sudo install -d -m 0750 /etc/zodiac/tls
sudo openssl req -x509 -nodes -newkey rsa:2048 -days 825 \
  -keyout /etc/zodiac/tls/zodiac.key \
  -out /etc/zodiac/tls/zodiac.crt \
  -subj /CN=keycloak.test \
  -addext 'subjectAltName=DNS:keycloak.test,DNS:zodiac-admin.test,DNS:zodiac-comm.test,DNS:zodiac-ra.test,DNS:zodiac-relay.test,IP:192.168.1.100'

sudo chmod 640 /etc/zodiac/tls/zodiac.key
sudo chmod 644 /etc/zodiac/tls/zodiac.crt
sudo cp /etc/zodiac/tls/zodiac.crt /usr/local/share/ca-certificates/zodiac-test.crt
sudo update-ca-certificates

Адрес 192.168.1.100 в примере является placeholder. Перед установкой
замените его на фактический внутренний IP сервера и используйте тот же адрес
в записи /etc/hosts и в SAN сертификата.

После создания проверьте SAN:

openssl x509 -in /etc/zodiac/tls/zodiac.crt -noout -subject -issuer -dates -ext subjectAltName

Для рабочей сети используйте сертификат корпоративного CA. Закрытый ключ не копируйте на клиентские машины.

6.1 Хранилище сертификата Zodiac

update-ca-certificates добавляет сертификат только в системное хранилище
доверия Linux. Серверные компоненты Zodiac дополнительно используют своё
хранилище сертификатов, поэтому сертификат нужно импортировать через
CertificateTool с правами root через sudo.

В используемой версии CertificateTool команда add принимает один PFX-файл.

Выполняйте следующую команду из корня распакованного дистрибутива Zodiac,
где расположен каталог certtool.

Распакуйте Linux-версию CertificateTool из каталога certtool дистрибутива:

sudo mkdir -p /opt/zodiac
sudo tar -xf ./certtool/certtool.linux.x64.tar -C /opt/zodiac
sudo chmod 755 /opt/zodiac/certtool/Zodiac.CertificateTool

Соберите его из сертификата и закрытого ключа:

sudo openssl pkcs12 -export \
  -out /tmp/zodiac-server.pfx \
  -inkey /etc/zodiac/tls/zodiac.key \
  -in /etc/zodiac/tls/zodiac.crt \
  -passout pass:zodiac

Запустите импорт в настоящем TTY с правами root через sudo:

sudo /opt/zodiac/certtool/Zodiac.CertificateTool add /tmp/zodiac-server.pfx

Введите пароль PFX при запросе. При успешном выполнении команда выводит
Thumbprint сертификата. Используйте его значение без двоеточий в параметре
Thumbprint секций [Certificate] конфигураций Administration Server,
Communication Server, RA Server и Relay.

Запускайте CertificateTool add в настоящем интерактивном TTY через sudo.
Инструмент читает пароль через Console.ReadKey; перенаправление пароля через
pipe или stdin может завершиться ошибкой.

На отдельных клиентских машинах и узлах с удалёнными Agent установите
корневой CA-сертификат в системное доверенное хранилище каждого узла. Для
тестовой схемы с одним самоподписанным сертификатом добавьте вместо него сам
тестовый сертификат.

7. Keycloak 25.0.6 на штатном OpenJDK 17

7.1 Установка

Astra Linux 1.8 поставляет OpenJDK 17. Установите штатный JDK из
репозитория Astra:

sudo apt update
sudo apt install -y openjdk-17-jdk
java -version

Скачайте Keycloak 25.0.6 с официальной страницы релизов, распакуйте его
в /opt и создайте ссылку:

cd /tmp
curl -fLO https://github.com/keycloak/keycloak/releases/download/25.0.6/keycloak-25.0.6.tar.gz
sudo tar -xzf keycloak-25.0.6.tar.gz -C /opt
sudo ln -s /opt/keycloak-25.0.6 /opt/keycloak
sudo useradd --system --home-dir /opt/keycloak --shell /usr/sbin/nologin keycloak
sudo chown -R keycloak:keycloak /opt/keycloak-25.0.6
/opt/keycloak/bin/kc.sh --version

Ожидается:

Keycloak 25.0.6
JVM: 17.0.17

7.2 Встроенная H2

В этом AIO-развёртывании Keycloak не использует PostgreSQL. Zodiac использует
PostgreSQL, а Keycloak использует собственную H2 dev-file.

Keycloak в Zodiac используется для аутентификации администраторов системы. Число управляемых устройств с установленными агентами
не определяет нагрузку на Keycloak напрямую: основные соединения агентов проходят через сервер коммуникаций.

Поэтому встроенная H2 dev-file подходит для данного автономного AIO-развёртывания,
даже при значительном количестве управляемых устройств, если число
администраторов небольшое и нет требований к отказоустойчивости. Для
инсталляций с высокими требованиями к отказоустойчивости, резервированию или
масштабированию самого Keycloak используйте поддерживаемую внешнюю СУБД согласно
документации Keycloak.

7.3 systemd

Для Keycloak 25 используйте старые переменные начального администратора:

KEYCLOAK_ADMIN=admin
KEYCLOAK_ADMIN_PASSWORD=zodiac

Создайте /etc/systemd/system/keycloak.service:

sudo nano /etc/systemd/system/keycloak.service

Вставьте в файл следующее содержимое:

[Unit]
Description=Keycloak
After=network-online.target
Wants=network-online.target

[Service]
User=keycloak
Group=keycloak
WorkingDirectory=/opt/keycloak
Environment=KEYCLOAK_ADMIN=admin
Environment=KEYCLOAK_ADMIN_PASSWORD=zodiac
Environment=JAVA_OPTS_APPEND=-Xms64m -Xmx256m
ExecStart=/opt/keycloak/bin/kc.sh start --db=dev-file --cache=local --https-certificate-file=/etc/zodiac/tls/zodiac.crt --https-certificate-key-file=/etc/zodiac/tls/zodiac.key --https-port=8443 --hostname=https://keycloak.test:8443 --hostname-strict=true
Restart=on-failure
RestartSec=5
TimeoutStartSec=300
TimeoutStopSec=300

[Install]
WantedBy=multi-user.target

Права на ключ должны позволять чтение пользователю keycloak:

sudo chown root:keycloak /etc/zodiac/tls
sudo chmod 750 /etc/zodiac/tls
sudo chown root:keycloak /etc/zodiac/tls/zodiac.key
sudo chmod 640 /etc/zodiac/tls/zodiac.key
sudo systemctl daemon-reload
sudo systemctl enable --now keycloak

Проверка:

systemctl is-active keycloak
for i in $(seq 1 30); do
  if bash -c '</dev/tcp/127.0.0.1/8443' 2>/dev/null; then
    break
  fi
  sleep 1
done
ss -ltnp | grep ':8443\b'
curl -kI https://keycloak.test:8443/realms/master/.well-known/openid-configuration

Ожидается HTTP 200 для OIDC discovery.

В данной инструкции указывается Authority="https://keycloak.test:8443/realms/master", поскольку используется Keycloak 25, где по умолчанию нет префикса /auth.
В более старых версиях Keycloak может использоваться путь /auth/realms/master, тогда Authority="https://keycloak.test:8443/auth/realms/master"

Можно получить значение Authority для своего стенда, запросив OIDC discovery:

curl --fail --silent --show-error https://keycloak.test:8443/realms/master/.well-known/openid-configuration

В ответе найдите поле issuer. Его значение используйте как Authority в конфигурациях Administration Server, RA Server и Relay, если они используют один OIDC-провайдер и один realm.

Если Keycloak опубликован с префиксом /auth, добавьте этот префикс перед /realms/master в адресе discovery:

curl --fail --silent --show-error https://keycloak.test:8443/auth/realms/master/.well-known/openid-configuration

Проверка должна проходить с доверенным сертификатом, без отключения TLS-проверки через -k.

7.4 Клиент Zodiac

Откройте в браузере Keycloak Admin Console:

https://keycloak.test:8443/admin/

Войдите учётной записью начального администратора, коотрая была заведена выше:

Для нашей инструкции это

Login: admin
Password: zodiac

В селекторе realm в левом верхнем углу выберите master, затем в левом
меню откройте Clients → Create client.

Создайте клиент со следующими параметрами:

Client type: OpenID Connect
Client ID: zodiac
Capability config → Standard flow: On
Capability config → Client authentication: Off

Для Zodiac создается публичный OIDC-клиент: параметр Capability config → Client authentication должен быть выключен (Off).
В этом режиме Keycloak не выдаёт клиенту Client Secret. Не создавайте и не добавляйте секрет в конфигурации серверов Zodiac!
Public client — это не про безопасность пользователя. Термин описывает лишь то, что у приложения нет Client Secret, так как используется браузер и SPA web-приложение. Защита входа обеспечивается HTTPS, точной проверкой redirect URI и валидацией токенов. Для SPA публичный клиент — рекомендованная конфигурация OIDC.

Login settings → Valid redirect URIs:

https://zodiac-admin.test:3000/*
https://zodiac-ra.test:21118/*

Login settings → Web Origins:

https://zodiac-admin.test:3000
https://zodiac-ra.test:21118

Не используйте одиночный wildcard * в полях Redirect URI и Web Origins для рабочих конфигураций:
Redirect URI: *
Web Origins: *
он позволяет перенаправление и запросы с непредусмотренных адресов.

Далее, сохраняем клиента с указанными выше настройками кнопкой Save.

Затем, в карточке клиента zodiac:

откройте вкладку Client scopes.
В таблице найдите автоматически созданную ссылку zodiac-dedicated с описанием Dedicated scope and mappers for this client и откройте её:

Эта ссылка ведёт на страницу Dedicated scopes клиента zodiac.

На странице Dedicated scopes нажмите Configure a new mapper.

В списке типов выберите Audience и в открывшемся окне Add mapper заполните поля:

Mapper type: Audience
Name: zodiac-audience
Included Client Audience: zodiac
Add to ID token: Off
Add to access token: On
Add to lightweight access token: Off
Add to token introspection: On

Нажмите Save.

Затем вернитесь в карточку клиента zodiac, откройте вкладку Roles и
нажмите Create role. Создайте две client roles, каждую отдельным действием:

zodiac_ac_sa
zodiac_ac_ra

Создайте пользователя и назначьте ему client role:

1. В левом меню откройте Users → Add user.
2. В поле Username укажите zodiac-admin и нажмите Create.
3. Откройте вкладку Credentials, нажмите Set password, задайте пароль, отключите Temporary и нажмите Save.
4. Откройте вкладку Role mapping. Нажмите Assign role, выберите роль zodiac_ac_sa и нажмите Assign для подтверждения.

Для полной проверки ролевого каталога можно также назначить client role
zodiac_ac_ra, но супер-администратору для полного доступа достаточно
zodiac_ac_sa.

Проверяемый access token должен содержать:

"aud": ["zodiac", "account"],
"resource_access": {
  "zodiac": {
    "roles": ["zodiac_ac_sa"]
  }
}

7.5 Профиль пользователя

Для передачи имени и фамилии заполните у пользователя Keycloak поля First name и Last name. Это влияет на claims name, given_name и family_name, но не заменяет роли и не определяет права Zodiac.

7.6 Опциональная оптимизация запуска (--optimized)

Приведенный выше ExecStart собирает конфигурацию при каждом запуске. Для
продакшена Keycloak поддерживает предварительную сборку через kc.sh build,
после которой kc.sh start --optimized стартует быстрее, так как пропускает
build-фазу.

sudo -u keycloak /opt/keycloak/bin/kc.sh build --db=dev-file

После сборки замените в ExecStart флаг start на start --optimized и
уберите из командной строки параметры, которые уже зафиксированы сборкой
(--db). Остальные рантайм-параметры (--https-*, --hostname*, --cache)
можно оставить как раньше.

Важно: при любом изменении параметров, зафиксированных на этапе build
(например, --db), нужно заново выполнить kc.sh build, иначе --optimized
либо откажется стартовать, либо запустится со старой конфигурацией. Для
простого AIO-развёртывания с редкими изменениями конфигурации этот шаг
необязателен; используйте его, если требуется минимизировать время старта на
медленном хосте.

8. Zodiac: дистрибутив и версии

Состав дистрибутива:

Administration Server 1.8.х
Communication Server 1.8.х
Agent 1.8.х
Remote Assistance Server 1.8.х
Remote Assistance Relay 1.8.х

Для Astra с CPU, поддерживающим AVX/AVX2, использовался пакет Communication Server:

zodiac.communication.server.debian12.x64.1.8.x.avx.deb

Остальные Linux-пакеты:

zodiac.administration.server.linux.x64.1.8.x.deb
zodiac.remoteassistance.server.linux.x64.1.8.x.deb
zodiac.remoteassistance.relay.linux.x64.1.8.x.deb
zodiac.agent.linux.x64.1.8.x.deb

Проверяйте наличие поддержки AVX перед выбором AVX-пакета:

lscpu | grep -E 'Model name|Flags'

В именах пакетов 1.8.x обозначает номер версии-подстановки. Перед
установкой замените x на фактический номер версии файлов из вашего
дистрибутива.

9. Общие каталоги Zodiac

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

Создайте каталоги до настройки внешних конфигураций серверов:

sudo install -d -m 0750 /var/zodiac/updates
sudo install -d -m 0750 /var/zodiac/updates_temp
sudo install -d -m 0750 /var/zodiac/scatter-packages
sudo install -d -m 0750 /var/zodiac/uploads
sudo install -d -m 0750 /var/zodiac/audit

Пути приведены по шаблону конфигурации, используемому в данном развертывании. Пути определяются при конфигурировании серверов .ini.

10. Установка серверных пакетов

Установите четыре серверных .deb:

sudo apt install \
  ./zodiac.administration.server.linux.x64.1.8.x.deb \
  ./zodiac.communication.server.debian12.x64.1.8.x.avx.deb \
  ./zodiac.remoteassistance.server.linux.x64.1.8.x.deb \
  ./zodiac.remoteassistance.relay.linux.x64.1.8.x.deb

Пакеты автоматически создают systemd units и пытаются запустить службы. До появления рабочих .ini это может завершиться кодом 99, это ожидаемо.

11. Конфигурации серверов

В приведённых ниже конфигурациях замените
REPLACE_WITH_CERTIFICATE_THUMBPRINT на Thumbprint, который вывел
CertificateTool после импорта сертификата.

11.1 Administration Server

Создайте файл конфигурации:

/var/zodiac/administration-server/administration.ini:

URLS="https://zodiac-admin.test:3000/"

[Kestrel:EndpointDefaults]
Protocols=Http1

[Certificate]
Store=CurrentUser
Thumbprint=REPLACE_WITH_CERTIFICATE_THUMBPRINT

[WebInterface]
WebAdministrationUrl="https://zodiac-admin.test:3000/"
Authenticate=true
ShowPii=true

[Roles]
Enabled=true
SaExprs="$.resource_access.zodiac.roles[?(@ == 'zodiac_ac_sa')];$.roles[?(@ == 'zodiac_ac_sa')]"
RaExprs="$.resource_access.zodiac.roles[?(@ == 'zodiac_ac_ra')];$.roles[?(@ == 'zodiac_ac_ra')]"

[ConnectionStrings]
ZodiacContext="Server=127.0.0.1;Port=5432;Database=zodiac;UserID=zodiac;Password=zodiac;"

[Packages]
Dir="/var/zodiac/scatter-packages"

[OTA]
AgentDir="/var/zodiac/updates"
TempDir="/var/zodiac/updates_temp"

[Audit]
LogFileOn=false

[CommonFiles]
Dir="/var/zodiac/uploads"

[DataProtection]
SecretPhrase="MySecret"

[OidcConfiguration]
ClientId="zodiac"
RedirectUri="https://zodiac-admin.test:3000/#/authentication/callback"
ResponseType="code"
PostLogoutRedirectUri="https://zodiac-admin.test:3000/"
Scope="openid profile email"
Authority="https://keycloak.test:8443/realms/master"
AutomaticSilentRenew=true
LoadUserInfo=true
AdministrationAudience="zodiac"

11.2 Communication Server

Создайте файл конфигурации:

/var/zodiac/communication-server/communication.ini:

URLS="https://zodiac-comm.test:3001/"

[Certificate]
Store=CurrentUser
Thumbprint=REPLACE_WITH_CERTIFICATE_THUMBPRINT

[ConnectionStrings]
ZodiacContext="Server=127.0.0.1;Port=5432;Database=zodiac;UserID=zodiac;Password=zodiac;"

[Packages]
Dir="/var/zodiac/scatter-packages"

[OTA]
AgentDir="/var/zodiac/updates"

[CommonFiles]
Dir="/var/zodiac/uploads"

[DataProtection]
SecretPhrase="MySecret"

Если выбранный шаблон пакета содержит Processing:TakeLimit, перенесите эту секцию из шаблона дистрибутива.

11.3 Установка и проверка серверов

sudo systemctl daemon-reload
sudo systemctl restart zodiac.administration.server.service
sudo systemctl restart zodiac.communication.server.service
systemctl is-active zodiac.administration.server.service zodiac.communication.server.service

for i in $(seq 1 30); do
  admin_ready=$(bash -c '</dev/tcp/127.0.0.1/3000' 2>/dev/null && echo yes || echo no)
  comm_ready=$(bash -c '</dev/tcp/127.0.0.1/3001' 2>/dev/null && echo yes || echo no)
  if [ "$admin_ready" = yes ] && [ "$comm_ready" = yes ]; then
    break
  fi
  sleep 1
done
ss -ltnp | grep -E ':(3000|3001)\b'
curl --fail --silent --show-error --max-time 10 -kI https://zodiac-admin.test:3000/
curl --silent --show-error --max-time 10 -kI https://zodiac-comm.test:3001/

systemctl restart возвращает управление после запуска процесса, а не после
того, как приложение завершило JIT, DI, подключение к PostgreSQL и привязало
Kestrel-сокет. Поэтому проверяйте готовность отдельно: приведенный цикл ждет
до 30 секунд появления обоих TCP-портов. Цикл завершается сразу после готовности
обоих сервисов и не выдерживает весь интервал без необходимости. Если порты не
появились, изучите журналы до повторного запуска:

journalctl -u zodiac.administration.server.service -n 100 --no-pager
journalctl -u zodiac.communication.server.service -n 100 --no-pager

Для Communication Server ответ 404 на корневой URL API допустим: в этой
проверке важнее успешное TCP-соединение и отсутствие ошибки запуска. Для
Administration Server ожидается ответ 200 или перенаправление 3xx.

Для API Communication Server ответ 404 на корневой URL не обязательно означает ошибку. Проверяйте состояние systemd и журнал.

12. Remote Assistance в AIO-развёртывании

В AIO-развёртывании работает один RA Server и один Relay. Балансировщик и
RendezvousKey не требуются.

Создайте и заполните внешние конфигурационные файлы для RA Server и Relay.

12.1 RA Server

Создайте файл конфигурации:

/var/zodiac/remoteassistance-server/remoteassistance-server.ini:

URLS="https://zodiac-ra.test:21118/"

[Settings]
IdServer=zodiac-ra.test:21118
LaFlushInterval=00:01:00

[Roles]
Enabled=true
SaExprs="$.resource_access.zodiac.roles[?(@ == 'zodiac_ac_sa')];$.roles[?(@ == 'zodiac_ac_sa')]"
RaExprs="$.resource_access.zodiac.roles[?(@ == 'zodiac_ac_ra')];$.roles[?(@ == 'zodiac_ac_ra')]"

[ConnectionStrings]
ZodiacContext="Server=127.0.0.1;Port=5432;Database=zodiac;UserID=zodiac;Password=zodiac;"

[Certificate]
Store=CurrentUser
Thumbprint=REPLACE_WITH_CERTIFICATE_THUMBPRINT

[OidcConfiguration]
ClientId="zodiac"
RedirectUri="https://zodiac-ra.test:21118/api/oidc/callback"
Scope="openid profile email"
Authority="https://keycloak.test:8443/realms/master"
UseSystemTls=true
Audience=zodiac

[DataProtection]
SecretPhrase="MySecret"

[Audit]
LogFileOn=false

[RaServers:All]
node1=zodiac-ra.test:21118

[RaRelays:All]
node1=zodiac-relay.test:21119

[Logging:LogLevel]
Default=Warning
Zodiac=Information
Microsoft.Hosting.Lifetime=Information

Не добавляйте RendezvousKey в AIO-развёртывании. Для нескольких RA Server-нodes сгенерируйте один общий ключ и укажите один и тот же PrivateKeyFile на всех копиях. В секции RaServers:All перечисляйте внутренние адреса всех RA Server, включая текущий. Через балансировщик эти адреса заменять нельзя.

12.2 Relay

Создайте файл конфигурации:

/var/zodiac/remoteassistance-relay/remoteassistance-relay.ini:

URLS="https://zodiac-relay.test:21119/"

[Roles]
Enabled=true
SaExprs="$.resource_access.zodiac.roles[?(@ == 'zodiac_ac_sa')];$.roles[?(@ == 'zodiac_ac_sa')]"
RaExprs="$.resource_access.zodiac.roles[?(@ == 'zodiac_ac_ra')];$.roles[?(@ == 'zodiac_ac_ra')]"

[ConnectionStrings]
ZodiacContext="Server=127.0.0.1;Port=5432;Database=zodiac;UserID=zodiac;Password=zodiac;"

[Certificate]
Store=CurrentUser
Thumbprint=REPLACE_WITH_CERTIFICATE_THUMBPRINT

[OidcConfiguration]
ClientId="zodiac"
RedirectUri="https://zodiac-ra.test:21118/api/oidc/callback"
Scope="openid profile email"
Authority="https://keycloak.test:8443/realms/master"
UseSystemTls=true
Audience=zodiac

[DataProtection]
SecretPhrase="MySecret"

[Logging:LogLevel]
Default=Warning
Zodiac=Information
Microsoft.Hosting.Lifetime=Information

Запустите:

sudo systemctl daemon-reload
sudo systemctl restart zodiac.remoteassistance.server.service
sudo systemctl restart zodiac.remoteassistance.relay.service
systemctl is-active zodiac.remoteassistance.server.service zodiac.remoteassistance.relay.service

for i in $(seq 1 30); do
  ra_ready=$(bash -c '</dev/tcp/127.0.0.1/21118' 2>/dev/null && echo yes || echo no)
  relay_ready=$(bash -c '</dev/tcp/127.0.0.1/21119' 2>/dev/null && echo yes || echo no)
  if [ "$ra_ready" = yes ] && [ "$relay_ready" = yes ]; then
    break
  fi
  sleep 1
done

ss -ltnp | grep -E ':(21118|21119)\b'

12.3 Клиент ZORA (клиент удаленной поддержки)

Remote Assistance состоит как из серверной части - RA Server и Relay, так и из клиента удалённой поддержки ZORA (Zodiac Remote Assistance), установленном на управляемом устройстве. Клиент ZORA является отдельным приложением и дополняет основного агента Zodiac.
Как правило, ручная установка клиента не выполняется - клиент распространяется автоматически, через директиву Zodiac, что позволяет быстро проверить установку на группе тестовых АРМ, и затем назначить её нужным группам устройств.

Клиент ZORA поставляется в дистрибутиве Zodiac в файле с расширением .zorad:

Загрузка и публикация установщика

1. В интерфейсе Zodiac откройте меню Удалённая поддержка.
   
2. Перейдите в раздел Загрузка и нажмите Загрузить файл.
   
3. Выберите файл .zorad из дистрибутива Zodiac. Например:

Zodiac-260826-1.8.20-s1.8.21-a1.8.11.zip\Zodiac-260826\zora.1.8.315\zora-1.8.315.zorad

Номер версии и имя архива являются примером: используйте файл из своего дистрибутива. После загрузки, когда содержимое установщика отобразится в окне ниже, нажмите Загрузить -> Загрузить все.

4. Перейдите в раздел Версии и опубликуйте клиентов ZORA для нужных вам ОС.

Создание директивы

1. Откройте меню Директивы и создайте директиву.
2. В типе директивы выберите Клиент поддержки.
   
3. Во вкладке с основными параметрами, на закладке "Установка и удаление" настройте параметры и правила, в соответствии с которыми будет производиться установка и удаление клиента ZORA.
   

Один из параметров конфигурации Профили определяет режим работы установленного клиента. Для первичного тестирования можно использовать профиль generic.profile. В этом режиме клиент может принимать входящие подключения и инициировать исходящие.

Профили бывают следующих типов:

4. Во вкладке Конфигурация настройте параметры конфигурации клиента удаленной поддержки, включая адрес Remote Assistance Server. C описанием параметров конфигурации клиента ZORA можно ознакомиться в соответствующей статье.
   
   
5. Сохраните директиву.
6. Через Ассоциации назначьте эту директиву на нужные группы компьютеров. Для установки клиента на все устройства используйте Глобальную связку, если это соответствует политике развертывания.

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

После выполнения директивы проверьте, что клиент ZORA появился на целевом устройстве и установил связь с сервером Remote Assistance. После этого, из раздела Все компьютеры можно открыть контекстное меню устройства и подключиться к нему. Через то же меню доступен функционал передачи файлов и другие возможности ZORA.

13. Агент Zodiac

13.1 Установка и настройка через переменную окружения

Ниже приведён ручной способ установки агента на один или несколько АРМ. Рекомендуется использовать его для проверки доступности Communication Server со стороны пользовательских подсетей, подтверждения успешного развертывания системы и обмена агента с сервером.

Для массовой установки агентов на машины под управлением Linux используйте утилиту zopush. Для Windows применяется zoexec. Также могут использоваться другие средства централизованного развертывания, например групповые политики.
Подробное описание вариантов распространения агентов приведено в инструкции Распространение агентов.

Для DEB-пакетов агента параметры установки передаются через переменные окружения. Для Windows-установки это делается аналогично через передачу параметров в инсталлятор msi. Часто, это предпочтительнее ручного заполнения служебных секций.
Установите агента с параметрами сервера через переменную окружения. Пакет автоматически создаст служебные файлы и сформирует конфигурацию агента.

env ZDC_SET_SERVER_URL=https://zodiac-comm.test:3001 \
  sudo -E apt install ./zodiac.agent.linux.x64.1.8.x.deb

После установки проверьте внешний файл конфигурации
/var/zodiac/agent/agent.ini. Он должен содержать минимум:

[Server]
url=https://zodiac-comm.test:3001
interval=600

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

sudo systemctl enable --now zodiac-agent.service
sudo systemctl restart zodiac-agent.service
systemctl is-active zodiac-agent.service

Проверка успешного обмена:

sudo tail -100 /var/zodiac/agent/log/agent.log

Ожидаемые записи:

Communicator.communicate: succeeded
Agent.main: started

Старые записи в /var/zodiac/agent/agent.critical.log не являются текущей ошибкой, если после последнего перезапуска появились успешные строки в agent.log.

14. Приемочная проверка

systemctl is-active postgresql keycloak \
  zodiac.administration.server.service \
  zodiac.communication.server.service \
  zodiac-agent.service \
  zodiac.remoteassistance.server.service \
  zodiac.remoteassistance.relay.service

for i in $(seq 1 30); do
  ready=true
  for port in 3000 3001 8443 21118 21119; do
    if ! bash -c "</dev/tcp/127.0.0.1/$port" 2>/dev/null; then
      ready=false
      break
    fi
  done
  if [ "$ready" = true ]; then
    break
  fi
  sleep 1
done

ss -ltnp | grep -E ':(3000|3001|8443|21118|21119)\b'

curl -kI https://keycloak.test:8443/realms/master/.well-known/openid-configuration
curl -kI https://zodiac-admin.test:3000/
curl -kI https://zodiac-comm.test:3001/

Ожидается:

• все перечисленные units имеют состояние active;
• Keycloak OIDC discovery отвечает HTTP 200;
• Administration Server отвечает HTTP 200 на корневой странице;
• Communication Server может отвечать HTTP 404 на корневом URL API;
• порты 3000, 3001, 8443, 21118, 21119 слушаются;
• Агент в agent.log содержит Communicator.communicate: succeeded.

15. Проверка токена и ролей

После входа пользователя Zodiac в Chrome откройте DevTools (F12) → Network и найдите запрос к API Zodiac с заголовком:

Authorization: Bearer <token>

Декодируйте payload локально. Токен должен содержать:

{
  "aud": ["zodiac", "account"],
  "preferred_username": "zodiac-admin",
  "resource_access": {
    "zodiac": {
      "roles": ["zodiac_ac_sa"]
    }
  }
}

Для полной проверки каталога ролей можно назначить также zodiac_ac_ra, но для супер-администратора достаточно zodiac_ac_sa.

В administration.ini, RA Server и Relay выражения должны соответствовать фактическому пути ролей:

SaExprs="$.resource_access.zodiac.roles[?(@ == 'zodiac_ac_sa')];$.roles[?(@ == 'zodiac_ac_sa')]"
RaExprs="$.resource_access.zodiac.roles[?(@ == 'zodiac_ac_ra')];$.roles[?(@ == 'zodiac_ac_ra')]"

После изменения ролей или конфигурации полностью выйдите из Zodiac и войдите снова: старый access token не изменяется.

16. Типовые ошибки

17. Резервное копирование и обновление

Перед обновлением сохраните:

• базу zodiac;
• /var/zodiac/updates;
• /var/zodiac/updates_temp;
• /var/zodiac/scatter-packages;
• /var/zodiac/uploads;
• все внешние INI в /var/zodiac;

При обновлении Zodiac:

1. Проверьте совместимость версий.
2. Сделайте резервную копию базы и каталогов.
3. Остановите Zodiac-службы.
4. Для миграции выполните create-or-migrate-db.sql от имени владельца объектов БД.
5. Установите новые .deb.
6. Проверьте внешние INI и CertificateTool thumbprint.
7. Запустите службы.
8. Проверьте OIDC, UI, Агента и RA.

Удаление пакета само по себе не является откатом: для возврата нужна совместимая резервная копия базы, конфигурации и служебных каталогов.