Описание

Модуль 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

# cache config file path
cacheConfigFile = /etc/eltex-apb/ehcache.xml

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

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

mercury {
  host = localhost
  port = 6565
  poolSize = 50
}

Расположение необходимых файлов:

# cache config file path
cacheConfigFile = /etc/eltex-apb/ehcache.xml

# 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

/etc/eltex-apb/ehcache.xml

Содержит системные настройки хранения данных о Wi-Fi-пользователях, подключенных на портале. При необходимости название и расположение файла может быть изменено в /etc/eltex-apb/application.conf .

<ehcache xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:noNamespaceSchemaLocation="http://www.ehcache.org/ehcache.xsd" updateCheck="false" monitoring="autodetect"
         dynamicConfig="true">

    <!--cacheManagerPeerProviderFactory
            class="net.sf.ehcache.distribution.RMICacheManagerPeerProviderFactory"
            properties="peerDiscovery=manual,rmiUrls=//192.168.26.179:40001/users"/-->

    <!--cacheManagerPeerListenerFactory
            class="net.sf.ehcache.distribution.RMICacheManagerPeerListenerFactory"
            properties="hostName=192.168.26.205, port=40001, socketTimeoutMillis=2000"/-->

    <defaultCache
            maxEntriesLocalHeap="10000"
            eternal="false"
            timeToLiveSeconds="8600"
            timeToIdleSeconds="120"
            maxEntriesLocalDisk="10000000"
            diskExpiryThreadIntervalSeconds="120"
            memoryStoreEvictionPolicy="LRU">
        <pinning store="inCache" />
        <persistence strategy="localTempSwap"/>
    </defaultCache>

    <cache name="users"
           maxBytesLocalHeap="1G"
           eternal="false"
           timeToLiveSeconds="43200"
           memoryStoreEvictionPolicy="LRU">
        <pinning store="inCache" />
        <persistence strategy="none"/>

        <!--cacheEventListenerFactory
                class="net.sf.ehcache.distribution.RMICacheReplicatorFactory"
                properties="replicateAsynchronously=true, replicatePuts=true, replicateUpdates=true,
                                                            replicateUpdatesViaCopy=false, replicateRemovals=true "/-->
    </cache>

    <cache name="hosts" maxBytesLocalHeap="128M" eternal="true">
        <persistence strategy="none"/>
    </cache>

</ehcache>

Количество оперативной памяти, выделяемое для хранения таблицы авторизованных пользователей настраивается параметром "maxBytesLocalHeap" в разделе:

  <cache name="users"
           maxBytesLocalHeap="1G"
           eternal="false"
           timeToLiveSeconds="43200"
           memoryStoreEvictionPolicy="LRU">
           . . .
    </cache>

Количество оперативной памяти, выделяемое для хранения таблицы с белыми списками настраивается параметром "maxBytesLocalHeap" в разделе:

    <cache name="hosts" maxBytesLocalHeap="128M" eternal="true">
        <persistence strategy="none"/>
    </cache>

/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="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="net.sf.ehcache" additivity="false">
            <AppenderRef ref="CacheAppender"    level="DEBUG"/>
            <AppenderRef ref="RollingFile"      level="ERROR"/>
        </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>

Мониторинг

Для мониторинга сервиса 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 должен быть доступным из сети управления точками доступа.

Eltex Documentation > v1.35_APB > image2019-10-5_15-25-6.png

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

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

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

Eltex Documentation > v1.35_APB > image2021-4-14_11-30-45.png

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

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

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

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

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

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

Eltex Documentation > v1.35_APB > image2021-4-14_11-44-58.png При создании/настройке правила инициализации для ТД необходимо отметить галочкой пункт «Использовать индивидуальный шаблон» выбрать созданный шаблон «apb__root», который будет иметь имя вида «Название шаблона__домен шаблона». При использовании данного правила для инициализации ТД, параметры подключения к серверу APB будут настроены на ТД в ходе её инициализации.

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

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

Eltex Documentation > v1.35_APB > image2021-4-14_11-16-6.png

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

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

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

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

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

Eltex Documentation > v1.35_APB > image2019-5-13_10-28-19.png

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

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

На данный момент конфигурирование сервиса происходит через маппинг настроек сервиса, запущенного ранее в deb-пакете.

version: "2.4"

volumes:
  softwlc_logs:
    driver: local

services:
  apb:
    container_name: apb
    image: hub.eltex-co.ru/softwlc/eltex-apb:1.21-<tag>
    ports:
      - 8090:8090
      - 8092:8092
    volumes:
      - "/etc/eltex-apb:/etc/eltex-apb"
      - "softwlc_logs:/var/log"
    environment:
      - "JAVA_OPTS=-Dcom.sun.management.jmxremote -Dcom.sun.management.jmxremote.port=8092 -Dcom.sun.management.jmxremote.rmi.port=8092 -Dcom.sun.management.jmxremote.ssl=false -Dcom.sun.management.jmxremote.authenticate=false -Dcom.sun.management.jmxremote.local.only=false -Djava.rmi.server.hostname=<IP-address>"
      - TZ=${TZ}

Вместо <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, в котором указываются переменные окружения и их значения, например:

PORT=8090
JAVA_INIT_HEAP=128m
JAVA_MAX_HEAP=2048m
DEBUG_PORT=8092
JAVA_OPTS=-Dcom.sun.management.jmxremote -Dcom.sun.management.jmxremote.ssl=false -Dcom.sun.management.jmxremote.authenticate=false -Dcom.sun.management.jmxremote.local.only=false -Djava.rmi.server.hostname=<IP-address>
#Настройка часового пояса
TZ=Asia/Novosibirsk

В таком случае блок "environment" будет записан следующим образом:

    environment:
      - JAVA_OPTS=${JAVA_OPTS}
      - PORT=${PORT}
      - JAVA_INIT_HEAP=${JAVA_INIT_HEAP}
      - JAVA_MAX_HEAP=${JAVA_MAX_HEAP}
      - DEBUG_PORT=${DEBUG_PORT}

Файл переменных окружения .env должен находиться в одной папке с docker-compose.yml