Настройки SME-RE

SME-RE принимает запросы по двум маршрутам:

Маршрут	Кто вызывает	Аутентификация
/sme_remote_exec/*	Команда script в поиске, тип script планировщика задач	Basic: sme.core.remote_script.user и пароль из keystore
/sme_scripts/v1/*	Активные действия на скриптах из каталога (плагин sm-actions-api)	Bearer-токен из хранилища токенов SME-RE

Настройки первого маршрута описаны в разделах Общие настройки подключения к SME-RE, Информация для запуска скрипта в поиске и Информация для запуска скрипта в планировщике задач. Настройки второго — в разделе Запуск активных действий через маршрут /sme_scripts/v1.

Проверка настройки SME-RE

Проверка наличия утилиты SME-RE

Утилита SME-RE автоматически устанавливается при каждом развертывании или обновлении системы. Она присутствует на всех узлах OpenSearch, для которых в файле opensearch.yml установлено значение node.attr.node_with_sme: true.

Обратите внимание!

Убедитесь, что конфигурационный файл /app/opensearch/utils/sme-re/application.properties существует и содержит корректные настройки. Если файл отсутствует, утилита SME-RE не сможет подключиться к OpenSearch. Также проверьте, что в opensearch.yml параметру node.attr.node_with_sme присвоено значение true. Если установлено значение false, на этот узел не будут отправляться задания на выполнение скриптов из поиска.

Проверка конфигурации

Проверьте текущие настройки, выполнив команду в консоли разработчика (Навигационное меню - Параметры системы - Консоль разработчика):

GET _cluster/settings

В ответе найдите следующий блок:

...
    "sme": {
        "core": {
            "remote_script": {
                "base_path": "/app/opensearch/utils/scripts/",
                "enable_ssl": "true",
                "port": "18080",
                "base_interpreter_name": "bash",
                "url": "https://127.0.0.1",
                "interpreters": [
                    "python3::/app/opensearch/utils/python/bin/python3",
                    "bash::bash"
                ]
            },
            "enable_field_caps": "false",
            "enable_limits": "true"
        },
        "overwrite": {
            "scroll_timeout": "30000"
        }
    },
...

Если раздел sme.core отсутствует, добавьте его и при необходимости скорректируйте значения параметров.

В консоли разработчика выполните команду:

PUT _cluster/settings
{
  "persistent": {
    "sme": {
      "core": {
        "remote_script": {
          "base_path": "/app/opensearch/utils/scripts/",
          "enable_ssl": true,
          "port": "18080",
          "base_interpreter_name": "bash",
          "url": "https://127.0.0.1",
          "interpreters": [
            "python3::/app/opensearch/utils/python/bin/python3",
            "bash::bash"
          ]
        }
      }
    }
  }
}

Обратите внимание!

Скрипт из команды script в поиске выполняется на случайном узле OpenSearch, для которого установлено значение node.attr.node_with_sme: true. Поэтому такие скрипты должны быть размещены на всех узлах с этим параметром.

К активным действиям это не относится: плагин сам передает код скрипта на SME-RE, поэтому размещать его на узлах не нужно.

Чтобы проверить список узлов и их параметры, выполните команду в консоли разработчика (Навигационное меню - Параметры системы - Консоль разработчика):

GET _cat/nodeattrs

В выдаче команды найдите параметр node_with_sme.

Параметры запуска SME-RE

Параметры запуска SME-RE указываются в конфигурационном файле application.properties, который находится в одной директории с утилитой SME-RE.

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

Параметр	Описание	Значение по умолчанию
server.port	Порт, на котором SME-RE будет принимать входящие соединения	18080
spring.servlet.multipart.max-request-size	Максимальный размер файлов для загрузки в байтах	100000000
server.tomcat.max-http-form-post-size	Максимальный размер для запросов multipart/form-data в байтах	104857600
sme.FileRotatePeriod	Время ротации файлов с данными запроса в секундах	10000
sme.baseData	Директория хранения файлов с данными запроса	./data
sme.directoryPollerInterval	Интервал проверки директории хранения файлов с данными запроса в секундах	50
sme.scriptConfigPath	Путь до конфигурационного файла scripts.yaml	./scripts.yaml
sme.LogStringSize	Размер строки логов	300
sme.RapidDelete	Удалять ли файлы с данными запросов	True
sme.redis.url	Адрес для подключения к Redis	"127.0.0.1"
sme.redis.port	Порт для подключения к Redis	6379
sme.redis.pass	Пароль для подключения к Redis	""
logging.file.path	Путь для хранения логов	logs
server.ssl.enabled	При ожидании входящих подключений использовать SSL/TLS	true
server.ssl.certificate	Путь до открытого ключа (сертификата) текущего сервера SME-RE в формате PKCS8	/app/opensearch/config/node-cert.pem
server.ssl.certificate-private-key	Путь до закрытого ключа текущего сервера SME-RE в формате PKCS8	/app/opensearch/config/node-key.pem
server.ssl.trust-certificate	Путь до цепочки удостоверяющих центров (CA) в формате PKCS8	/app/opensearch/config/ca-cert.pem
server.ssl.client-auth	Режим валидации сертификатов, может быть need, none, want	need

Параметры маршрута активных действий /sme_scripts/v1

Параметры читаются при старте SME-RE. Исключение — хранилище токенов, которое перечитывается без перезапуска.

Параметр	Описание	Значение по умолчанию
sme.scripts.interpreters	Разрешенные пути интерпретаторов через запятую. Запуск с путем, которого нет в списке, отклоняется. Пустой список запрещает все запуски	(пусто)
sme.scripts.loadersDir	Каталог, куда при старте раскладываются загрузчик скриптов и пакет sm_actions	./loaders
sme.scripts.cacheDir	Каталог кэша кода скриптов	./scripts-cache
sme.scripts.cacheMaxBytes	Объем кэша кода. При переполнении удаляются файлы, которые дольше всего не использовались	1GB
sme.scripts.workRoot	Корень рабочих каталогов вызовов	./runs
sme.scripts.maxProcesses	Общее число одновременно работающих процессов скриптов	16
sme.scripts.maxPerScript	Число одновременно работающих процессов одного скрипта	4
sme.scripts.queueSize	Сколько вызовов могут ждать свободного места. Сверх этого — 429 busy. Свободное место занимается без очереди, поэтому 0 означает «без очереди», а не «отказ всем»	32
sme.scripts.queueWaitMs	Сколько миллисекунд вызов ждет места в очереди	2000
sme.scripts.maxSourceBytes	Предел размера кода скрипта при загрузке. Сверх него — 413 source.too_large	20MB
sme.scripts.maxOutputBytes	Предел размера результата скрипта	10MB
sme.scripts.logTailBytes	Размер хвоста stdout и stderr скрипта, который возвращается в ответе и попадает в диагностику запуска	64KB
sme.scripts.interruptGrace	За сколько до истечения срока вызова скрипту посылается SIGTERM, чтобы run() получил DeadlineExceeded и освободил ресурсы. Не больше 10 % срока	1s
sme.scripts.pool.enabled	Сохранять запущенные процессы скриптов между вызовами. Если параметр выключен, каждый вызов запускает новый процесс	false
sme.scripts.pool.idleTtl	Как долго простаивающий процесс остается запущенным до остановки	5m
sme.scripts.pool.maxCallsPerWorker	Сколько вызовов обслуживает один процесс до перезапуска	1000
sme.scripts.pool.setupBackoff	Пауза перед повторной попыткой поднять процесс после сбоя setup()	30s
sme.scripts.pool.maxMessageBytes	Предел размера сообщения между SME-RE и запущенным процессом	64MB
sme.scripts.pool.teardownTimeout	Сколько ждать teardown() при остановке процесса	5s
sme.scripts.auth.keystorePath	Путь к PKCS12-хранилищу токенов вызовов. Если пусто, токенов нет и все вызовы получают 401	(пусто)
sme.scripts.auth.keystorePassword	Пароль хранилища токенов	Значение переменной окружения SME_RE_KEYSTORE_PASSWORD
sme.scripts.auth.reloadCheckInterval	Как часто проверяется время изменения файла хранилища. Измененный файл перечитывается без перезапуска; если файл не удается прочитать, используется прежний набор токенов	5s

Обратите внимание!

• путь в sme.scripts.interpreters должен вести к исполняемому файлу интерпретатора (подойдет bin/python3 виртуального окружения), а не к shim или обертке, которая запускает интерпретатор дочерним процессом. Иначе при прерывании вызова дочерние процессы скрипта продолжат работу. Для разных наборов библиотек используйте разные виртуальные окружения и пути
• группа процессов скрипта завершается командой kill. Она должна находиться в PATH процесса SME-RE (в минимальные образы ее добавляет пакет procps). Если команда kill отсутствует, при запуске в журнал записывается ошибка

Общие настройки подключения к SME-RE

Настройки ниже относятся к маршруту /sme_remote_exec (команда script в поиске и тип script планировщика задач). Активные действия на маршруте /sme_scripts/v1 используют из них только sme.core.remote_script.enable_ssl, а вместо пользователя и пароля — токен (см. раздел Запуск активных действий).

Настройка	Описание	Значение по умолчанию	Тип настройки
sme.core.remote_script.user	Имя пользователя, от которого выполняется запрос к SME-RE	sme_re_user	Кластерная настройка
sme.core.remote_script.password	Пароль пользователя, от которого выполняется запрос к SME-RE	—	Настройка keystore узла
sme.core.remote_script.enable_ssl	Флаг, указывающий, использовать ли SSL для подключения к SME-RE из команды script в поиске, из типа script планировщика задач и из активных действий	true	Кластерная настройка

Информация для запуска скрипта в поиске

Настройки подключения к SME-RE из команды script в поиске

В таблице приведены кластерные настройки подключения команды script к SME-RE:

Настройка	Описание	Значение по умолчанию
sme.core.remote_script.base_path	Путь к каталогу, куда будут загружаться скрипты	"/app/opensearch/utils/scripts/"
sme.core.remote_script.port	Порт, на котором запущен SME-RE	18080
sme.core.remote_script.url	Список URL-адресов узлов, на которых работает SME-RE	["https://127.0.0.1"]
sme.core.remote_script.base_interpreter_name	Название интерпретатора по умолчанию, чтобы использовать команду script без параметра intr	"bash"
sme.core.remote_script.interpreters	Массив строк с доступными интерпретаторами. Формат элемента: "название интерпретатора"::"путь к интерпретатору". Массив используется командой script; для активных действий см. раздел Интерпретаторы	["python3::/app/opensearch/utils/python/bin/python3","bash::bash"]

к сведению

Запросы равномерно распределяются между хостами с SME-RE с помощью алгоритма Round Robin.

Авторизация

Авторизация запросов к SME-RE на маршруте /sme_remote_exec всегда выполняется на том хосте, где запущен SME-RE.

Создание скрипта

Чтобы использовать скрипт в поиске, разместите его на всех серверах кластера в каталоге, указанном в настройке sme.core.remote_script.base_path. Убедитесь, что файл исполняемый и принадлежит пользователю и группе opensearch:opensearch.

Чтобы вернуть из скрипта данные для дальнейшей обработки в поиске, нужно вывести результат в формате JSON.

Пример для Python:

print(scriptResultJson)

Если перед командой script выполняются другие команды, их результат сохраняется во временный файл в папке, указанной в sme.baseData. Название этого файла будет передано в скрипт аргументом командной строки.

Пример для Python:

import sys

if __name__ == "__main__":
    # открыть файл с данными из запроса
    inputDataFile = open(sys.argv[1], "r")
    # прочитать файл с данными из запроса
    inputData = inputDataFile.read()
    # закрыть файл после прочтения
    inputDataFile.close()

Запуск активных действий через маршрут /sme_scripts/v1

Активные действия на скриптах из каталога ядра (_core/adhoc_scripts) выполняет SME-RE по запросу плагина sm-actions-api. Хост SME-RE выбирается из списка sme.core.remote_script.url, а код скрипта плагин передает самостоятельно.

Настройки подключения со стороны OpenSearch

Адреса SME-RE берутся из тех же кластерных настроек, что и для команды script. Их изменение подхватывается без перезапуска узлов.

Настройка	Описание	Значение по умолчанию	Тип настройки
sme.core.remote_script.url	Список URL-адресов узлов с SME-RE. Схема берется из записи; если она не указана — определяется по enable_ssl. Порт берется из записи; если он не указан — используется общий порт	["https://127.0.0.1"]	Кластерная настройка
sme.core.remote_script.port	Порт SME-RE для записей без порта	18080	Кластерная настройка
sme.core.remote_script.enable_ssl	Использовать ли SSL для записей без схемы	true	Кластерная настройка
sm.actions.script.sme_re.token	Токен вызовов скриптов. Без него запуски отклоняются, а в журнале узла при старте появляется предупреждение	—	Настройка keystore узла
sm.actions.script.deadline_margin	Запас между сроком вызова SME-RE и сроком выполнения действия, чтобы ответ успел дойти до плагина	2s	Настройка узла (opensearch.yml)

Токен вызовов скриптов

Вызовы на маршруте /sme_scripts/v1 принимаются с заголовком Authorization: Bearer <token>. SME-RE проверяет токен по своему хранилищу: файлу PKCS12, путь к которому задан в sme.scripts.auth.keystorePath. Принимается каждая секретная запись с алиасом, начинающимся на scripts-token, длиной не меньше 32 байт. Записей может быть несколько.

Порядок создания токена:

1. Сгенерируйте токен:

   openssl rand -base64 32

2. На каждом хосте SME-RE добавьте токен в хранилище (пароль хранилища задается переменной окружения SME_RE_KEYSTORE_PASSWORD):

   keytool -importpass -storetype PKCS12 -keystore <путь из sme.scripts.auth.keystorePath> -alias scripts-token-<метка>

   Перезапуск SME-RE не нужен: файл перечитывается в пределах sme.scripts.auth.reloadCheckInterval.

3. На каждом узле OpenSearch добавьте тот же токен в keystore. Через консоль разработчика (настройка применяется сразу):

   POST _core/keystore/sm.actions.script.sme_re.token
   {
     "value": "<токен>"
   }

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

   opensearch-keystore add sm.actions.script.sme_re.token

   POST _nodes/reload_secure_settings

Чтобы сменить токен без простоя, добавьте новую запись в хранилище каждого SME-RE, затем замените токен на узлах OpenSearch. Когда старый алиас перестанет встречаться в журнале SME-RE, удалите его:

keytool -delete -storetype PKCS12 -keystore <путь> -alias <старый алиас>

Интерпретаторы

Интерпретатор скрипта действия берется из справочника интерпретаторов ядра, а не из sme.core.remote_script.interpreters. Путь интерпретатора должен быть одинаковым на всех хостах SME-RE и входить в параметр sme.scripts.interpreters файла application.properties каждого из них, иначе SME-RE отклонит запуск.

Информация для запуска скрипта в планировщике задач (тип script)

Тип script планировщика задач запускает произвольную команду на хосте SME-RE по маршруту /sme_remote_exec/command. Для его работы на узлах должен быть установлен плагин sm-actions-api.

Настройки подключения к SME-RE из ScriptAction в планировщике задач

Получить настройки можно по следующему пути:

GET _core/settings/job-scheduler

В таблице приведены настройки подключения ScriptAction к SME-RE:

Настройка	Описание	Значение по умолчанию
sme-re_port	Порт, на котором запущен SME-RE	18080
sme-re_host	Список URL-адресов узлов, на которых работает SME-RE	["localhost"]

Пользователь и пароль берутся из кластерной настройки sme.core.remote_script.user и настройки keystore sme.core.remote_script.password.

Создание скрипта

В планировщике задач можно запустить любой скрипт.

Для передачи скрипту секретных данных можно использовать механизм переменных environment. Он позволяет сохранить секреты в keystore, чтобы SME-RE добавлял их в переменные окружения при запуске скрипта.

Порядок настройки переменных environment:

1. На всех серверах кластера сохраните в keystore значения переменных, которые нужно передать скрипту, под ключами вида jobscheduler.script.pass.<название переменной>.

2. В настройках Планировщика задач укажите, какие переменные из keystore доступны каждому заданию. Для этого выполните команду:

   PUT _core/settings/job-scheduler
   {
     "script_environments": """{
       "<идентификатор задачи>": ["<название переменной>"]
     }"""
   }

   Теперь Планировщик задач передаст SME-RE эти переменные для запуска скрипта.

3. Добавьте в скрипт чтение переменной из окружения.

   Пример для Python:

   import sys
   from os import getenv
   
   if __name__ == "__main__":
       # получить переменную из окружения
       try:
           envParamData = getenv("<название переменной>")
       except Exception as e:
           envParamData = e

Изменения в журналировании SME-RE

Начиная с версии 4.2.1 журнал SME-RE включает следующие изменения:

1. Добавлены следующие новые поля:
   • ID лога — уникальный идентификатор записи
   • ID потока — идентификатор потока, в котором создана запись
   • Код ошибки (только для записей об ошибках) — код, соответствующий конкретной проблеме в работе программы
   • Имя пользователя — пользователь, связанный с событием. Для вызовов по маршруту /sme_scripts/v1 указывается алиас токена
   • Глобальный тип — тип, который определяет принадлежность записи к определенной системе
2. Теперь каждая запись включает дату и время.

Формат логов до изменений:

13:40:11.957 INFO [main] c.s.s.r.JavaClass#info:1 - Custom message

Формат логов после изменений:

[2024-11-27 13:40:11,957][INFO ][c.s.s.r.r.JavaClass] [re][user_name][id][id_thread]  Custom message