Описание сервиса
Eltex-Bob - RESTful API сервис, предназначенный для выгрузки информации о ТД в формате JSON в систему мониторинга. По умолчанию, к сервису можно обратиться по порту 9190, выполнив GET-запрос.
Для получения информации о количестве и состоянии устройств, сервису eltex-bob требуется доступ до БД MariaDB. Для защиты от DDoS, сервис имеет собственный кэш, который позволяет не нагружать БД. Кэш сервиса обновляется с периодом, регулируемым с помощью крон-выражения в конфигурационном файле сервиса, либо в файле .env при работе сервиса в докер-контейнере. По умолчанию eltex-bob обновляет кэш один раз в 10 минут.
За обновление информации в БД, необходимой для работы eltex-bob отвечает сервис eltex-ems. Сервис eltex-ems обладает собственным кэшем, в котором хранится информация об устройствах. Регулирование периода опроса устройств для актуализации информации в кэше осуществляется параметром «Период опроса устройства (ICMP/SNMP)» в меню «Администрирование – Настройка сервера – Системные модули - system». Уменьшением значения данного параметра можно добиться более частого обновления информации об устройствах в кэше сервиса. Обновление информации в БД по кэшу eltex-ems происходит с периодом 1 минута.
Доступные методы API:
- http://<<ip_address>>:<<port>>/GetAPList Список ТД в формате JSON
- http://<<ip_address>>:<<port>>/GetAPDetail/{MAC_ADDRESS} - Детализация информации по ТД
- http://<<ip_address>>:<<port>>/GetAPAvailable/{MAC_ADDRESS} - Доступность ТД
- http://<<ip_address>>:<<port>>/GetAPPerformance/{MAC_ADDRESS} - Метрики по ТД
Управление сервисом
GetAPList
Предоставляет список ТД в формате JSON, который содержит:
- grRegion - область/регион;
- vspNumber - номер ВСП;
- apID - MAC-адрес устройства;
- apRtcGroup - домен , в котором располагается устройство
- grTB - территориальный банк;
- apGroup - месторасположение ТД;
- vspAddress - адрес ВСП;
- apName - имя устройства;
- grCity - город;
Пример:
{
"data": [
{
"grRegion":"Самарская",
"vspNumber":"****-*****",
"apID":"00-00-00-00-00-00",
"apRtcGroup":"toor.pA",
"grTB":"банк",
"apGroup":"банк/Самарская/Доп.офис №****-****",
"vspAddress":"******, Самара, Самарская, *",
"apName":"****-****_Samarskaya_*_00:00:00:00:00:00",
"grCity":"Самара"
},
]
}
Возможные параметры запроса
- Стандартный запрос:
curl -L http://localhost:9190/GetAPList
GetAPDetail
Детализация информации по ТД , которая содержит :
- "firmware-version" - версия ПО;
- "full-address" - полный адрес ТД.
- "vsp" - номер ВСП;
- "city" - город расположения ТД;
- "serial-number" - серийный номер устройства;
- "ip" - IP-адрес устройства;
- grTB - территориальный банк;
- "office" - название офиса , где расположена ТД;
Запрос:
curl -L http://localhost:9190/GetAPDetail/00-00-00-00-00-00
Ответ:
{
"firmware-version":"1.0.0.0",
"full-address":"Волгоград, Металлургов, *",
"vsp":"****-*****",
"city":"Волгоград",
"serial-number":"",
"ip":"127.0.0.1",
"grTB":"банк",
"office":"Доп.офис №****-****"
}
GetAPAvailable
Доступность ТД, которая содержит:
- "available" - доступность ТД, где 0 - ТД доступна, 1 - ТД недоступна;
- "uptime" - время доступности ТД, в секундах.
Запрос:
curl -L http://localhost:9190/GetAPAvailable/00-00-00-00-00-00
Ответ:
{
"available": 0,
"uptime": 67370
}
GetAPPerformance
Метрики ТД, которые содержат:
- "wifi_users" - количество подключенных пользователей,
- "mac" - mac-адрес ТД
Запрос:
curl -L http://localhost:9190/GetAPPerformance/00-00-00-00-00-00
Ответ:
{
"wifi_users": "5"
"mac":"00-00-00-00-00-00"
}
Настройки
Для авторизации в сервисе доступно 2 способа:
- http-basic авторизация, включается в настройках сервиса;
- ACL-список в настройках конфигурации nginx, включается в конфигурационном файле nginx.
nginx и ACL
Для ограничения доступа к сервису по IP-адресу, можно выполнить настройку nginx сервера с помощью ACL. Access Control List добавляется в конфигурационный файл nginx, пример :
location /api {
allow 192.168.1.3/24;
allow 127.0.0.1;
deny all;
}
deny - IP-address, с которого запрещен доступ;
allow - IP-address, с которого разрешен доступ.
В примере, доступ с IP-адреса 192.168.1.3 и 127.0.0.1 разрешен, остальным запрещен.
Eсли используется nginx для доступа к сервису eltex-bob, то следует настроить проксирование:
server {
listen 80;
server_name bob;
location /api/ {
proxy_pass http://localhost:9190/;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Real-IP $remote_addr;
proxy_redirect default;
}
}
Настройка профиля юридических лиц
В EMS → "Администрирование" → "Права и пользователи" - > "Профили юридических лиц" необходимо добавить профиль, нажав на "+":
На вкладке "Описание профиля" заполнить поля "Имя профиля" и "Описание".
На вкладке "Параметры" нужно добавить новый объект и заполнить необходимые поля:
Добавление параметров не является обязательным!
Привязка профиля юридических лиц
В EMS → "Администрирование" → "Права и пользователи" - > "Домены" нужно выбрать необходимый домен, нажать кнопку редактирования и добавить созданный профиль:
Новый профиль появится в списке:
Обратим внимание на цифру слева от профиля- это id профиля, который в дальнейшем указывается в настройке "service.profile.id" .
Создание и привязка профиля является необходимым условием, т.к. именно привязка профиля к определенному домену указывает в какой ветке искать ТД и формировать информацию для выгрузки!
Заполнение параметров профиля в дереве доменов для выгрузки дополнительной информации
При необходимости для профиля юридических лиц могут быть добавлены дополнительные параметры выгрузки. Добавление параметров в профиль юридических лиц рассмотрено выше. При настройке сервиса они указываются в параметре "service.profile.fields" (если параметров несколько - перечисляются через ","), в выгружаемую информацию по ТД будут добавляться только параметры указанные в настройке.
Заполнение параметров осуществляется непосредственно в домене, содержащем ТД. Для этого открываем "Администрирование" → "Права и пользователи" - > "Домены", выбираем нужный домен, содержащий ТД и нажимаем кнопку редактирования:
Заполняем параметр для домена:
и нажимаем кнопку "Принять".
Аналогично заполняется информация для других доменов.
Выгрузка информации для указанных в настройке параметров осуществляется независимо от их заполненности. Если параметр не заполнен - в выгрузке будет указано значение "null".
/etc/eltex-bob/application.properties
Основной конфигурационный файл:
- Средство для диагностики проблем в сервисном центре
h2.console.enabled=true h2.console.port=9111 h2.user=sa h2.password=h2bob
Важно!
Для предотвращения возможности доступа к консоли с дефолтным логином/паролем по умолчанию она отключена!
После установки пакета требуется включить её:
h2.console.enabled=true
Сменить дефолтный пароль:
h2.password=pa$$w0rd
Выполнить перезапуск сервиса:
systemctl restart eltex-bob
- Подключение к БД:
spring.datasource.url=r2dbc:mysql://localhost:3306/eltex_ems?useSSL=false&useJDBCCompliantTimezoneShift=true&useLegacyDatetimeCode=false&serverTimezone=UTC spring.datasource.username=javauser spring.datasource.password=javapassword
- Количество коннектов к БД. По умолчанию, сервис использует 10 коннектов до БД, при необходимости можно увеличить.
spring.datasource.hikari.maximum-pool-size=10
- Данные профиля юридических лиц.
service.profile.id=1 service.profile.fields=vsp,grTB,officeName service.profile.fields=testprofile
- Разделители октетов в мак-адресе (в apID и в запросах GetAPDetail, GetAPAvailable, GetAPPerformance, по умолчанию "-")
mac.splitter=-
- Включение авторизации по логин-паролю, false - выключено:
auth.enabled=true
- Логин/пароль, для авторизации на сервисе bob:
auth.username=user auth.password=password
- Конфигурационный файл для работы со справочником ВСП:
excel.config.file=/etc/eltex-bob/excel_config.yaml
- Порт, который слушает сервис
server.port=9190
- Крон выражение, определяющее период обновления кэша:
server.cron=0 */10 * ? * *
Задается в формате крон выражений spring. Формат отличается от UNIX формата тем, что содержит 6 символов, где первый символ отвечает за секунды.
/etc/default/eltex-bob
Файл инициализации сервиса.
| Параметры | Описание |
|---|---|
JAVA_INIT_HEAP | Количество памяти, выделяемое на работу сервиса при старте. Рекомендуется выставлять равное JAVA_MAX_HEAP. |
JAVA_MAX_HEAP | Максимальное количество памяти, которое может зарезервировать сервис |
JAVA_OPTS | Дополнительные опции для запуска jvm |
/etc/eltex-bob/log4j2.xml
Настройки логирования сервиса.
- Максимально допустимый размер файла (при его превышении создается новый файл. а старый архивируется):
<Property name="maxSize" value="5MB"/>
- Максимальное количество архивных файлов, при его превышении наиболее старые файлы будут перезаписываться:
<Property name="maxCount" value="7"/>
- Базовая директория хранения логов:
<Property name="logDir" value="/var/log/eltex-bob"/>
- Блок настройки перенаправления логов в Graylog (уровень логирования, адрес, порт):
<Property name="gelfLevel">${env:GELF_LEVEL:-OFF}</Property>
<Property name="gelfHost">${env:GELF_HOST:-udp:lab3-test.eltex.loc}</Property>
<Property name="gelfPort">${env:GELF_PORT:-12201}</Property>
- Уровень логирования
<Property name="rootLevel" value="ERROR"/>
Докеризация сервиса
Сервис может быть запущен в docker-контейнере. Для этого необходимо подготовить файл с переменными окружения .env и docker-compose.yml.
version: "3"
services:
bob:
image: ${ELTEX_HUB}/eltex-bob:${SWLC_VERSION}
ports:
- 9190:${BOB_PORT}
- 9111:${BOB_H2_CONSOLE_PORT}
volumes:
- /etc/timezone:/etc/timezone:ro
environment:
- server.port=${BOB_PORT}
- server.cron=${BOB_CRON}
- spring.datasource.url=${BOB_DB_URL}
- spring.datasource.username=${BOB_DB_USERNAME}
- spring.datasource.password=${BOB_DB_PASSWORD}
- service.profile.id=${BOB_SERVICE_PROFILE_ID}
- service.profile.fields=${BOB_SERVICE_PROFILE_FIELDS}
- service.profile.mapper=${BOB_SERVICE_PROFILE_MAPPER}
- h2.console.enabled=${BOB_H2_CONSOLE_ENABLED}
- h2.console.port=${BOB_H2_CONSOLE_PORT}
- h2.user=${BOB_H2_USER}
- h2.password=${BOB_H2_PASSWORD}
- BOB_LOG_LEVEL=${BOB_LOG_LEVEL}
- BOB_CONSOLE_LOG_LEVEL=${BOB_CONSOLE_LOG_LEVEL}
# Настройка перенаправления логов в Graylog
- GELF_LEVEL=${GELF_LEVEL}
- GELF_HOST=${GELF_HOST}
- GELF_PORT=${GELF_PORT}
- TZ=${TZ}
ELTEX_HUB=hub.eltex-co.ru/softwlc SWLC_VERSION=1.23-<tag> # Bob ENV BOB_PORT=9190 BOB_CRON=0 */10 * ? * * BOB_DB_URL=r2dbc:mysql://<ip_mariadb_server>:3306/eltex_ems?useSSL=false&useJDBCCompliantTimezoneShift=true&useLegacyDatetimeCode=false&serverTimezone=UTC BOB_DB_USERNAME=javauser BOB_DB_PASSWORD=javapassword BOB_DB_HIKARI_MAXIMUM_POOL_SIZE=1 BOB_SERVICE_PROFILE_ID=1 BOB_SERVICE_PROFILE_FIELDS=vsp,grTB,officeName BOB_SERVICE_PROFILE_MAPPER=testprofile #Доступ к консоли BOB_H2_CONSOLE_ENABLED=true BOB_H2_CONSOLE_PORT=9111 BOB_H2_USER=sa BOB_H2_PASSWORD=h2bob # Настройка логгирования BOB_CONSOLE_LOG_LEVEL=INFO BOB_LOG_LEVEL=INFO GELF_LEVEL=OFF GELF_HOST=udp:<ip_graylog_server> GELF_PORT=12201 #Настройка часового пояса TZ=Asia/Novosibirsk
Рекомендуется обязательно включить консоль сервиса и сменить дефолтный пароль для доступа к ней:
BOB_H2_CONSOLE_ENABLED=true BOB_H2_PASSWORD=pa$$w0rd
Вместо <tag> необходимо указать актуальную версию, которую можно посмотреть по ссылке.
Вместо <ip_mariadb_server> необходимо указать ip-адрес сервера MariaDB.
Файлы .env и docker-compose.yml должны находиться в одной папке. Контейнер запускается командой:
docker-compose up -d
Описание переменных (environment)
Запуск сервиса
BOB_PORT - порт, на котором сервис будет работать внутри контейнера;
- BOB_CRON - крон выражение, отвечающее за период обновления данных в памяти сервиса. Задается в формате крон выражений spring.
Формат отличается от UNIX формата тем, что содержит 6 символов, где первый символ отвечает за секунды; ELTEX_HUB - URL репозитория Элтекс;
SWLC_VERSION - версия образа;
Подключение к БД (MariaDB)
BOB_DB_URL - URL для подключения к БД MariaDB;
BOB_DB_USERNAME - Логин подключения к БД;
BOB_DB_PASSWORD - Пароль подключения к БД;
Параметры фильтрации
BOB_CLIENT_PROFILE - id профиля юридических лиц;
- BOB_SERVICE_PROFILE_FIELDS - дополнительные параметры выгрузки для юридических лиц;
BOB_CLIENT_PROFILE_FIELDS - имя профиля юридических лиц.
Параметры логгирования
BOB_CONSOLE_LOG_LEVEL - уровень логгирования сервиса в консоль;
BOB_LOG_LEVEL - уровень логгирования сервиса;
Параметры доступа к консоли:
- BOB_H2_CONSOLE_ENABLED - включение/отключение консоли. Может принимать значения: true/false;
- BOB_H2_CONSOLE_PORT - порт подключения к консоли;
- BOB_H2_USER - логин для доступа к консоли;
- BOB_H2_PASSWORD - пароль для доступа к консоли.
Настройка перенаправления логов на сервер Graylog
GELF_LEVEL - уровень логов, перенаправляемых в Graylog
GELF_HOST - адрес хоста Graylog
GELF_PORT - порт хоста Graylog
Настройка часового пояса
- TZ - часовой пояс в формате Asia/Novosibirsk (список существующих можно посмотреть командой timedatectl list-timezones).
Диагностика
Доступ к диагностической консоли сериса
По умолчанию доступ к диагностической консоли сервиса (далее "консоль") по умолчанию отключен, для предотвращения несанкционированного доступа с дефолтным логином паролем. Рекомендуется заранее при установке сервиса включить доступ и сменить дефолтный логин пароль. Подробное описание параметром приведено выше.
После конфигурирования параметров требуется перезапустить сервис:
systemctl restart eltex-bob
Или перезапустить контейнер:
docker-compose stop docker-compose up -d
Подключение к диагностической консоли сервиса
Подключение к консоли можно выполнить в любом браузере, введя адрес:
http://<IP-адрес сервиса>:<порт консоли>
Откроется окно доступа:
Потребуется ввести:
- JDBC URL: jdbc:h2:mem:bobmemdb
- User Name: sa (или другой, указанный в параметре h2.user)
- Password: пароль, указанный в параметре h2.password
И нажать на кнопку "Test Connection", что бы проверить правильность введеных данных.
Если внизу появиться надпись "Test successful" - значит данные ведены правильно.
Повторно ввести пароль и нажать кнопку "Connect" - откроется окно консоли:
Просмотр информации в диагностической консоли сервиса
Для просмотра используются SQL команды, вводимые в окно наверху справа от информации о таблицах.
Для просмотра информации о всех ТД, которые находятся в кэше сервиса надо ввести команду "SELECT * FROM DEVICES;" и нажать кнопку "Run":
Для просмотра информации по отдельной ТД по её MAC-адресу ввести "SELECT * FROM DEVICES WHERE MAC='e0-d9-e3-70-59-20';". Следует обратить внимание, что разделитель MAC-адреса надо указывать к в настройке "mac.splitter":
