Описание сервиса
Eltex-Bob - RESTful API сервис, предназначенный для выгрузки информации о ТД в формате JSON в систему мониторинга. По умолчанию, к сервису можно обратиться по порту 9190, выполнив GET-запрос.
Для получения информации о количестве и состоянии устройств, сервису eltex-bob требуется доступ до БД MYSQL. Для защиты от 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, который содержит:
- apID - MAC-адрес устройства;
- apName - имя устройства;
- grCity - город;
- grRegion - область/регион;
- grTB - территориальный банк;
- vspAddress - графа из справочника с адресом расположение ТД;
- vspNumber - номер ВСП;
- apGroup - сформированное по справочнику месторасположение ТД;
- apRtcGroup - домен , в котором располагается устройство (за исключением скрываемой части - domain_search.regex, см. Настройки сервиса);
Пример:
{ "data": [ { "apGroup": "Поволжский банк/Волгоградская область/Доп.офис №8621-0304", "apID": "a8-f9-4b-b5-a4-a0", "grTB": "Поволжский банк", "grCity": "г.Волгоград, Краснооктябрьский район", "vspNumber": "8621-00304", "apRtcGroup": "Ug/Volgogradskiy_filial/Volgogradskaya_obl/Volgograd/Sberbank/8621-0304_pr-kt_Metallurgov_15", "vspAddress": "400007, г.Волгоград, пр.Металлургов, 15", "apName": "sberbank_ug_vgg_volgograd_8621-0304_a8:f9:4b:b5:a4:a0", "grRegion": "Волгоградская область" }, ] }
Возможные параметры запроса
- Стандартный запрос:
curl -L http://localhost:9190/GetAPList
- grTB - фильтр по полю grTB. При указании этого параметра в ответе от eltex-bob будут содержаться только те объекты, значение grTB которых совпадает с указанным. Если значение параметра пустое, фильтр будет игнорироваться.
пример запроса:
curl -L http://localhost:9190/GetAPList?grTB='Сибирский банк'
GetAPDetail
Детализация информации по ТД , которая содержит :
"ip" - IP-адрес устройства;
"office" - название офиса для найденного ВСП из справочника;
"city" - город для найденного ВСП из справочника;
"firmware-version" - версия ПО;
"serial-number" - серийный номер устройства;
"vsp" - номер ВСП;
"full-address" - полный адрес для найденного ВСП из справочника.
Запрос:
curl -L http://localhost:9190/GetAPDetail/00:00:00:00:00:00
Ответ:
{ "ip": "192.168.6.18", "office": "Доп.офис №178-758", "city": "г.Березовский", "firmware-version": "1.16.0.163", "serial-number": "WP01000177", "vsp": "4157-081" "full-address": "678100, г.Олекминск, ул.Молодежная, 20741" }
GetAPAvailable
Доступность ТД, которая содержит:
"available" - доступность ТД, где 0 - ТД доступна, 1 - ТД недоступна;
"uptime" - время доступности ТД, в секундах.
Запрос:
curl -L http://localhost:9190/GetAPAvailable/00:00:00:00:00:00
Ответ:
{ "available": 0, "uptime": 67370 }
GetAPPerformance
Метрики ТД, которые содержат:
"wifi_users" - количество подключенных пользователей.
Запрос:
curl -L http://localhost:9190/GetAPPerformance/00:00:00:00:00:00
Ответ:
{ "wifi_users": "5" }
Настройки
Для авторизации в сервисе доступно 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; } }
/etc/eltex-bob/application.properties
Основной конфигурационный файл:
- Подключение к БД:
spring.datasource.url=jdbc: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
- Домен, в по которому будет производиться выгрузка. Включает в себя дочерние домены.
domain_search.mask=[a-zA-Z0-9]*\.ap\.root
- Часть домена/ВСП, которая будет скрыта при выводе результата:
domain_search.regex=^root/Ap/(.*)$ domain_search.replacement=$1 vsp_search.regex=/(\\d{2,}[-_]\\d{2,})[^/]*$
- Разделители октетов в мак-адресе (по умолчанию ":"):
mac.splitter=:
- Включение авторизации по логин-паролю, false - выключено:
auth.enabled=true
- Логин/пароль, для авторизации на сервисе bob:
auth.username=user auth.password=password
- Конфигурационный файл для работы со справочником ВСП:
excel.config.file=/etc/eltex-bob/excel_config.yaml
- Порт, который слушает сервиc
server.port=9190
- Крон выражение, определяющее период обновления кэша:
server.cron=0 */10 * ? * *
Следует отменить, что приведенный конфигурационный файл предназначен для доменов вида Ap.root. Если используется только root, то регулярные выражения нужно изменить следующим образом:
# Common properties domain_search.mask=.*root domain_search.regex=^(.*)$ domain_search.replacement=$1
/etc/eltex-bob/excel_config.yaml
Конфигурационный файл для работы со справочником:
- Имя страницы для анализа и путь к справочнику:
vspSheetName: В конкурс vspExcelFile: /home/vagrant/list2.xlsx
- Режим работы с таблицей. TITLE - поиск колонок будет происходить по их заголовкам, NUMBER - поиск колонок будет происходить по их порядковому номеру.
type: TITLE
- Работа с таблицей:
columns: vsp: Номер ВСП - в этой колонке происходит поиск ячейки с номером ВСП совпадающим со значением ВСП из домена, например в домене .../Sberbank/4157-081_Kuznechnaya_11a..., это "4157-081" bank: Территориальный банк \ region: Субъект РФ - ячейки этих столбцов будут использованы для составления APGROUP office: Наименование подразделения / address: Фактитческий адрес Объекта - значение этого поля из этой колонки попадает в FULLADDRESS в выводе GetAPList
/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>
- Уровень логирования
<Root level="error">
Докеризация сервиса
Сервис может быть запущен в docker-контейнере. Для этого необходимо подготовить файл с переменными окружения .env и docker-compose.yml.
version: "3" services: bob: image: hub.eltex-co.ru/softwlc/eltex-bob:1.18-479 network_mode: host ports: - 9190:${BOB_PORT} volumes: - "/etc/eltex-bob/excel_config.yaml:/etc/eltex-bob/excel_config.yaml" - "/etc/eltex-bob/log4j2.xml:/etc/eltex-bob/log4j2-docker.xml" - "/etc/eltex-bob/application.properties:/etc/eltex-bob/application.properties" - "/var/log/eltex-bob:/var/log/eltex-bob" 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} - domain_search.mask=${BOB_DOMAIN_SEARCH_MASK} - domain_search.regex=${BOB_DOMAIN_SEARCH_REGEX} - vsp_search.regex=${BOB_VSP_SEARCH_REGEX}
# common bob params BOB_DB_URL=jdbc:mysql://<IP-address>: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=20 BOB_DOMAIN_SEARCH_MASK=[a-zA-Z0-9\\._-]*\\.Ap\\.root BOB_DOMAIN_SEARCH_REGEX=^root/Ap/(.*)$ BOB_VSP_SEARCH_REGEX=/(\\d{2,}[-_]\\d{2,})[^/]*$ BOB_PORT=9190 BOB_CRON=0 */10 * ? * *
Файлы .env и docker-compose.yml должны находиться в одной папке. Контейнер запускается командой:
docker-compose up
Описание переменных (environment)
Звауск сервиса
- BOB_PORT - порт, на котором сервис будет работать внутри контейнера;
BOB_CRON - крон выражение, отвечающее за период обновления данных в памяти сервиса. Задается в формате крон выражений spring.
Формат отличается от UNIX формата тем, что содержит 6 символов, где первый символ отвечает за секунды.
Подключение к БД (MySQL)
- BOB_DB_URL - URL для подключекния к БД MySQL;
- BOB_DB_USERNAME - Логин подключения к БД;
- BOB_DB_PASSWORD - Пароль подключения к БД;
Параметры фильтрации
- BOB_DOMAIN_SEARCH_MASK - фильтр (регулярное выражение), по которому выбираются домены из БД;
- BOB_DOMAIN_SEARCH_REGEX - фильтр вырезает часть домена для того, чтобы отобразить эту часть в json, например, root.Ap.Sibir, превратить в Ap.Sibir или в Sibir;
- BOB_VSP_SEARCH_REGEX - по этому фильтру выбирается номер ВСП из полного представления домена, например, root.Ap.Sibir.Novosibisrk.Lenina.0000_0000-kakoetovsp.