Описание сервиса
Eltex-Bob - RESTful API сервис, предназначенный для выгрузки информации о ТД в формате JSON в систему мониторинга. По умолчанию, к сервису можно обратиться по порту 9190, выполнив GET-запрос.
Для получения информации о количестве и состоянии устройств, требуется доступ до БД MYSQL.
Для защиты от DDoS, сервис имеет собственный кеш, который позволяет не нагружать БД, список ТД сервис запрашивает раз в 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;
}
} |
Настройка профиля юридических лиц
1. В EMS → "Администрирование" → "Права и пользователи" - > "Профили юридических лиц" необходимо добавить профиль, нажав на "+":
На вкладке "Описание профиля" заполнить поля "Имя профиля" и "Описание".
На вкладке "Параметры" нужно добавить новый объект и заполнить необходимые поля:
2. В EMS → "Администрирование" → "Права и пользователи" - > "Домены" нужно выбрать необходимый домен, нажать кнопку редактирования и добавить созданный профиль:
/etc/eltex-bob/application.properties
Основной конфигурационный файл:
# The Datasource Mysql properties
spring.application.name=bob
h2.console.enabled=true
h2.console.port=9111
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
spring.datasource.hikari.maximum-pool-size=20
service.profile.id=2
service.profile.fields=testprofile
spring.mvc.favicon.enabled=false
mac.splitter=-
auth.enabled=false
auth.username=user
auth.password=password
server.port=9190 |
- Средство для диагности проблем в сервисном центре
h2.console.enabled=true
h2.console.port=9111 |
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=2
service.profile.fields=testprofile
|
- Разделители октетов в мак-адресе (в apID и в запросах GetAPDetail, GetAPAvailable, GetAPPerformance, по умолчанию "-")
- Включение авторизации по логин-паролю, false - выключено:
- Логин/пароль, для авторизации на сервисе bob:
auth.username=user
auth.password=password |
- Конфигурационный файл для работы со справочником ВСП:
excel.config.file=/etc/eltex-bob/excel_config.yaml |
- Порт, который слушает сервис
/etc/default/eltex-bob
Файл инициализации сервиса.
# AP Monitoring service
# Initial size of Java heap
JAVA_INIT_HEAP=128m
# Maximum size of Java heap
JAVA_MAX_HEAP=256m
# Additional arguments to pass to java
JAVA_OPTS="-XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/var/log/eltex-bob" |
Параметры | Описание |
---|
JAVA_INIT_HEAP | Количество памяти, выделяемое на работу сервиса при старте. Рекомендуется выставлять равное JAVA_MAX_HEAP. |
JAVA_MAX_HEAP | Максимальное количество памяти, которое может зарезервировать сервис |
JAVA_OPTS | Дополнительные опции для запуска jvm |
/etc/eltex-bob/log4j2.xml
Настройки логирования сервиса.
<?xml version="1.0" encoding="UTF-8"?>
<Configuration>
<Properties>
<Property name="maxSize" value="5MB"/>
<Property name="maxCount" value="7"/>
<Property name="logDir" value="/var/log/eltex-bob"/>
<Property name="defaultPattern" value="%d{ISO8601} [%t] %-5p %logger{1} %C{1}.%M(line:%L). %m%n"/>
<Property name="gelfHost" value="udp:lab3-test.eltex.loc"/>
<Property name="gelfPort" value="12201"/>
<Property name="gelfLevel" value="OFF"/>
<Property name="filenamePrefix" value="eltex-bob"/>
</Properties>
<Appenders>
<Console name="STDOUT" target="SYSTEM_OUT">
<PatternLayout>
<Pattern>${defaultPattern}</Pattern>
</PatternLayout>
</Console>
<RollingFile name="SPRING-INFO"
fileName="${logDir}/${filenamePrefix}-spring.log"
filePattern="${logDir}/%d{yyyyMMdd}.%i.log">
<ThresholdFilter level="INFO" onMatch="ACCEPT" onMismatch="DENY"/>
<PatternLayout>
<pattern>${defaultPattern}</pattern>
</PatternLayout>
<Policies>
<SizeBasedTriggeringPolicy size="${maxSize}"/>
</Policies>
<DefaultRolloverStrategy max="${maxCount}"/>
</RollingFile>
<RollingFile name="SERVICE-ERROR"
fileName="${logDir}/${filenamePrefix}-error.log"
filePattern="${logDir}/%d{yyyyMMdd}.%i.log">
<ThresholdFilter level="ERROR" onMatch="ACCEPT" onMismatch="DENY"/>
<PatternLayout>
<pattern>${defaultPattern}</pattern>
</PatternLayout>
<Policies>
<SizeBasedTriggeringPolicy size="${maxSize}"/>
</Policies>
<DefaultRolloverStrategy max="${maxCount}"/>
</RollingFile>
<RollingFile name="SERVICE-INFO"
fileName="${logDir}/${filenamePrefix}-info.log"
filePattern="${logDir}/%d{yyyyMMdd}.%i.log">
<ThresholdFilter level="INFO" onMatch="ACCEPT" onMismatch="DENY"/>
<PatternLayout>
<pattern>${defaultPattern}</pattern>
</PatternLayout>
<Policies>
<SizeBasedTriggeringPolicy size="${maxSize}"/>
</Policies>
<DefaultRolloverStrategy max="${maxCount}"/>
</RollingFile>
<Gelf name="Gelf"
host="${gelfHost}"
port="${gelfPort}"
version="1.1"
facility="${filenamePrefix}"
extractStackTrace="true"
originHost="%host{fqdn}"
maximumMessageSize="8192" >
<Field name="thread" pattern="%t" />
<Field name="level" pattern="%level" />
<Field name="severity" pattern="%-5level" />
<Field name="logger" pattern="%logger{1}" />
<Field name="location" pattern="%C{1}.%M(line:%L)" />
</Gelf>
</Appenders>
<Loggers>
<Logger name="org.springframework" level="info" additivity="false">
<AppenderRef ref="SPRING-INFO"/>
</Logger>
<Logger name="org.eltex.softwlc.bob" level="error" additivity="false">
<AppenderRef ref="SERVICE-ERROR"/>
</Logger>
<Logger name="org.eltex.softwlc.bob" level="info" additivity="false">
<AppenderRef ref="SERVICE-INFO"/>
</Logger>
<Root level="error">
<AppenderRef ref="Gelf" level="${gelfLevel}"/>
</Root>
</Loggers>
</Configuration> |
- Максимально допустимый размер файла (при его превышении создается новый файл. а старый архивируется):
<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> |
Докеризация сервиса
Сервис может быть запущен в docker-контейнере. Для этого необходимо подготовить файл с переменными окружения .env и docker-compose.yml.
version: "3"
services:
bob:
image: hub.eltex-co.ru/softwlc/eltex-bob:1.19-<tag>
network_mode: host
ports:
- 9190:9190
- 9111:9111
volumes:
- "/etc/eltex-bob/log4j2.xml:/etc/eltex-bob/log4j2.xml"
- "/var/log/eltex-bob:/var/log/eltex-bob"
environment:
- spring.datasource.url=${BOB_DB_URL}
- spring.datasource.username=${BOB_DB_USERNAME}
- spring.datasource.password=${BOB_DB_PASSWORD}
- service.profile.id=${BOB_CLIENT_PROFILE}
- service.profile.fields=${BOB_CLIENT_PROFILE_FIELDS}
- fields=${BOB_CLIENT_PROFILE_FIELDS}
|
Вместо <tag> необходимо указать актуальную версию, которую можно посмотреть по ссылке. |
# common bob params
BOB_DB_URL=r2dbc:mysql://100.110.1.228:3306/eltex_ems?useSSL=false&useJDBCCompliantTimezoneShift=true&useLegacyDatetimeCode=false&serverTimezone=UTC
BOB_DB_USERNAME=javauser
BOB_DB_PASSWORD=javapassword
BOB_CLIENT_PROFILE=2
BOB_CLIENT_PROFILE_FIELDS=testprofile |
Файлы .env и docker-compose.yml должны находиться в одной папке. Контейнер запускается командой:
Описание переменных (environment)
Звауск сервиса
- BOB_PORT - порт, на котором сервис будет работать внутри контейнера;
Подключение к БД (MySQL)
- BOB_DB_URL - URL для подключекния к БД MySQL;
- BOB_DB_USERNAME - Логин подключения к БД;
- BOB_DB_PASSWORD - Пароль подключения к БД;
Параметры фильтрации
- BOB_CLIENT_PROFILE - id профиля юридических лиц;
- BOB_CLIENT_PROFILE_FIELDS - имя профиля юридических лиц.