Описание

Модуль Eltex-APB предназначен для обмена информацией между точками доступа. Обеспечивает:

  • Роуминг пользователей, подключившихся при помощи авторизации на WEB-портале
  • Настройку и передачу списков белых адресов при портальной авторизации

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

Установка сервиса

apt-get install eltex-apb

Способ запуска/остановки:

ДействиеКомандаОтвет
Проверка состояния


service eltex-apb status



Сервис работает

eltex-apb is running with pid <pid>



Сервис не работает

eltex-apb is not running



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


service eltex-apb start



Сервис запустился

Starting eltex-apb ...
eltex-apb started



Сервис уже работает

eltex-apb is already running




Остановка сервиса


service eltex-apb stop



Сервис успешно остановлен

Stopping eltex-apb ...
eltex-apb stopped



Сервис не остановлен, т.к. не был запущен

eltex-apb is not running
rm: cannot remove '/var/run/eltex-apb.pid': No such file or directory



Перезапуск сервиса


service eltex-apb restart



Сервис успешно перезапущен

Stopping eltex-apb ...
eltex-apb stopped
Starting eltex-apb ...
eltex-apb started




Просмотр точек доступа, которые находятся под управлением сервиса:

http://localhost:8090/apb/ap.jsp

Просмотр пользователей, которые находятся под управлением сервиса:

http://localhost:8090/apb/users.jsp

Просмотр числа пользователей, которые находятся под управлением сервиса:

http://localhost:8090/apb/users.jsp?short


Конфигурация

/etc/default/eltex-apb

Содержит параметры, необходимые для инициализации сервиса.

# Port for use by Access Point Binder service
PORT=8090
# Number of connection requests that can be queued
ACCEPT_QUEUE_SIZE=0
# Max text message buffer size, in bytes
MAX_TEXT_MESSAGE_BUFFER_SIZE=524288

# Path to Java executable
JAVA=/usr/bin/java

# Memory
JAVA_INIT_HEAP=128m
JAVA_MAX_HEAP=2048m

JAVA_OPTS="-XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/var/log/eltex-apb"

# To enable remote JMX monitoring uncomment the following line
#JMX_OPTS="-Dcom.sun.management.jmxremote -Dcom.sun.management.jmxremote.port=8091 -Dcom.sun.management.jmxremote.ssl=false -Dcom.sun.management.jmxremote.authenticate=false -Dcom.sun.management.jmxremote.local.only=false -Djava.rmi.server.hostname=127.0.0.1"
  • Слушаемый порт:
PORT=8090
  • Длина очереди запросов. При заполнении очереди, новые запросы будут игнорироваться сервером, пока старые запросы не будут обработаны (по дефолту очередь не будет накапливаться):
ACCEPT_QUEUE_SIZE=0
  • Максимальный размер буфера сообщения, в байтах:
MAX_TEXT_MESSAGE_BUFFER_SIZE=262144

  • Настройка памяти, выделяемой на работу сервиса (память выделяется на сам процесс, а не на кэш, прописанный в /etc/eltex-apb/ehcache.xml):

JAVA_INIT_HEAP=128m
JAVA_MAX_HEAP=2048m


/etc/eltex-apb/application.conf

Содержит основные настройки сервиса.


Файл настроек /etc/eltex-apb/application.conf используется начиная с версии SoftWLC 1.20. В предыдущих версиях использовался файл /etc/eltex-apb/apb.properties .

Основные настройки сервиса.

# maximum number of outgoing messages in queue for each session
sessionMessageQueueSize = 100

# path to the file with permitted hosts
hostsFile = /etc/eltex-apb/hosts.json

pingJob {
  # ping job interval
  interval = 60s

  # timeout waiting for subscribe-request after connecting the access point to the server
  subscribeIdleTimeout = 60s
  # timeout during that the session will stay opened without receiving any message
  messageIdleTimeout = 90s
  # interval of ping to be sent to the websocket session
  pingIdleTimeout = 30s
}

# eltex-mercury connection properties
mercury {
  host = localhost
  port = 6565
  poolSize = 50
}

jdbc {
    url = "jdbc:mysql://localhost:3306/eltex_apb?useUnicode=true&characterEncoding=utf8&relaxAutoCommit=true&connectTimeout=10000&socketTimeout=10000&useSSL=false"
    username = javauser
    password = javapassword
    driver = "com.mysql.cj.jdbc.Driver"
    maxPoolSize = 16
}

cache {
    port = 5704
    ttlSeconds = 43200
    bootstrap {
        enabled = true
        batchSize = 10000
    }
    store {
        writePeriodSeconds = 2
        writeBatchSize = 200
    }
}

cluster {
    enabled = false
    members = ["", ""]
    publicNodeAddress = 127.0.0.1
    notifications {
        publishBatchSize = 50
        publishPeriodSeconds = 3
        processingThreads = 4
        processingBatchSize = 100
    }
}

dbCleanJob {
    usersExpiredPeriodDays = 90
    cronExprToCleanUsersTable = "0 0 0 15 * *"
}
  • Настройки для подключения к сервису Mercury:
mercury {
  host = localhost
  port = 6565
  poolSize = 50
}
  • Расположение необходимых файлов:
# path to the file with permitted hosts
hostsFile = /etc/eltex-apb/hosts.json
  • Интервал запуска службы по выполнению websocket-пингов:
  # ping job interval
  interval = 60s
  • Время ожидания запроса подписки после подключения точки доступа к серверу, в секундах (если ТД подключается, но не шлёт subscribe в течение данного интервала, то при очередном запуске службы websocket-пингов такая сессия ТД будет отключена):
  # timeout waiting for subscribe-request after connecting the access point to the server
  subscribeIdleTimeout = 60s
  • Время, в течение которого сессия остается открытой без отправки сообщений:
  # timeout during that the session will stay opened without receiving any message
  messageIdleTimeout = 90s
  • Интервал между последним полученным сообщением от ТД и выполнением websocket-пинга к ней. В случае неответа ТД, её сессия будет отключена от сервиса:
  # interval of ping to be sent to the websocket session
  pingIdleTimeout = 30s
  • Максимальное количество исходящих сообщений для очереди на каждый сеанс:
# maximum number of outgoing messages in queue for each session
sessionMessageQueueSize = 100
  • Настройки подключения к БД MariaDB
jdbc {
    url = "jdbc:mysql://localhost:3306/eltex_apb?useUnicode=true&characterEncoding=utf8&relaxAutoCommit=true&connectTimeout=10000&socketTimeout=10000&useSSL=false"
    username = javauser
    password = javapassword
    driver = "com.mysql.cj.jdbc.Driver"
    maxPoolSize = 16
}
  • Настройки кэша Hazelcast
cache {
    port = 5704
    ttlSeconds = 43200
    bootstrap {
        enabled = true
        batchSize = 10000
    }
    store {
        writePeriodSeconds = 2
        writeBatchSize = 200
    }
}
  • Настройки режима кластера
cluster {
    enabled = false
    members = ["", ""]
    publicNodeAddress = 127.0.0.1
    notifications {
        publishBatchSize = 50
        publishPeriodSeconds = 3
        processingThreads = 4
        processingBatchSize = 100
    }
}
  • Настройки периодической очистки БД
dbCleanJob {
    usersExpiredPeriodDays = 90
    cronExprToCleanUsersTable = "0 0 0 15 * *"
}

/etc/eltex-apb/hosts.json

Cодержит набор списков белых адресов. В данном конфигурационном файле выполняется настройка белых списков (списки IP-адресов, на который можно перейти до авторизации на портале). При необходимости название и расположение файла может быть изменено в /etc/eltex-apb/application.conf. По умолчанию данный список является пустым.

Пример заполнения файла:

[
  {
    "mobility-domain-list": [
      {
        "mobility-domain": "eltex.root",
        "radius-domain": "root",
        "ssid": "Eltex-Local"
      }
    ],
    "permitted-ip-list": [
      "eltex-co.ru",
      "eltex.org"
    ]
  },
  {
    "permitted-ip-list": [
        "esia-portal1.test.gosuslugi.ru",
        "esia.gosuslugi.ru",
    ]
  }
]

  • Белый список, общий для всех подключенных точек задается в формате:
  [{
    "permitted-ip-list": [
        "esia-portal1.test.gosuslugi.ru",
        "esia.gosuslugi.ru",
    ]
  }]


  • Белый список, который назначается на точки с определенным SSID и доменом, записывается в следующем формате:
  [{
    "mobility-domain-list": [
      {
        "mobility-domain": "eltex.root",
        "radius-domain": "root",
        "ssid": "Eltex-Local"
      }
    ],
    "permitted-ip-list": [
      "eltex-co.ru",
      "eltex.org"
    ]
  }]

Запись в приведенном выше конфигурационном файле говорит о том, что если на сервис поступит информация о пользователе, чьим mobility-domain является eltex.root, radius-domain является root, а ssid – Eltex-Local, то данному пользователю до авторизации на портале помимо адресов из общего белого списка, будут доступны адреса eltex-co.ru и eltex.org. Другими словами, адреса, находящиеся в «permitted-ip-list», будут доступны пользователю, в случае полного совпадения всех ключей, описанных в рамках одного «mobility-domain-list».

Если параметры пользователя удовлетворяют критериям нескольких правил, ему будут разрешены для доступа IP-адреса из всех таких правил.

В параметр "mobility-domain" вносится значение параметра "ap-location" точки доступа, который находится в разделе сетевых настроек.


/etc/eltex-apb/log4j2.xml

Содержит настройки логирования.

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="OFF" monitorInterval="10">
    <Properties>
        <Property name="rootLevel">${env:LOG_LEVEL:-INFO}</Property>

        <Property name="baseDir">/var/log/eltex-apb</Property>
        <Property name="maxFileSize">20 MB</Property>
        <Property name="accumulatedFileSize">100 MB</Property>
        <Property name="lastModified">4d</Property>
        <Property name="maxCount">7</Property>
        <Property name="logPattern">%d{ISO8601} [%t] %-5p %logger{1} %C{1}.%M(line:%L). %m%n</Property>
        <Property name="dateSuffix">%d{yyyyMMdd}</Property>

		<Property name="consoleLevel">${env:CONSOLE_LEVEL:-OFF}</Property>
		<Property name="hazelcastLogLevel">${env:HAZELCAST_LOG_LEVEL:-INFO}</Property>

        <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>
    </Properties>

    <Appenders>
        <Console name="STDERR" target="System.err">
            <PatternLayout pattern="${logPattern}"/>
        </Console>

        <RollingFile name="RollingFile"
                     filename="${baseDir}/apb.log"
                     filepattern="${baseDir}/log/apb-${dateSuffix}-%i.log.gz">
            <PatternLayout pattern="${logPattern}"/>
            <Policies>
                <TimeBasedTriggeringPolicy interval="1" modulate="true"/>
                <SizeBasedTriggeringPolicy size="${maxFileSize}"/>
                <OnStartupTriggeringPolicy />
            </Policies>
            <DefaultRolloverStrategy max="${maxCount}">
                <Delete basePath="${baseDir}" maxDepth="1">
                    <IfFileName glob="*/apb-*.log.gz">
                        <IfAny>
                            <IfAccumulatedFileSize exceeds="${accumulatedFileSize}"/>
                            <IfLastModified age="${lastModified}"/>
                        </IfAny>
                    </IfFileName>
                </Delete>
            </DefaultRolloverStrategy>
        </RollingFile>

        <RollingFile name="CacheAppender"
                     filename="${baseDir}/apb-cache.log"
                     filepattern="${baseDir}/log/apb-cache-${dateSuffix}-%i.log.gz">
            <PatternLayout pattern="${logPattern}"/>
            <Policies>
                <TimeBasedTriggeringPolicy interval="1" modulate="true"/>
                <SizeBasedTriggeringPolicy size="${maxFileSize}"/>
                <OnStartupTriggeringPolicy />
            </Policies>
            <DefaultRolloverStrategy max="${maxCount}">
                <Delete basePath="${baseDir}" maxDepth="1">
                    <IfFileName glob="*/apb-cache-*.log">
                        <IfAny>
                            <IfAccumulatedFileSize exceeds="${accumulatedFileSize}"/>
                            <IfLastModified age="${lastModified}"/>
                        </IfAny>
                    </IfFileName>
                </Delete>
            </DefaultRolloverStrategy>
        </RollingFile>

        <Gelf name="Gelf" host="${gelfHost}" port="${gelfPort}" version="1.1" facility="eltex-apb"
              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="RollingFile"/>
            <AppenderRef ref="STDERR" level="OFF"/>
            <AppenderRef ref="Gelf" level="${gelfLevel}"/>
        </Root>

        <Logger name="org.springframework"  level="ERROR"/>
        <Logger name="org.apache"           level="ERROR"/>
        <Logger name="org.quartz"           level="ERROR"/>
        <Logger name="io.netty"             level="ERROR"/>
        <Logger name="io.grpc"              level="ERROR"/>

        <Logger name="com.hazelcast" additivity="false" level="${hazelcastLogLevel}">
            <AppenderRef ref="CacheAppender"/>
            <AppenderRef ref="RollingFile" level="ERROR"/>
            <AppenderRef ref="STDERR" level="${consoleLevel}"/>
        </Logger>

    </Loggers>
</Configuration>
  • Автоматическое перечитывание конфигурации логгера:
<Configuration status="OFF" monitorInterval="10">
  • Уровень логирования:
<Property name="rootLevel">${env:LOG_LEVEL:-INFO}</Property>
  • Базовая директория хранения логов:
<Property name="baseDir">/var/log/eltex-apb</Property>
  • Максимально допустимый размер файла (при его превышении создается новый файл. а старый архивируется):
<Property name="maxFileSize">20 MB</Property>
  • Суммарный размер логов (текущий файл + архивные). При его превышении наиболее старые файлы будут удаляться:
<Property name="accumulatedFileSize">100 MB</Property>
  • Срок хранения логов, файлы модифицированные раннее этого срока будут удаляться:
<Property name="lastModified">4d</Property>
  • Максимальное количество архивных файлов, при его превышении наиболее старые файлы будут перезаписываться:
<Property name="maxCount">7</Property>
  • Блок настройки перенаправления логов в 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>
  •    Блок настройки логирования Hazelcast
<Property name="hazelcastLogLevel">${env:HAZELCAST_LOG_LEVEL:-INFO}</Property>


Мониторинг

Для мониторинга сервиса APB поддержаны совместимые с Prometheus метрики. Для просмотра списка метрик надо открыть:

http://<адрес сервера APB>:<порт>/apb/api/metrics


Для запуска мониторинга со стороны Prometheus надо добавить в файл его конфигурации:

  - job_name: 'apb'
    metrics_path: '/apb/api/metrics'
    static_configs:
      - targets: ['<адрес сервера APB>:<порт>']

Порт соответствует рабочему порту сервера APB, по умолчанию 8090.

Так же можно просмотреть список пользователей, зарегистрированныйх на APB. Для этого надо открыть:

http://<адрес сервера APB>:<порт>/apb/api/users


Настройка подключения точек доступа к сервису APB

Подключение к сервису APB на точке доступа можно настроить через GUI EMS.

Для настройки роуминга пользователей при портальной авторизации необходимо перейти в раздел Конфигурация → Captive Portal.Global, указать адрес Roaming Service URL в формате: «<IP-aдрес_apb>:8090». IP-aдрес APB должен быть доступным из сети управления точками доступа.

Настройте «Roaming no action timeout» (время, через которое ТД удалит устаревшие/неактивные записи о клиентах в роуминге). Параметр «Roaming no action timeout» должен быть не меньше максимальной длительности тарифного плана.

Существует возможность выполнить настройку с помощью шаблона, используемого в правиле инициализации ТД.

Откройте в EMS Wireless → Менеджер шаблонов конфигурации и нажмите кнопку Добавить. В открывшемся окне выполнить настройку:

  • «Тип устройства» - «Universal»
  • «Имя шаблона» - «apb» (можно указать произвольное имя)
  • «Домен» - «root»
  • «Captive Portal. Global» - отмечаем галочкой

и нажимаем Принять.

Откроется окно редактирования шаблона - в нем нажимаем и задаем параметры:

  • «Адрес service роуминга» - адрсе сервера APB в формате «<IP-aдрес_apb>:8090»
  • «Roaming no action timeout, min» - время в мин.
  • «AP IP alias» - «redirect.loc»

После чего нажимаем кнопку Принять и в следующем окне еще раз Принять.

После этого шаблон будет сформирован и его можно будет использовать в правилах инициализаии ТД:

При создании/настройке правила инициализации для ТД необходимо отметить галочкой пункт «Использовать индивидуальный шаблон» выбрать созданный шаблон «apb__root», который будет иметь имя вида «Название шаблона__домен шаблона». При использовании данного правила для инициализации ТД, параметры подключения к серверу APB будут настроены на ТД в ходе её инициализации.


Начиная с версии ПО ТД 1.10.0 WEP/WOP-12/12 rev.C/2ac в качестве мобильного домена («User Mobility Domain») используется параметр «AP location, domain», который соответствует домену, в который была инициализирована ТД. Он задается при инициализации ТД и не требует настройки.

Так же можно выполнить его настройку во вкладке ТД Конфигурация → Сеть:

Нажимаем Редактировать:

И в открывшемся окне, нажав кнопку справа от настройки «AP location, domain», выбираем нужный домен:

Потом нажимаем Принять и еще раз Принять.

Для сохранения настроек на ТД нажимаем сверху-слева кнопку Сохранить ().

Во вкладке «Виртуальные точки доступа» необходимо открыть настраиваемый SSID и в блоке настроек Captive Portal указать «User Mobility Domain» (должен быть одинаковым для всех точек доступа, которые будут участвовать в роуминге).



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

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


version: "3"

networks:
  swlc_innernet:
    driver: bridge
    ipam:
      driver: default
      config:
        - subnet: 172.30.0.0/16

services:
  eltex-apb:
    container_name: eltex-apb
    image: ${ELTEX_HUB}/eltex-apb:${SWLC_VERSION}
    restart: unless-stopped
    deploy:
      resources:
        limits:
          memory: 1024M
    networks:
      - swlc_innernet
    ports:
      # connect with APs
      - "8090:8090/tcp"
      # Cluster
      - "5704:5704"
      - "5025:5025"
    env_file:
      - eltex-apb.env
    environment:
      # Настройки таймзоны
      - TZ=${TZ}
    volumes:
      # Конфигурирование списков
      - ./hosts.json:/etc/eltex-apb/hosts.json:ro
      - ./hosts_kassa.json:/etc/eltex-apb/hosts_kassa.json:ro
      # логи
      - ./volumes/logs/eltex-apb:/var/log/eltex-apb


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

В параметре "-Djava.rmi.server.hostname=<IP-address>" вместо <IP-address> нужно указать ip-адрес сервера, где запущен сервис.

Контейнеры могут быть сконфигурированы, путем передачи переменных окружения:

  • PORT - порт, на котором будет слушать сервис,
  • JAVA_INIT_HEAP - a.k.a. -Xms JVM опция,
  • JAVA_MAX_HEAP - a.k.a. -Xmx JVM опция,
  • DEBUG_PORT - порт для JMX,
  • JAVA_OPTS - JVM опции (может переопределить все остальные дефолтные параметры).

  • TZ - часовой пояс в формате Asia/Novosibirsk (список существующих можно посмотреть командой timedatectl list-timezones)


Для задания параметров через переменные окружения, необходимо подготовить файл .env, в котором указываются переменные окружения и их значения, например:

#Докер-регистри
ELTEX_HUB=hub.eltex-co.ru/softwlc
#Версия SoftWLC
SWLC_VERSION=1.36
#Настройка часового пояса
TZ=Asia/Novosibirsk
#Настройки логирования
LOG_LEVEL=INFO
CONSOLE_LEVEL=INFO
HAZELCAST_LOG_LEVEL=INFO


Также для запуска приложения необходимо будет создать конфигурационный файл с переменными окружения eltex-apb.env. Файл должен распологаться там же, где и docker-compose.yml

# Важно! В целях исключения перезатирания данных при обновлении не следует вносить изменения в текущий файл.
# Переопределить переменные окружения можно в файле environment-overrides/eltex-apb.env

# Размер очереди сообщений
sessionMessageQueueSize=100

# Путь к файлу белых списков
hostsFile=/etc/eltex-apb/hosts.json

# Интервал запуска задачи проверок таймаутов
pingJob.interval=60s

# Таймаут ожидания subscribe-request
pingJob.subscribeIdleTimeout=60s

# Время жизни сессии без получения сообщений
pingJob.messageIdleTimeout=90s

# Время через которое нужно отправить пинг
pingJob.pingIdleTimeout=30s

# Настройки mercury
mercury.host=eltex-mercury
mercury.port=6565
mercury.poolSize=50

# Настройка соединения с БД
jdbc.url=jdbc:mysql://${MYSQL_HOST}:${MYSQL_PORT}/eltex_apb?useUnicode=true&characterEncoding=utf8&relaxAutoCommit=true&connectTimeout=10000&socketTimeout=10000&useSSL=false
jdbc.username=${MYSQL_USER}
jdbc.password=${MYSQL_PASSWORD}
jdbc.driver=com.mysql.cj.jdbc.Driver
jdbc.maxPoolSize=16

# Настройки кэша
cache.port=5704
# Время хранения записей в кэше пользователей
cache.ttlSeconds=43200
# Предзагрузка кэша из бд на старте
cache.bootstrap.enabled=true
# Размер пачки предзагрузки пользователей
cache.bootstrap.batchSize=10000
# Период асинхронной записи в БД
cache.store.writePeriodSeconds=2
# Размер пачки для записи в БД
cache.store.writeBatchSize=200

# Настройки кластера
cluster.enabled=false
# Публичный адрес ноды
cluster.publicNodeAddress=192.168.0.1
# Размер пачки событий для публикации
cluster.notifications.publishBatchSize=50
# Период публикации событий
cluster.notifications.publishPeriodSeconds=3
# Количество потоков обрабатывающих события
cluster.notifications.processingThreads=4
# Размер пачки обрабатываемых событий
cluster.notifications.processingBatchSize=100
# Адреса членов кластера. Указываются через индекс
# cluster.members.0=192.168.0.1:5704
# cluster.members.1=192.168.0.2:5704

# Настройки очистки БД
# Период хранения устаревших записей таблицы 'users'
dbCleanJob.usersExpiredPeriodDays=90
# Интервал запуска задачи по очистке устаревших записей таблицы 'users'
dbCleanJob.cronExprToCleanUsersTable=0 0 0 15 * *

# Настройки логирования
LOG_LEVEL=${LOG_LEVEL}
CONSOLE_LEVEL=${CONSOLE_LEVEL}
HAZELCAST_LOG_LEVEL=${HAZELCAST_LOG_LEVEL}