Дерево страниц
Перейти к концу метаданных
Переход к началу метаданных

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


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

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

application.properties
# The Datasource Mysql properties
spring.application.name=bob
h2.console.enabled=false
h2.console.port=9111
h2.user=sa
h2.password=h2bob

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=1
service.profile.fields=vsp,grTB,officeName
service.profile.fields=testprofile

spring.mvc.favicon.enabled=false

mac.splitter=-

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

server.port=9190
server.cron=0 */10 * ? * *
  • Средство для диагностики проблем в сервисном центре
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

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

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"/>
        <Property name="rootLevel" value="ERROR"/>
    </Properties>

    <Appenders>

        <RollingFile name="SPRING-INFO"
                     fileName="${logDir}/${filenamePrefix}-spring.log"
                     filePattern="${logDir}/%d{yyyyMMdd}.%i.log">
            <ThresholdFilter level="DEBUG" onMatch="ACCEPT" onMismatch="DENY"/>
            <PatternLayout>
                <pattern>${defaultPattern}</pattern>
            </PatternLayout>
            <Policies>
                <SizeBasedTriggeringPolicy size="${maxSize}"/>
            </Policies>
            <DefaultRolloverStrategy max="${maxCount}"/>
        </RollingFile>

        <RollingFile name="SERVICE"
                     fileName="${logDir}/${filenamePrefix}.log"
                     filePattern="${logDir}/%d{yyyyMMdd}.%i.log">
            <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>

        <Root level="${rootLevel}">
            <AppenderRef ref="Gelf" level="${gelfLevel}"/>
        </Root>

        <Logger name="org.springframework" level="ERROR">
            <AppenderRef ref="SPRING-INFO"/>
        </Logger>

        <Logger name="org.eltex.softwlc.bob" level="ERROR">
            <AppenderRef ref="SERVICE"/>
        </Logger>

    </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>
  • Уровень логирования
<Property name="rootLevel" value="ERROR"/>

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


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

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}
.env
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.

Вместо <ip_graylog_server> необходимо указать ip-адрес сервера Graylog.

Файлы .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).

Диагностика

Доступ к диагностической консоли сериса

По умолчанию доступ к диагностической консоли сервиса (далее "консоль") по умолчанию отключен, для предотвращения несанкционированного доступа с дефолтным логином паролем. Рекомендуется заранее при установке сервиса включить доступ и сменить дефолтный логин пароль. Подробное описание параметром приведено выше.

Пример конфигурации параметров в файле /etc/eltex-bob/application.properties
h2.console.enabled=true
h2.console.port=9111
h2.user=sa
h2.password=pa$$w0rd
Пример конфигурации параметров при запуске сервиса в докере
В файле ".env"
BOB_H2_CONSOLE_ENABLED=true
BOB_H2_CONSOLE_PORT=9112
BOB_H2_USER=admin
BOB_H2_PASSWORD=testing123

В файле "docker-compose.yml"
      - h2.console.enabled=${BOB_H2_CONSOLE_ENABLED}
      - h2.console.port=${BOB_H2_CONSOLE_PORT}
      - h2.user=${BOB_H2_USER}
      - h2.password=${BOB_H2_PASSWORD}

После конфигурирования параметров требуется перезапустить сервис:

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":




  • Нет меток