Проба

Проба — это отдельное приложение, которое подключается к основному приложению Памир и выполняет «обогащение» на удалённых хостах

Технические требования

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

Поддерживаемые операционные системы

Дистрибутивы Linux с ядром не ниже версии 4.19 и системой инициализации systemd:

• Debian не ниже версии 10;
• Ubuntu не ниже версии 20.04;
• Astra Linux Special Edition не ниже версии 1.7.4;
• RED OS не ниже версии 8.

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

• Docker Engine не ниже версии 24.0 (или Podman не ниже версии 4.9.0 с активным сокетом).

примечание

Инсталлятор поддерживает миграцию каталога хранения данных Docker на другой диск/точку монтирования. Для выполнения миграции требуется пакет rsync в системе.

Установка pamirctl в PATH работает без привилегий суперпользователя — путь автоматически добавляется в окружение пользователя. Привилегии суперпользователя (sudo) требуются только для установки приложения от имени суперпользователя (не рекомендуется) и для миграции каталога хранения данных Docker.

Каталог приложения Пробы определяется следующим образом:

• /opt/pamir_probe — при установке от суперпользователя;
• $HOME/.pamir_probe — при установке от обычного пользователя (рекомендуется).

Podman

При использовании Podman необходимо отключить SELinux (или перевести его в режим permissive), иначе контейнеры не смогут нормально функционировать. Инсталлятор выдаст предупреждение при обнаружении активного SELinux.

Для автоматического запуска контейнеров после перезагрузки машины необходимо включить в автозагрузку сервисы podman.socket и podman-restart.service (подробно — в руководстве по установке сервера).

Содержимое дистрибутива

Образы контейнеров

В ходе установки будут загружены следующие образы контейнеров:

• RabbitMQ (брокер сообщений);
• Probe.

Порты сервисов

5672 — основной AMQP-порт, через который приложения подключаются к RabbitMQ для обмена сообщениями.

15672 — HTTP API и веб-интерфейс RabbitMQ Management Plugin (панель администрирования).

подсказка

Порты могут быть переопределены в файле конфигурации docker-compose.additional.yml.

Установка

Дистрибутив Пробы Памир реализован в виде образа формата ISO 9660.

Для установки Пробы Памир данный образ необходимо смонтировать любым доступным способом (через системные/сторонние приложения). В корне образа должны присутствовать 3 директории:

• probe/
• deps/
• install/

Исполняемый файл инсталлятора pamir-installer расположен в корне образа ISO. Конфигурационные файлы и ресурсы установки находятся в поддиректории install/. Инсталлятор автоматически определяет тип дистрибутива (сервер или проба) по наличию директории-маркера (probe/ для Пробы) и используемую систему контейнеризации (Docker или Podman).

Для установки необходимо вызвать ./pamir-installer install и следовать указаниям инсталлятора. Инсталлятор автоматически произведёт все необходимые проверки и загрузит требуемые образы контейнеров, после чего запустит сервисы Пробы.

Порядок установки

1. Монтирование образа ISO

sudo mount -o loop ./pamir-probe-1.0.0-astra1.7.iso /media/cdrom

2. Запуск установочного исполняемого файла

cd /media/cdrom
./pamir-installer install

Инсталлятор осуществляет проверку дистрибутива операционной системы, версию ОС, наличие Docker Engine (или Podman), а также при необходимости предложит мигрировать каталог с данными Docker Engine на другой диск.

В случае, если Проба Pamir уже установлена, инсталлятор определяет это автоматически и выполняет обновление: обновляет только изменившиеся образы контейнеров и перезапускает сервисы Пробы Pamir.

Команды инсталлятора

Инсталлятор принимает следующие команды:

• install — установка или обновление приложения. Инсталлятор автоматически определяет, выполняется ли первичная установка или обновление существующей инсталляции.
• uninstall — удаление приложения. Останавливает и удаляет контейнеры и сети. Образы контейнеров, тома с данными и директория приложения не удаляются.
• uninstall --purge — полное удаление приложения, включая тома с данными, образы контейнеров, сервис pamirctl.service и директорию приложения $HOME/.pamir_probe. Операция необратима.

Общие флаги инсталлятора:

• --log-level <LEVEL> — уровень детализации логов (DEBUG, INFO, WARN, ERROR). По умолчанию INFO.
• --noninteractive — отключает интерактивные запросы; использует значения из переменных окружения или действия по умолчанию.
• --no-color — отключает цветной вывод в терминале.

Флаги команды install:

• --force — принудительно перезагружает все образы контейнеров, даже если они не изменились.
• --skip-image-load — пропускает загрузку образов (полезно, если образы уже загружены).

подсказка

Инсталлятор поддерживает сжатые форматы образов контейнеров .tar.gz и .tar.zst, поэтому установка пакета zstd в системе больше не требуется.

Совместная установка сервера и пробы на одной машине

Сервер Памир и Пробу можно установить на один и тот же хост. Инсталлятор автоматически обнаруживает уже установленный сервер (по наличию его каталога /opt/pamir или $HOME/.pamir) и включает режим изоляции, чтобы сервер и Проба не конфликтовали. При этом базовые compose-файлы не модифицируются — контрольные суммы конфигураций остаются валидными.

Разные директории конфигурации

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

Приложение	Каталог (обычный пользователь)	Каталог (суперпользователь)
Сервер	$HOME/.pamir	/opt/pamir
Проба	$HOME/.pamir_probe	/opt/pamir_probe

Разделённые сети

Сервер и Проба работают в отдельных Docker Compose-проектах (pamir и probe соответственно), поэтому их контейнеры и сети не конфликтуют.

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

Приложение	Сеть	Подсеть
Сервер	pamir-net	172.19.0.0/16
Проба	pamir-probe-net	172.20.0.0/16

Переопределение сети выполняется через управляемый файл docker-compose.managed.yml в каталоге Пробы — базовые compose-файлы дистрибутива при этом не изменяются.

Разная конфигурация pamirctl

Обеими подсистемами управляет одна и та же утилита pamirctl, поведение которой задаётся файлом конфигурации .pamirctl.yml (параметры app_type и app_path). Утилита ищет конфигурацию последовательно в текущей рабочей директории ($CWD), затем в домашней директории пользователя ($HOME) и, наконец, в /etc/pamir. Если конфигурация не найдена, pamirctl управляет сервером.

При установке Пробы рядом с сервером её конфиг .pamirctl.yml кладётся не в $HOME (там уже находится конфиг сервера), а в каталог самой Пробы — $HOME/.pamir_probe/.pamirctl.yml. Если же Проба была установлена раньше сервера, её конфиг лежит в $HOME/.pamirctl.yml (или /etc/pamir/.pamirctl.yml при установке от суперпользователя) — при установке сервера инсталлятор автоматически переносит его в каталог Пробы. Параметр app_path в конфиге Пробы инсталлятор приводит к фактическому каталогу Пробы (например, /opt/pamir_probe при установке от суперпользователя). Поэтому:

• для управления сервером утилиту pamirctl можно вызывать из любого каталога (конфиг подхватывается из $HOME);
• для управления Пробой утилиту pamirctl необходимо вызывать из каталога Пробы $HOME/.pamir_probe — только тогда она подхватит конфиг Пробы через текущую рабочую директорию.

# Управление сервером — из любого каталога
pamirctl status

# Управление Пробой — из каталога Пробы
cd ~/.pamir_probe
pamirctl status

подсказка

В качестве альтернативы конфигурацию Пробы можно указать явно флагом --config:

pamirctl --config ~/.pamir_probe/.pamirctl.yml status

Пример файла конфигурации .pamirctl.yml для управления Пробой:

.pamirctl.yml

---
app_type: probe
app_path: /home/user/.pamir_probe

Контроль целостности при совместной установке

Контроль целостности (КЦ) выполняется только для сервера Памир. Под КЦ понимается проверка контрольных сумм образов и конфигурационных файлов перед командами start/restart, проверка командой sums --verify и демон постоянного контроля целостности (сервис pamirctl.service). Сервисы Пробы эталонными контрольными суммами не покрываются, и их целостность не проверяется.

Что установлено на хосте	pamirctl start / restart	Демон pamirctl.service
Только сервер	КЦ выполняется	Контролирует сервисы сервера
Сервер и Проба	С конфигурацией сервера — КЦ выполняется (кроме общих образов, см. ниже); с конфигурацией Пробы — КЦ не выполняется	Контролирует только сервисы сервера (кроме общих образов)
Только Проба	КЦ не выполняется	Не работает: сразу завершается без ошибки

При установке Пробы рядом с сервером Проба переиспользует утилиту pamirctl и демон сервера — они не заменяются и не перезапускаются, поэтому контроль целостности сервера не прерывается. Демон всегда контролирует именно сервер: даже если он обнаружит конфигурацию Пробы, сервер будет найден в его каталоге установки.

pamirctl определяет, что установлено на хосте, по каталогам приложений (см. Разные директории конфигурации): сервер — по наличию файла docker-compose.server.yml в каталоге сервера, Проба — по наличию файла docker-compose.probe.yml в каталоге Пробы. Проверяются оба варианта размещения (/opt/... и $HOME/...) независимо от того, от какого пользователя запущена утилита.

Общие образы сервера и Пробы

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

Чтобы после установки Пробы сервер можно было запустить, при совместной установке контроль целостности образов rabbitmq не выполняется — ни перед start/restart, ни демоном. Остальные образы сервера проверяются как обычно. Если Проба на хосте не установлена, образ rabbitmq проверяется наравне с остальными.

Демон определяет наличие Пробы при каждой проверке, поэтому установка Пробы рядом с уже работающим сервером не требует перезапуска демона. Если до установки Пробы демон успел заблокировать контейнер rabbitmq сервера, после установки Пробы блокировка снимается.

примечание

Исключение общих образов из контроля целостности — временная мера до перехода на раздельное тегирование образа rabbitmq для сервера и Пробы.

Управление Пробой утилитой сервера

pamirctl от сервера может управлять запуском и остановкой сервисов Пробы — для этого достаточно указать ему файл конфигурации .pamirctl.yml от Пробы: вызвать утилиту из каталога Пробы либо передать путь до конфига флагом --config.

# Управление сервисами Пробы из её каталога
cd ~/.pamir_probe
pamirctl status

# либо с явным указанием конфигурации Пробы
pamirctl --config ~/.pamir_probe/.pamirctl.yml status

При управлении Пробой контроль целостности не выполняется, даже если утилита pamirctl установлена сервером.

Управление сервисами Пробы Памир

Для управления сервисами Пробы Памир используется утилита командной строки (CLI) — pamirctl. Утилита автоматически устанавливается в PATH пользователя в ходе установки приложения; привилегии суперпользователя для этого не требуются. При необходимости утилиту можно вызвать напрямую по пути $HOME/.local/bin/pamirctl (/usr/local/bin/pamirctl — при установке от суперпользователя). Если Проба установлена рядом с сервером, используется утилита, установленная сервером.

Утилита принимает следующие команды:

• start — запуск сервисов Пробы.
• stop — остановка сервисов и удаление контейнеров. Тома хранения данных сохраняются.
• restart — последовательная остановка и запуск сервисов.
• status — просмотр текущего состояния сервисов.
• sums — вывод эталонных контрольных сумм образов и конфигураций. Проверка с флагом --verify для Пробы не выполняется: утилита сообщает «Контроль целостности не применяется к пробе ПАМИР».

примечание

Контроль целостности для Пробы не выполняется: команды start и restart не проверяют контрольные суммы образов и конфигурационных файлов, а демон контроля целостности на хосте, где установлена только Проба, не работает. Подробнее — в разделе Контроль целостности при совместной установке.

подсказка

Если Проба установлена рядом с сервером, вызывайте pamirctl из каталога Пробы $HOME/.pamir_probe (см. раздел Разная конфигурация pamirctl). Подробнее о контроле целостности сервера и режиме демона — в руководстве по установке сервера.

# pamirctl --help

Утилита управления подсистемами {vars.name} позволяет осуществлять 
развертывание, перезапуск, остановку и наблюдение за сервисами 
приложения, используя для этого средства Compose API.

Использование:
pamirctl [command]

Доступные команды:
completion  Generate the autocompletion script for the specified shell
help        Получить справочную информацию по выбранной команде
restart     Выполнить перезапуск сервисов {vars.name}
start       Выполнить запуск сервисов {vars.name}
status      Просмотр состояния сервисов {vars.name}
stop        Выполнить остановку сервисов {vars.name}
sums        Просмотр и проверка контрольных сумм

Флаги:
      --config string   файл конфигурации (по-умолчанию: $HOME/.pamirctl.yml)
  -h, --help            показать справочную информацию для pamirctl
  -v, --version         показать версию pamirctl

Используйте "pamirctl [command] --help" для получения дополнительной информации о команде.

Запуск приложения

Запуск Pamir осуществляется командой pamirctl start, после чего создаются и запускаются контейнеры. Большая часть контейнеров дополнительно проверяется на работоспособность и способность принимать трафик (healthcheck).

Параметризация сервисов

Данная команда также может использоваться для применения настроек, внесенных в конфигурацию сервисов (файлы docker-compose*.yml), например, если нужно опубликовать извне сервис rabbitMQ, вносятся изменения в файл docker-compose.additional.yml такого вида:

services:
  rabbitmq:
    ports:
      - "5672:6000"

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

pamirctl start rabbitmq

Остановка приложения

Остановка Pamir осуществляется командой pamirctl stop, которая останавливает работающие контейнеры и удаляет их. Тома хранения (volumes) и директория $HOME/.pamir_probe остаются нетронутыми (для дальнейшего запуска приложения).

Просмотр состояния сервисов

Просмотр статуса работы сервисов осуществляется командой pamirctl status.

Команда также может принимать дополнительные позиционные аргументы - имена сервисов, разделенные пробелом. В таком случае в таблице будут отображены указанные сервисы.

Перезапуск приложения (сервисов)

Перезапуск сервисов приложения осуществляется командой pamirctl restart.

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

Удаление

Для удаления Пробы Памир необходимо примонтировать ISO-образ дистрибутива и из корня образа выполнить команду ./pamir-installer uninstall.

Порядок удаления приложения без удаления данных

1. Монтирование образа ISO

sudo mount -o loop ./pamir-probe-1.0.0-astra1.7.iso /media/cdrom

2. Запуск установочного исполняемого файла

cd /media/cdrom
./pamir-installer uninstall

Деинсталлятор остановит работающие контейнеры, удалит их и сеть. Образы контейнеров, тома хранения данных (volumes) и директория $HOME/.pamir_probe не будут удалены.

Порядок удаления приложения с удалением данных

1. Монтирование образа ISO

sudo mount -o loop ./pamir-probe-1.0.0-astra1.7.iso /media/cdrom

2. Запуск установочного исполняемого файла с флагом --purge

cd /media/cdrom
./pamir-installer uninstall --purge

В данном случае тома хранения данных (volumes), образы контейнеров, сервис pamirctl.service и директория $HOME/.pamir_probe будут удалены безвозвратно.

примечание

Если Проба установлена рядом с сервером, при её удалении с флагом --purge сервис контроля целостности pamirctl.service и общий с сервером образ rabbitmq сохраняются — ими продолжает пользоваться сервер Памир.

Настройка пробы

Настройка Env переменных

Заполнить в .probe.env значимые переменные

• probe_name - уникальное идентифицирующее имя пробы
• workers - количество обработчиков
• данные для подключения к rabbitmq

подсказка

Для пользовательских конфигураций использовать .probe.override.env.

Подробно: Настройка Env переменных

Настройка RabbitMQ пробы

Данные для подключения веб-интерфейс RabbitMQ Management Plugin опередляются в .probe.env

Admin->Federation Upstream добавить новый upstream с параметрами rabbitmq к которому устанавливается подключение:

-Name: Pamir upstream

-upstreamURI: amqp://federation_user:federation_user@pamir:5672/vhost

Admin->Polices добавить политику подключения:

-Name: Probe police

-Pattern: probe_exchange - шаблон имени обмена, который будет связан с upstream rabbit

-Definition: federation-upstream-set=all

Настройка RabbitMQ основного сервера ПАМИР

Данные для подключения веб-интерфейс RabbitMQ Management Plugin опередляются в .env

Открыть порт для подключени веб-интерфейс RabbitMQ Management Plugin в docker-compose.additional.yml

Admin->Federation Upstream добавить новый upstream с параметрами rabbitmq к которому устанавливается подключение:

-Name: Probe upstream

-upstreamURI: amqp://federation_user:federation_user@probe:5672/vhost

Admin->Polices добавить политику подключения:

-Name: Pamir police

-Pattern: srm_exchange - шаблон имени обмена, который будет связан с upstream rabbit

-Definition: federation-upstream-set=all

Обогащение через пробу

Обогащение происходит через ТКЕ 'probe' (название может быть любое) связанную с обогащаемыми TКЕ через тип связи - Зависимость

Настройка ТКЕ

Настройка связи

• Тип связи - Зависимость

• Фетчер связи - Получить данные из атрибута: Название

Настройка КЕ

Создать КЕ 'probe' с идентифицирующим атрибутом Название которое соответвует настройке probe_name в файле .probe.env