Быстрый старт

Контакты технических специалистов

При возникновении вопросов по развёртыванию, настройке или эксплуатации ПО вы можете обратиться к специалистам службы сопровождения Solar TI Feeds по электронной почте support.tic@rt-solar.ru.

Назначение и область применения

Агент Solar TI Feeds представляет собой программное обеспечение для интеграции с облаком TI Feeds, предназначенное для автоматизации получения различных фидов и их доставки конечному потребителю в различных форматах. Решение представлено в виде Docker-образа, что обеспечивает простоту развертывания и масштабируемость. Агент самостоятельно выполняет запросы к серверу, аутентифицируется и выгружает необходимые данные.

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

Перед началом установки убедитесь, что выполнены следующие требования:

1. Программное обеспечение

• Операционная система: Unix-подобная ОС (Linux или macOS)
• Контейнеризация:
  • Docker версии 22 или выше
  • Docker Compose версии 2
• Архив с агентом: Скачайте установочный пакет

2. Аппаратные требования (при развертывании на виртуальной машине)

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

• Процессор: 2-4 vCPU
• Оперативная память: 8 ГБ vRAM
• Диск: 50 ГБ HDD

Распаковка архива

1. Откройте терминал и перейдите в директорию, где находится архив
2. Создайте директорию для агента, выполнив команду: mkdir -p agent
3. Распакуйте архив, выполнив команду: tar -xvf v2.6.5.tar.gz -C agent
4. Перейдите в распакованную директорию: cd agent

Описание установочных файлов

Установочный комплект включает в себя Docker-образ контейнера и конфигурационные файлы, с помощью которых можно настраивать агента без внесения изменений в программный код:

• Docker-образ агента в файле 4rays_tic_agent.tar
• Файл docker-compose.yml с предопределёнными переменными окружения
• Краткая инструкция по запуску агента ReadMe.txt
• Файлы конфигурации агента в поддиректории pkl:
  • agent.pkl – базовый файл конфигурации с описанием всех структур и возможных значений параметров
  • {PIPELINE_NAME}.pkl – конфигурационные файлы в директории configs, которые описывают логику работы и параметры запуска агента
  • templates.pkl – файл с шаблонами конфигурации

Инсталляция установочных файлов

Необходимо сохранить в одной папке полученные файлы:

• 4rays_tic_agent.tar
• docker-compose.yml
• pkl/agent.pkl
• pkl/configs/{PIPELINE_NAME}.pkl
• pkl/templates.pkl

Для загрузки Docker-образа контейнера агента необходимо ввести команду:
$ docker load -i “4rays_tic_agent.tar”

Для проверки того, что контейнер успешно загружен введите команду:
$ docker image list

Если в консоли появилась информация о контейнере 4rays/tic/agent соответствующей версии, значит контейнер с агентом успешно загружен.

Конфигурация агента

Для работы с конфигурацией агента необходимо создать новый или взять готовый файл конфигурации {PIPELINE_NAME}.pkl из директории pkl/configs/, указав корректные параметры для его запуска, в том числе пути к рабочим файлам с учетом точки монтирования в файле docker-compose.yml (по умолчанию ./work).

Для этого нужно заполнить все значения переменных окружения, которые объявлены в docker-compose.yml файле или напрямую в самом конфигурационном файле, где переменные окружения объявляются как read("env:{ENV_NAME}").

Обычно параметры конфигурации для готовых конфигурационных файлов заранее заданы в блоке environment в docker-compose.yml файле. При необходимости модифицировать или добавить дополнительные параметры можно изменить сам пайплайн в файле {PIPELINE_NAME}.pkl.

В общем случае необходимо задать значения для следующих переменных окружения:
Основные переменные для подключения к Solar TI Feeds

• TIC_AGENT_API_SERVER=api.data.rt-solar.ru - Адрес сервера Solar TI Feeds
• TIC_AGENT_API_TOKEN - JWT-токен для аутентификации на сервере Solar TI Feeds
• TIC_AGENT_NOTIFICATION_SERVER=notifications.data.rt-solar.ru - Адрес сервера уведомлений

Настройки локального хранилища и путей (опционально)

• TIC_AGENT_SQLITE_DB_FILE=/data/agent/states.sqlite - Полный путь к файлу базы данных SQLite для хранения состояния работы агента
• TIC_AGENT_OUTPUT_DIR=/data/agent/data - Директория для сохранения результирующих файлов (CSV, TXT)
• TIC_AGENT_LOG_DIR=/data/agent/ - Директория для хранения лог-файлов работы агента

По умолчанию путь /data/agent/ монтируется в локальную папку ./work.
Остальные переменные нужно заполнять при необходимости в зависимости от способа использования агента и его конфигурации.

Также в стандартных конфигурациях обычно в начало файла вынесен список фидов – feedsList, который необходимо заполнить в соответствии с полученными доступами для вашего токена.

Если доступ во внешнюю сеть организован через прокси-сервер, то необходимо указать в docker-compose.yml файле дополнительные переменные окружения:

• HTTP_PROXY=http://proxy.example.com:8080
• http_proxy=http://proxy.example.com:8080
• HTTPS_PROXY=http://proxy.example.com:8080
• https_proxy=http://proxy.example.com:8080

При проблемах с доступом можно также указать данные параметры напрямую в файле /etc/systemd/system/docker.service.d/http-proxy.

Запуск и проверка функционирования

Для запуска агента необходимо перейти в директорию, в которой был распакован установочный комплект и ввести в консоли команду для запуска агента:
$ docker-compose up

Для запуска агента в фоновом режиме (как службы) необходимо ввести команду:
$ docker-compose up -d

После запуска контейнера в обычном режиме в консоль будет выводиться служебная информация о работе агента. При запуске в режиме службы для просмотра аналогичной информации необходимо воспользоваться командой:
$ docker logs {CONTAINER_NAME}

Чтобы посмотреть результаты работы агента, перейдите в поддиректорию ./work, находящуюся в директории, из которой был запущен агент. Там размещаются файлы, содержащие результаты работы агента. Если в конфигурационном файле установлены соответствующие значения, то в этой же директории могут быть созданы файл с логами работы агента и файл базы данных SQLite, хранящий в себе состояние работы агента.

Для остановки агента нажмите сочетание клавиш Ctrl+C.

Перезапуск агента

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

Внимание!

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

Шаги для полного перезапуска агента:

1. Остановите работающий агент:

• Если агент запущен в интерактивном режиме (через docker-compose up), нажмите сочетание клавиш Ctrl+C
• Если агент запущен в режиме службы (через docker-compose up -d), выполните в директории с агентом команду: $ docker-compose down

2. Удалите файл базы данных состояния агента. Файл состояния по умолчанию находится в рабочей директории ./work и имеет имя states.sqlite. Полный путь к файлу задается переменной окружения TIC_AGENT_SQLITE_DB_FILE в docker-compose.yml. Выполните команду: $ rm ./work/states.sqlite Если в конфигурации указан другой путь к файлу состояния, удалите файл по этому пути
3. Запустите агент заново, выполнив команду запуска в нужном режиме:

• В интерактивном режиме: $ docker-compose up
• В режиме службы: $ docker-compose up -d

После выполнения этих шагов агент будет запущен с чистым состоянием и начнет процесс выгрузки данных сначала.

Результаты работы агента

В этом разделе приведены примеры результатов работы агента, зависящие от его конфигурации. Также для некоторых форматов может быть настроена дополнительная отправка индикаторов в СЗИ.

Актуальный перечень возможных СЗИ можно уточнить у специалистов по сопровождению TI Feeds по электронной почте support.tic@rt-solar.ru.

Сохранение результатов в формате CSV

Данные могут быть загружены в формате CSV с расширенными возможностями настройки:

• Настройка разделителей (сепараторов) между полями (запятая, точка с запятой, табуляция и др.)
• Настройка символов экранирования для специальных символов и текстовых данных
• Настройка заголовков столбцов (возможность переименования, добавления или удаления)
• Гибкая настройка содержания столбцов с выбором необходимых полей данных

Рисунок 1 – Пример CSV-файла

Рисунок 2 – Пример CSV-файла с настроенными столбцами

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

• Перезапись старого файла
• Запись в конец существующего файла
• Запись в новый файл с временной меткой

Рисунок 3 – Примеры файлов в различных режимах записи

Сохранение результатов в виде списка в TXT-файле

Агент позволяет настроить получение данных таким образом, что будет выгружаться только значение индикатора без дополнительной информации для удобного формирование списков (Рисунок 4).

Рисунок 4 – Примеры TXT-файлов, содержащие только значения индикатора

Запись результатов в Kafka

Агент предоставляет возможность записи фидов отдельными сообщениями в Apache Kafka с возможностью выбрать топик, ключ и настроить формат сообщения.

Рисунок 5 – Пример записи фида в виде сообщения в формате Apache Kafka