Описание сервиса

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

Основной конфигурационный файл:

application.properties

# The Datasource Mysql properties
spring.application.name=bob

spring.datasource.url=jdbc:mysql://10.62.18.35: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=10

# Common properties
#domain_search.mask=[a-zA-Z0-9.-_]*.ap.root
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=:

auth.enabled=false
auth.username=user
auth.password=password

excel.config.file=/etc/eltex-bob/excel_config.yaml

server.port=9190
server.cron=0 */10 * ? * *

Подключение к БД:

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

Порт, который слушает сервис:

server.port=9190

Крон выражение, определяющее период обновления кэша:

server.cron=0 */10 * ? * *

Задается в формате крон выражений spring. Формат отличается от UNIX формата тем, что содержит 6 символов, где первый символ отвечает за секунды.

Следует отметить, что приведенный конфигурационный файл предназначен для доменов вида Ap.root. Если используется только root, то регулярные выражения нужно изменить следующим образом:

# Common properties
domain_search.mask=.*root

domain_search.regex=^(.*)$
domain_search.replacement=$1

/etc/eltex-bob/excel_config.yaml

Конфигурационный файл для работы со справочником:

excel_config.yaml

vspSheetName: В конкурс
vspExcelFile: /etc/eltex-bob/vsp.xlsx
type: TITLE
columns:
  vsp: Номер ВСП
  bank: Территориальный банк
  region: Субъект РФ
  office: Наименование подразделения
  address: Фактитческий адрес Объекта
  city: Населенный пункт

## Пример конфигурации по номерам колонок
#vspSheetName: В конкурс
#type: NUMBER
#columns:
#  vsp: 3
#  bank: 1
#  region: 10
#  office: 2
#  address: 7

Имя страницы для анализа и путь к справочнику:

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

Файл инициализации сервиса.

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

Настройки логирования сервиса.

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>

Уровень логирования

<Root level="error">

Докеризация сервиса

Сервис может быть запущен в docker-контейнере. Для этого необходимо подготовить файл с переменными окружения .env и docker-compose.yml.

docker-compose.yml

version: "3"

services:
  bob:
    image: hub.eltex-co.ru/softwlc/eltex-bob:1.19-<tag>
    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}

Вместо <tag> необходимо указать актуальную версию, которую можно посмотреть по ссылке.

.env

# 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.

Дерево страниц

v1.19_Bob

Описание сервиса

Управление сервисом

GetAPList

GetAPDetail

GetAPAvailable

GetAPPerformance

Настройки

nginx и ACL

/etc/eltex-bob/application.properties

/etc/eltex-bob/excel_config.yaml

/etc/default/eltex-bob

/etc/eltex-bob/log4j2.xml

Докеризация сервиса

Описание переменных (environment)

Звауск сервиса

Подключение к БД (MySQL)

Параметры фильтрации