Usm satellite: различия между версиями

Материал из WiKi - UserSide
(Новая страница: «== Описание == Внешний модуль '''usm_satellite''' является прокси-сервером для выполнения сетевых…»)
 
(не показано 15 промежуточных версий 2 участников)
Строка 1: Строка 1:
== Описание ==
== Описание ==


Строка 5: Строка 6:
Внешний модуль '''usm_satellite''' взаимодействует с системой USERSIDE через протокол http (https). То есть, со стороны интерфейса USERSIDE он представляет собой WEB-API. USERSIDE обращается к модулю по протоколу http, передает ему команды и принимает результаты работы этих команд. Модуль '''usm_satellite''', получив команду по http от системы USERSIDE выполняет ее, взаимодействуя с сетевым оборудованием по протоколам icmp, snmp, либо путем прямого обращения к оборудованию, либо выполняя консольные команды, такие как ping, arp, telnet.
Внешний модуль '''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-сервера, интерпретатора РНР версии не ниже 5.5 и РНР-расширений: php-snmp, php-json, php-zip. Модуль может быть размещен как в отдельном виртуальном хосте, так и просто в подкаталоге уже существующего хоста (сайта), размещенного на этом сервере.
Для работы модуля подойдет абсолютно любой сервер на любой операционной системе, на котором работает совместно WEB-сервер и PHP-интерпретатор. Это может быть связка Apache + PHP или Nginx + PHP-FPM или любой другой веб-сервер совместно с PHP. От сервера требуется только наличие WEB-сервера, интерпретатора РНР версии не ниже 7.0 и РНР-расширений: php-mbstring, php-snmp, php-json. Модуль может быть размещен как в отдельном виртуальном хосте, так и просто в подкаталоге уже существующего хоста (сайта), размещенного на этом сервере.


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


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


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


== Проверка работоспособности ==
Для генерирования ключа доступа подойдет любой из следующих способов, или какой либо еще, какой вам больше нравится. Не забудьте поменять парольную фразу в приведенных ниже командах:
echo "моя сложная парольная фраза" | sha256sum
echo "моя сложная парольная фраза" | sha1sum
pwgen -s 32 1
 
=== Проверка работоспособности ===


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


  2019-04-07 09:13:28 <1.0.0> [401] - Unauthorized > Invalid authentication. Access keys do not match.
  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
 
Теперь запустите контейнер следующим образом (вместо <code>ключ_доступа_здесь</code> укажите ваш желаемый ключ доступа к модулю):
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 \
 
Если таких интерфейсов должно быть несколько — добавьте еще один параметр <code>-p</code>
-p 203.0.113.12:80:8080 \
-p 192.168.1.10:80:8080 \
 
* символы <code>\</code> в конце служебные и необходимы для указания того, что команда продолжается со следующей строки, а не завершается.
 
Вы можете использовать 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 ==
 
См: [[Сателлиты#Настройка|Сателлиты]]

Версия от 15:35, 24 января 2022

Описание

Внешний модуль 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

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