Zodiac.ITM: установка на РЕД ОС 8

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

Данная инструкция описывает AIO-развёртывание Zodiac.ITM на РЕД ОС 8.0.3 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 на ОС Windows):

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

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

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

Но более правильным решением является настрока DNS и внесение соответствующих записей. В рабочей сети используйте корпоративный DNS.

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

Требуется:

• минимум 4 CPU;
• минимум 8 Gb RAM для AIO-развёртывания;
• минимум 20 Gb свободного места для AIO-развёртывания, если планируется использование функционала OSD, объемных пакетов ПО, то рекомендуемый объем диска - от 100 Gb;
• доступ к репозиториям РЕД ОС 8;
• дистрибутив Zodiac.

4. Подготовка к установке

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

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

Проверьте права текущего пользователя:

whoami
sudo -v

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

4.2 Установка базовых пакетов

Обновите метаданные репозиториев и установите базовые утилиты, PostgreSQL, OpenJDK и Firewall (если отсутствуют):

sudo dnf makecache
sudo dnf install -y ca-certificates curl openssl tar unzip chrony postgresql-server java-17-openjdk-headless firewalld

Инициализация и запуск служб:

sudo postgresql-setup --initdb
sudo systemctl enable --now chronyd
sudo systemctl enable --now postgresql

Проверка готовности окружения:

cat /etc/os-release
uname -a
timedatectl status
systemctl is-active postgresql chronyd
rpm -q postgresql-server java-17-openjdk-headless

Команды должны вернуть данные дистрибутива, информацию о ядре и архитектуре, настройки времени; две строчки active, подтверждая, что база данных и служба времени работают, а также информацию по установленным пакетам.

В штатном репозитории версии РЕД ОС, на которой проводилась установка, предоставлялся PostgreSQL 16 версии. Зодиак.АйТиЭм не ограничен этой версией, а поддерживает широкую линейку, начиная с 12 версии.

4.3 Загрузка и проверка дистрибутива

До установки создайте рабочий каталог от имени текущего административного пользователя и скачайте архив дистрибутива в эту рабочую папку, распаковав его так, чтобы каталоги Zodiac-260826/dbscripts, Zodiac-260826/certtool, Zodiac-260826/zodiac.server.1.8.21 и Zodiac-260826/zodiac.agent.1.8.11 находились под "$HOME/zodiac-installer/zodiac". Далее в инструкции предполагается именно такая структура каталогов. (Но вы можете заменить путь на любой другой, учитывая это дальше при выполнении команд по инструкции).

Вышеописанные действия можно осуществить, например, таким блоком команд:

mkdir -p "$HOME/zodiac-installer/zodiac"
cd "$HOME/zodiac-installer/zodiac"

# Запрос полной HTTPS-ссылки на дистрибутив Zodiac.ITM
read -r -p 'HTTPS-ссылка на дистрибутив: ' DISTR_URL

curl --fail --location --retry 3 --connect-timeout 30 \
  --output zodiac-distribution.zip.part "$DISTR_URL" &&
mv zodiac-distribution.zip.part zodiac-distribution.zip

unset DISTR_URL

Пути системной конфигурации (/etc, /opt, /var, /tmp) в инструкции
указаны абсолютными и не зависят от текущего рабочего каталога.

После успешного скачивания проверьте ZIP-архив и распакуйте:

unzip -tq zodiac-distribution.zip &&
unzip zodiac-distribution.zip

Проверьте наличие каталогов:

ls -ld \
  Zodiac-260826/dbscripts \
  Zodiac-260826/certtool \
  Zodiac-260826/zodiac.server.1.8.21 \
  Zodiac-260826/zodiac.agent.1.8.11

5. Настройка Firewall в РЕД ОС 8

Сначала добавьте правило SSH в постоянную конфигурацию зоны public, чтобы сохранить доступ к серверу при включении Firewall. Затем запустите службу:

sudo firewall-offline-cmd --zone=public --add-service=ssh
sudo systemctl enable --now firewalld

Открытие необходимых портов для работы компонентов Zodiac и Keycloak:

sudo firewall-cmd --permanent --add-service=ssh
sudo firewall-cmd --permanent --add-port=8443/tcp
sudo firewall-cmd --permanent --add-port=3000/tcp
sudo firewall-cmd --permanent --add-port=3001/tcp
sudo firewall-cmd --permanent --add-port=21118/tcp
sudo firewall-cmd --permanent --add-port=21119/tcp
sudo firewall-cmd --reload

Проверьте итоговый список открытых портов:

sudo firewall-cmd --list-all

(В списке должны быть служба ssh и порты 3000/tcp, 3001/tcp, 8443/tcp, 21118/tcp, 21119/tcp. Порт базы данных 5432 не открывайте: в AIO-развёртывании он доступен только локально).

6. Создание базы данных

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

Role: zodiac
Database: zodiac
Password: zodiac

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

sudo -u postgres psql

Выполните в приглашении psql:

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

Перейдите в каталог dbscripts дистрибутива и создайте структуру таблиц с помощью выполнения SQL-скрипта create-or-migrate-db.sql от имени владельца базы:

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

Если команда выше возвращает Ident authentication failed, это может быть вызвано тем, что в РЕД ОС правило для локального TCP-подключения может использовать ident, который не проверяет пароль PostgreSQL. Это правило может мешать подключению Zodiac к 127.0.0.1.
В этом случае необходимо будет разрешить парольную аутентификацию, как описано в следующем разделе. Если ошибки не возникает, переходите сразу к проверке успешного создания таблиц.

Включение парольной аутентификации

Сохраните копию pg_hba.conf и откройте его для редактирования. Обычно путь /var/lib/pgsql/data/pg_hba.conf:

sudo cp -a /var/lib/pgsql/data/pg_hba.conf /var/lib/pgsql/data/pg_hba.conf.before-zodiac
sudo vi /var/lib/pgsql/data/pg_hba.conf

Перед общим правилом host all all 127.0.0.1/32 ident добавьте:

host    zodiac    zodiac    127.0.0.1/32    scram-sha-256

или можете сделать это командой:

sudo sed -i '/^host[[:space:]]\+all[[:space:]]\+all[[:space:]]\+127\.0\.0\.1\/32[[:space:]]\+ident$/s/ident/scram-sha-256/' /var/lib/pgsql/data/pg_hba.conf
sudo systemctl reload postgresql

PostgreSQL применяет первое подходящее правило. Это правило разрешает парольную аутентификацию только для роли и базы zodiac с адреса 127.0.0.1; остальные правила не меняются. AIO-установка не требует внешнего доступа к БД.

Перечитайте и проверьте правила:

sudo -u postgres psql -v ON_ERROR_STOP=1 -c 'SELECT pg_reload_conf();'
sudo -u postgres psql -c 'SELECT line_number, error FROM pg_hba_file_rules WHERE error IS NOT NULL;'

Последний запрос должен вернуть пустой результат. Затем повторите команду миграции из предыдущего подраздела.

Проверка успешного создания таблиц

Команда выведет список созданных таблиц:

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

Действия при ошибке аутентификации описаны выше (проверьте фактические правила в /var/lib/pgsql/data/pg_hba.conf).

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

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

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

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

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

Для тестового стенда создайте самоподписанный сертификат с SAN для всех имён и внутреннего IP сервера (перед выполнением команды замените 192.168.1.100, на адрес вашего сервера):

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 install -m 0644 /etc/zodiac/tls/zodiac.crt /etc/pki/ca-trust/source/anchors/zodiac-test.crt
sudo update-ca-trust extract

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

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

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

В этой инструкции используется тестовый самоподписанный сертификат. Скачайте его публичную копию из /etc/pki/ca-trust/source/anchors/zodiac-test.crt и импортируйте в доверенные корневые сертификаты на компьютере администратора, с браузера которого будет осуществляться управление Zodiac.ITM (для Windows используйте certmgr.msc). Для рабочей сети используйте сертификат корпоративного CA; закрытый ключ zodiac.key на клиентские машины не копируйте.

Для серверных компонентов Zodiac — Administration Server, Communication Server, Remote Assistance Server и Relay — сертификат и закрытый ключ дополнительно упаковываются в PFX и импортируются в хранилище через CertificateTool. В нашем AIO-развёртывании все четыре службы находятся на одном сервере и работают от имени root, поэтому достаточно выполнить импорт один раз. После импорта укажите Thumbprint, выведенный утилитой, в секциях [Certificate] конфигурационных файлов всех четырёх служб. Команды подготовки PFX и импорта приведены далее, на шаге установки серверных пакетов.

На клиентских машинах с установленным агентом установите тестовый сертификат в системное хранилище доверия.

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

РЕД ОС 8 поставляет OpenJDK 17. Проверьте установленную версию:

java -version

Скачайте и распакуйте официальный архив Keycloak 25.0.6:

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 --no-create-home --shell /sbin/nologin keycloak
sudo chown -R keycloak:keycloak /opt/keycloak-25.0.6
/opt/keycloak/bin/kc.sh --version

Создайте unit-файл службы Keycloak:

sudo tee /etc/systemd/system/keycloak.service > /dev/null <<'EOF'
[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=60

[Install]
WantedBy=multi-user.target
EOF

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

Проверьте запуск службы и доступность OIDC discovery endpoint:

systemctl is-active keycloak
for i in $(seq 1 60); do
  if curl --insecure --fail --silent --max-time 2 --output /dev/null https://keycloak.test:8443/realms/master/.well-known/openid-configuration; then
    break
  fi
  sleep 1
done
ss -ltnp | grep ':8443'
curl -kfsS -o /dev/null -w '%{http_code}\n' 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.

8.1 Клиент Zodiac

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

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

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

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

Login: admin
Password: zodiac

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

General settings:

Client type: OpenID Connect
Client ID: zodiac

Capability config:

Standard flow: On
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: *
он позволяет перенаправление и запросы с непредусмотренных адресов.

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

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

В списке типов выберите Audience, заполните поля:

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"]
  }
}

В Keycloak есть предпросмотр токена для выбранного пользователя. В карточке клиента zodiac откройте вкладку Client scopes, затем режим Evaluate, выберите пользователя zodiac-admin и нажмите Generated access token.

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

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

8.3 Опциональная оптимизация запуска (--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-развёртывания с редкими изменениями конфигурации этот шаг
необязателен; используйте его, если требуется минимизировать время старта на
медленном хосте.

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. Установка серверных RPM-пакетов

В предоставленном архиве использовалась версия Zodiac 1.8.21. Перед установкой рекомендуется проверить контрольные суммы пакетов Remote Assistance по манифесту архива, затем установите все четыре серверных RPM из каталога zodiac.server.1.8.21:

cd "$HOME/zodiac-installer/zodiac"
grep -E 'zodiac.remoteassistance.(server|relay).linux.x64.1.8.21.rpm$' SHA256SUMS | sha256sum -c -
cd "$HOME/zodiac-installer/zodiac/Zodiac-260826/zodiac.server.1.8.21"
sudo dnf install -y \
  ./zodiac.administration.server.linux.x64.1.8.21.rpm \
  ./zodiac.communication.server.rhel90.x64.1.8.21.avx.rpm \
  ./zodiac.remoteassistance.server.linux.x64.1.8.21.rpm \
  ./zodiac.remoteassistance.relay.linux.x64.1.8.21.rpm

RPM-пакеты создают и включают systemd-службы автоматически. До создания конфигурационных .ini-файлов службы могут завершаться с ошибкой; поэтому, после настройки конфигураций перезапустите их.
После установки серверных RPM импортируйте сертификат в хранилище Zodiac. Перейдите в корень распакованного дистрибутива:

cd "$HOME/zodiac-installer/zodiac/Zodiac-260826"
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
sudo /opt/zodiac/certtool/Zodiac.CertificateTool add /tmp/zodiac-server.pfx

При запросе введите пароль PFX zodiac. Сохраните выведенный Thumbprint и укажите его без двоеточий в секциях [Certificate] конфигурационных файлов (далее в процессе установки). CertificateTool add запускайте из интерактивного терминала.

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

sudo rm -f /tmp/zodiac-server.pfx

Создание конфигурации Administration Server (administration.ini)

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

/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"

Замените REPLACE_WITH_CERTIFICATE_THUMBPRINT на Thumbprint, выведенный CertificateTool, без двоеточий.

Создание конфигурации Communication Server (communication.ini)

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

/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"

Замените REPLACE_WITH_CERTIFICATE_THUMBPRINT на Thumbprint, выведенный CertificateTool, без двоеточий.

Далее перезапустите службы и проверьте их активность:

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

for i in $(seq 1 60); do
  admin_ready=$(curl --insecure --fail --silent --max-time 2 --output /dev/null https://zodiac-admin.test:3000/ && echo yes || echo no)
  comm_ready=$(curl --insecure --silent --max-time 2 --output /dev/null https://zodiac-comm.test:3001/ && 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 --insecure --fail --silent --show-error --max-time 10 --output /dev/null --write-out '%{http_code}\n' https://zodiac-admin.test:3000/
curl --insecure --silent --show-error --max-time 10 --output /dev/null --write-out '%{http_code}\n' 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 и журнал.

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

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

Перед запуском служб создайте конфигурационные .ini-файлы. Замените в них REPLACE_WITH_CERTIFICATE_THUMBPRINT на Thumbprint, выведенный CertificateTool, без двоеточий.

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

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 chmod 0600 /var/zodiac/remoteassistance-server/remoteassistance-server.ini /var/zodiac/remoteassistance-relay/remoteassistance-relay.ini
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'

Клиент 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.

12. Агент Zodiac

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

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

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

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

cd "$HOME/zodiac-installer/zodiac/Zodiac-260826/zodiac.agent.1.8.11"

env ZDC_SET_SERVER_URL=https://zodiac-comm.test:3001 \
  sudo -E dnf install -y ./zodiac.agent.linux.x64.1.8.11.rpm

После установки проверьте внешний файл конфигурации агента
/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.

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

Проверьте состояние установленных компонентов:

systemctl is-active postgresql chronyd firewalld 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 60); 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/
curl -kI https://zodiac-ra.test:21118/
curl -kI https://zodiac-relay.test:21119/
sudo grep -F 'Communicator.communicate: succeeded' \
  /var/zodiac/agent/log/agent.log | tail -n 1

Ожидается:

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

Успешное прохождение проверок означает, что Зодиак.АйТиЭм установлен и гоотв к использованию.

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

14.1 Проверка токена и ролей (в случае проблем c ролями и ошибками сразу после аутентификации)

После входа пользователя 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 не изменяется.

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

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

• базу zodiac;
• /var/zodiac/updates;
• /var/zodiac/updates_temp;
• /var/zodiac/scatter-packages;
• /var/zodiac/uploads;
• все внешние INI в /var/zodiac;
• /etc/systemd/system/keycloak.service;
• /etc/zodiac/tls;
• /opt/keycloak/conf и каталог H2 data/h2 для AIO-развёртывания.

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

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

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