Содержание

• Введение
• Минимальные требования
• Начало работы
• Свяжитесь с нами

Введение

Emissary — это P2P-ориентированный управляемый данными механизм рабочих процессов, который работает в гетерогенной, возможно широко распределённой, многоуровневой P2P-сети вычислительных ресурсов. Маршруты рабочих процессов не планируются заранее, как в обычных механизмах рабочих процессов, а обнаруживаются по мере получения дополнительной информации о данных. Обычно в рабочем процессе Emissary нет взаимодействия с пользователем; вместо этого данные обрабатываются целенаправленно, пока не достигнут состояния завершения.

Emissary является высококонфигурируемым, но в этой базовой реализации почти ничего не делает. Ожидается, что пользователи этого фреймворка предоставят классы, расширяющие emissary.place.ServiceProviderPlace, для выполнения работы над полезными нагрузками emissary.core.IBaseDataObject.

Можно выполнять различные действия, и рабочий процесс управляется по этапам, например STUDY, ID, COORDINATE, TRANSFORM, ANALYZE, IO, REVIEW.

Классами, отвечающими за управление рабочим процессом, являются emissary.core.MobileAgent и производные от него классы, которые управляют путём набора связанных объектов полезной нагрузки через рабочий процесс, и emissary.directory.DirectoryPlace, который управляет доступными сервисами, их стоимостью и качеством и поддерживает связь P2P-сети.

Сайт Maven и Javadoc, размещённые на GitHub Pages: https://code.nsa.gov/emissary/

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

• Операционная система Linux или MacOSX
• JDK 11
• Apache Maven 3.6.3+

Начало работы

Прочитайте руководство DEVELOPING.md для получения информации об установке необходимых компонентов, получении исходного кода, сборке и запуске Emissary.

Сборка

Выполните mvn clean package для компиляции, тестирования и упаковки Emissary

Запуск

В Emissary есть один bash-скрипт, который запускает всё. Он находится в верхнем уровне каталога Emissary. Скрипт запускает класс emissary.Emissary, который имеет несколько команд Picocli, доступных для обработки различных функций.

Без аргументов

Если скрипт emissary запущен без каких-либо аргументов, вы получите список всех подкоманд конфигурации и краткое описание.

Справка

Запуск ./emissary help даст вам тот же вывод, что и запуск без аргументов. Если вы хотите увидеть более подробную информацию о команде, добавьте имя команды после help. Например, чтобы увидеть все аргументы с описаниями для команды server, выполните:

Общие параметры

Остальные команды имеют аргументы (-b или --projectBase), которые можно задать, но они должны соответствовать PROJECT_BASE.

Каталог конфигурации по умолчанию — /config, но его также можно передать с помощью (-c или --config). При запуске из git-клона следует использовать target в качестве projectBase. Не стесняйтесь изменять файлы конфигурации в target/config перед запуском.

Журналирование обрабатывается logback. Вы можете указать пользовательский файл с помощью аргумента --logbackConfig.

См. help -c для каждой команды, чтобы получить дополнительную информацию.

Сервер (автономный)

Эта команда запустит сервер Emissary и инициализирует все настроенные места (places), место приёма (pickup place) и фильтры сдачи (drop off filters). Он запустится в автономном режиме, если -m или --mode не указан. По умолчанию количество MobileAgents рассчитывается на основе характеристик машины. На современных компьютерах это число может быть высоким. Вы можете управлять количеством агентов с помощью -a или --agents. Вот пример запуска.

Без дополнительной настройки он запустится на http://localhost:8001. Если вы перейдёте по этому адресу, вам потребуется ввести имя пользователя и пароль, определённые в target/config/jetty-users.properties, а именно emissary и emissary123.

Место приёма по умолчанию (PickUpPlace) настроено на чтение файлов из target/data/InputData. Если вы скопируете файлы в этот каталог, вы увидите, как Emissary обрабатывает их. Имейте в виду, что настроены только toUpper и toLower, поэтому вывод не будет слишком интересным.

Пауза

Остановить приём работы сервисом

Снятие паузы

Разрешить приостановленному сервису принимать работу

Инвалидация

Инвалидировать сервисы, которые поддерживают обновление. Это «лёгкое» обновление, подход без простоя, который инвалидирует ServiceProviderRefreshablePlace. Когда место затем извлекается из DirectoryPlace, место пересоздаётся с использованием тех же ключей для DirectoryPlace и Namespace, но конфигуратор перезагружается, и место может перезагрузить подмножество своих конфигураций.

Обновление

Принудительное обновление сервисов. Это «жёсткое» обновление: сервер ставится на паузу, и происходит ожидание, пока MobileAgents завершат работу. Когда сервер полностью простаивает, все существующие ключи ServiceProviderRefreshablePlace удаляются из DirectoryPlace и Namespace, и места полностью пересоздаются. Это позволяет вносить изменения в имена сервисов, прокси, списки запретов и т.д. Затем сервер снимается с паузы для возобновления обработки. Любой сбой при обновлении может привести сервер в нерабочее состояние, поэтому сервер завершает работу.

Остановка

Завершить работу сервиса

Принудительное завершение

Принудительное завершение работы сервиса

Агенты (автономный режим)

Команда agents показывает количество MobileAgents для настроенного хоста и то, чем эти агенты занимаются. По умолчанию порт — 9001, но вы можете использовать -p или --port для его изменения.
Предполагая, что вы работаете на порту 8001 из команды server выше, попробуйте:

Пул (автономный режим)

Pool — это свёрнутое представление агентов для узла. Он также по умолчанию использует порт 9001. Чтобы запустить его для автономного сервера, запущенного выше, выполните

Эта команда более полезна для кластера, так как она даёт более удобоваримое представление каждого узла.

Env

Команда Env требует запущенного сервера. Она запросит у сервера некоторые значения конфигурации, такие как PROJECT_BASE и BIN_DIR. Без аргументов она выведет неформатированный json-ответ.

Но вы также можете вывести ответ, пригодный для использования в bash.

При запуске сервера Emissary фактически вызывается эта конечная точка и выводится $PROJECT_BASE}/env.sh с настроенными переменными. Это сделано для того, чтобы shell-скрипты могли выполнить source $PROJECT_BASE}/env.sh и затем иметь эти переменные доступными без необходимости настраивать их где-либо ещё.

Config

Команда config позволяет увидеть эффективную конфигурацию для указанного места/сервиса/класса. Поскольку Emissary использует флейворы (flavors), эта команда покажет результирующую конфигурацию класса после применения всех флейворов. Эту команду можно использовать для подключения к работающему узлу Emissary, указав -h для хоста (по умолчанию localhost) и -p для порта (по умолчанию 8001). Для подключения к локально запущенному Emissary на порту 8001 подойдёт любая из следующих команд:

При желании вы можете указать автономный режим с помощью --offline, чтобы использовать файлы конфигурации, указанные в вашем локальном CONFIG_DIR:

В автономном режиме вы можете указать флейворы, чтобы увидеть различия в конфигурациях:

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

или в автономном режиме:

Сервер (кластер)

Emissary интересен в автономном режиме, но запуск в кластере более подходит для реальной работы. Способ запуска в кластере аналогичен автономному, но вам нужно указать -m cluster, чтобы сообщить узлу о необходимости подключения к другим узлам. В кластерном режиме Emissary также запустит PickUpClient вместо PickUpPlace, поэтому вам потребуется запустить фидер (feeder).

Посмотрите на target/config/peers.cfg, чтобы увидеть узлы рандеву. В данном случае их 3. Узлы, работающие на портах 8001 и 9001, — это просто узлы Emissary. Узел, работающий на порту 7001, — это фидер. Итак, давайте запустим 8001 и 9001 в двух разных терминалах.

Поскольку все эти узлы знают о портах 8001, 9001 и 7001, вы увидите ошибки в журналах, так как они продолжают пытаться подключиться.

Обратите внимание: в реальных развёртываниях мы не запускаем несколько процессов Emissary на одном узле. Вы можете настроить имя хоста с помощью -h.

Фидер (кластер)

С узлами, запущенными на портах 8001 и 9001, нам нужно запустить фидер. Команда feed по умолчанию использует порт 7001, но нам нужно создать каталог, из которого фидер будет читать. Файлы, помещённые в этот каталог, будут доступны для обработки рабочим узлам, и работа должна распределяться по кластеру. Запустите фидер с помощью

Вы должны иметь возможность открыть http://localhost:8001, http://localhost:9001 и http://localhost:7001 в браузере и посмотреть настроенные места. Поместите несколько файлов в ~/Desktop/feed1 и наблюдайте, как 2 узла обрабатывают их. Возможно, потребуется минута, чтобы они начали обработку.

Агенты (кластер)

Агенты в кластерном режиме снова показывают детали о mobileAgents. Они начинают с узла, который вы настраиваете (localhost:9001 по умолчанию), затем обращаются ко всем узлам, о которых знают, и получают ту же информацию. Запустите с помощью:

Пул (кластер)

Пул в кластерном режиме также делает то же самое, что и пул в автономном режиме. Он начинается с узла (localhost:9001) по умолчанию, затем переходит ко всем узлам, о которых знает, и агрегирует свёрнутое представление кластера. Запустите с помощью

Топология (кластер)

Команда topology обращается к настроенному узлу (localhost:8001 по умолчанию) и общается с каждым узлом, о котором знает. Ответ — это то, что знают все эти узлы, поэтому вы можете построить сетевую топологию вашего кластера. Запустите с помощью

Запуск сервера с SSL

Хранилище ключей и пароль хранилища ключей находятся в файле emissary.client.EmissaryClient-SSL.cfg. Включено и настроено по умолчанию примерное хранилище ключей, которое вы можете использовать для тестирования этой функциональности. Мы не рекомендуем использовать примерное хранилище ключей в производственных средах. Чтобы использовать собственное хранилище ключей, измените значения конфигурации в файле emissary.client.EmissaryClient-SSL.cfg.

Автономный режим

Кластерный режим

Свяжитесь с нами

Общие вопросы

Если у вас есть какие-либо вопросы или опасения по поводу этого проекта, вы можете связаться с нами по адресу: [email protected]

Вопросы безопасности

По вопросам безопасности и сообщению об уязвимостях, пожалуйста, обратитесь к SECURITY.md