Usm satellite

Описание

Внешний модуль usm_satellite является прокси-сервером для выполнения сетевых запросов к оборудованию в сетях, доступ к узлам которых невозможен непосредственно из USERSIDE или значительно затруднен. usm_satellite также решает проблему больших задержек для требовательных к времени запросов, например icmp-ping.

Внешний модуль usm_satellite взаимодействует с системой USERSIDE через протокол http (https). То есть, со стороны интерфейса USERSIDE он представляет собой WEB-API. USERSIDE обращается к модулю по протоколу http, передает ему команды и принимает результаты работы этих команд. Модуль usm_satellite, получив команду по http от системы USERSIDE выполняет ее, взаимодействуя с сетевым оборудованием по протоколам icmp, snmp, либо путем прямого обращения к оборудованию, либо выполняя консольные команды, такие как ping, arp, telnet.

Требования

• USERSIDE 3.13+
• PHP 7.0+
• PHP-extensions: mbstring, json, snmp

Ручная установка на сервер

В данном разделе описывается установка модуля на операционную систему сервера. Если вам больше подходит запуск модуля в виде Docker-контейнера, обратитесь к соответствующему разделу ниже.

Для работы модуля подойдет абсолютно любой сервер на любой операционной системе, на котором работает совместно WEB-сервер и PHP-интерпретатор. Это может быть связка Apache + PHP или Nginx + PHP-FPM или любой другой веб-сервер совместно с PHP. От сервера требуется только наличие WEB-сервера, интерпретатора РНР версии не ниже 7.0 и РНР-расширений: php-mbstring, php-snmp, php-json. Модуль может быть размещен как в отдельном виртуальном хосте, так и просто в подкаталоге уже существующего хоста (сайта), размещенного на этом сервере.

Скачайте архив с модулем usm_satellite из личного кабинета, скопируйте его на сервер и разархивируйте. В итоге Вы получите каталог с файлами. Этот каталог следует переместить в удобное для вас место на вашем веб-сервере.

Также настоятельно рекомендуем ограничить доступ к этому каталогу по http только с того IP-адреса, с которого к нему будет подключаться USERSIDE. Еще одним важным условием является настройка WEB-сервера таким образом, чтобы невозможно было просмотреть через http содержимое каталогов и файлов.

Если это первая установка, перейдите в каталог config и сделайте копию файла config-example.php с именем config.php. Теперь откройте любым удобным редактором файл config.php, придумайте (а лучше сгенерируйте) длинный сложный ключ доступа для этого сателлита и впишите его в занчение переменной 'key' этого файла. Ключ должен быть минимум 8 символов, среди которых должны быть как буквы так и цифры. Лучше, если это будет сгенерированный случайным образом хэш длиной не менее 32 символов. Там же можно поменять путь к лог-файлам, если в этом есть необходимость.

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

echo "моя сложная парольная фраза" | sha256sum
echo "моя сложная парольная фраза" | sha1sum
pwgen -s 32 1

Проверка работоспособности

Теперь просто откройте в браузере URL, по которому доступен usm_satellite. Вы должны увидеть ошибку аутентификации, которая выглядит следующим образом:

{
  "code": 401,
  "name": "Unauthorized",
  "message": "Invalid authentication. Access keys do not match."
}

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

2021-10-15 15:10:08|1.1|ERROR  |401| SatelliteException[Unauthorized]: Invalid authentication. Access keys do not match.

Запуск с использованием Docker

Вместо установки и настройки WEB-сервера, PHP, расширений и всего остального, можно воспользоваться готовым Docker-образом.

Установка

Если вы еще не установили Docker, то это можно сделать следующим способом:

sudo curl -fsSL get.docker.com -o get-docker.sh && sh get-docker.sh

Следующие действия создают группу docker и добавляют в нее текущего пользователя системы (чтобы текущий пользователь имел полный доступ к Docker). Эти действия можно пропустить, если в этом нет необходимости, но тогда придется все команды запускать от имени суперпользователя (через sudo):

sudo groupadd docker
sudo gpasswd -a $USER docker
newgrp docker

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

sudo mkdir -p /var/log/usm_satellite && sudo chmod 777 /var/log/usm_satellite

Теперь запустите контейнер следующим образом (вместо ключ_доступа_здесь укажите ваш желаемый ключ доступа к модулю):

docker run -d --name usm_satellite \
    --restart always \
    -e API_KEY=ключ_доступа_здесь \
    -p 8080:8080 \
    -v /var/log/usm_satellite:/app/log \
    -v /etc/localtime:/etc/localtime:ro \
    -v /etc/timezone:/etc/timezone:ro \
    erpuserside/usm_satellite

В данной конфигурации будет использован порт 8080 на сервере для трансляции в контейнер. Если вам нужен другой порт, например, стандартный порт 80, то измените параметр следующим образом (порт 8080 справа должен оставаться таким же):

-p 80:8080 \

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

-p 203.0.113.12:80:8080 \

Если таких интерфейсов должно быть несколько — добавьте еще один параметр -p

-p 203.0.113.12:80:8080 \
-p 192.168.1.10:80:8080 \

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

Вы можете использовать nginx в качестве ssl-фронтенда, если необходимо обеспечить доступ по https.

Контейнер будет автоматически запускаться при старте сервера, а также перезапускаться, если произойдет какой либо внутренний сбой в работе.

Обслуживание

Логи модуля пишутся в каталог, который подключен к контейнеру. В примере выше это каталог /var/log/usm_satellite. В нем создается файл журнала модуля с именем usm_satellite.log. Ротация логов осуществляется автоматически раз в неделю с сохранением последних 4-х файлов.

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

docker stop usm_satellite

А затем запустите его снова, добавив в параметры команды, указанной выше, еще одну переменную окружения:

-e LOG_SERENITY=debug \

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

Кроме лога модуля также существуют логи системных процессов контейнера (nginx, fpm, supervisor и т.д.) — они, как это требуется, выводятся в стандартный вывод контейнера (stdout + stderr). Так как вышеприведенная команда запускает контейнер в фоновом режиме, то эти логи можно просмотреть командой:

docker logs usm_satellite

Либо, если нужно наблюдать за логами, то:

docker logs usm_satellite -f

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

Обновление версии модуля

Для обновления выполните следующие команды:

docker stop usm_satellite
docker rm usm_satellite
docker pull erpuserside/usm_satellite

После чего запустите контейнер снова, как показано выше.

Удаление контейнера

Если вам понадобилось удалить контейнер и связанный с ним образ, то выполните:

docker stop usm_satellite
docker rm usm_satellite
docker rmi erpuserside/usm_satellite

Настройка в USERSIDE

См: Сателлиты