Описание

Сервис Eltex Polly предоставляет приложение для создания опросов на веб-портале при подключении hotspot-пользователей в схемах с ТД и BRAS.

Для демонстрации опроса сервис предоставляет web-интерфейс. Опрос представляет собой набор вопросов с вариантам ответов. Данные о пройденных опросах сохраняются в базе для последующего сбора статистики.

Управление опросами происходит в интерфейсе Конструктора порталов, настройки доступа к нему указываются в свойствах соответствующей роли в Личном кабинете.

Возможны две схемы работы сервиса Polly: с применением реверсного прокси, либо без него.

В первом случае перед порталом и Конструктором порталов необходимо установить nginx, который будет проксировать трафик к сервису Polly.

Во втором случае понадобятся дополнительные настройки точек доступа, а также понадобится открыть дополнительный порт в ядро SoftWLC из клиентской сети.

Схема с проксированием используется тогда, когда необходимо сохранить изоляцию контура ядра SoftWLC от клиентского трафика.

Рекомендуется схема работы с применением реверсного прокси nginx.

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

Установка

Для работы сервиса необходима установка схемы на сервер БД:

apt install eltex-polly-db

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

apt install eltex-polly

Остановка/запуск сервиса

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

/etc/eltex-polly/application.conf

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

access {
  secret = password
}

database {
  host = localhost
  port = 3306
  name = eltex_poll
  user = javauser
  password = javapassword

  pool {
    # Time to wait for a connection
    connectionTimeout = 10s
    # Time to wait for connection validation
    validationTimeout = 3s

    min = 1
    max = 5
  }

  cache {
    enabled = true
    expireAfterWrite = 3m
    maximumSize = 500
  }

  resources {
    readChunkSize = 256k
    writeChunkSize = 256k
  }
}

images {
  maxSize = 15MB
  cache {
    expireAfterWrite = 30s
    storagePath = /tmp/eltex-polly/cache/
  }
}

• Секретный ключ для доступа:

access {
  secret = password
}

• Основные параметры для подключения к БД:

database {
  host = localhost            IP-адрес БД
  port = 3306                 Порт обращения к БД
  name = eltex_poll           Название БД
  user = javauser             Имя пользователя
  password = javapassword     Пароль
...

• Настройка пула подключений к БД:

  pool {
    # Time to wait for a connection
    connectionTimeout = 10s                      Время ожидания подключения к БД
    # Time to wait for connection validation    
    validationTimeout = 3s                       Время ожидания валидации

    min = 1                                      Минимальное количество подключений к БД
    max = 5                                      Максимальное количество подключений к БД
  }

• Настройки кэша:

  cache {
    enabled = true           Активация записи
    expireAfterWrite = 3m    Время хранения
    maximumSize = 500        Максимальный размер
  }

• Настройка количества данных для чтения и записи:

  resources {
    readChunkSize = 256k
    writeChunkSize = 256k
  }

• Настройка изображений:

images {
  maxSize = 15MB                             Максимальный размер загружаемого изображения
  cache {
    expireAfterWrite = 30s
    storagePath = /tmp/eltex-polly/cache/
  }
}

/etc/default/eltex-polly

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

# Eltex-Polly daemon parameters

# HTTP Port for use by Eltex Polly
HTTP_PORT=9089
GRPC_PORT=9088

# Initial size of Java heap
JAVA_INIT_HEAP=16m
# Maximum size of Java heap
JAVA_MAX_HEAP=128m

# Additional arguments to pass to java
JAVA_OPTS="-XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/var/log/eltex-polly"

• Порты для работы сервиса:

# HTTP Port for use by Eltex Polly
HTTP_PORT=9089
GRPC_PORT=9088

• Количество памяти, выделяемое приложению при старте сервиса:

# Initial size of Java heap
JAVA_INIT_HEAP=16m

• Максимальное количество памяти, которое может арендовать сервис:

# Maximum size of Java heap
JAVA_MAX_HEAP=256m

• Дополнительные опции запуска java:

# Additional arguments to pass to java
JAVA_OPTS="-XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/var/log/eltex-polly"

/etc/eltex-polly/log4j2.xml

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

<?xml version="1.0" encoding="UTF-8"?>

<Configuration monitorInterval="10">

    <Properties>
        <Property name="rootLevel">${env:LOG_LEVEL:-ERROR}</Property>

        <Property name="baseDir">/var/log/eltex-polly</Property>
        <Property name="maxFileSize">20 MB</Property>
        <Property name="accumulatedFileSize">10 GB</Property>
        <Property name="lastModified">4d</Property>
        <Property name="maxCount">20</Property>
        <Property name="logPattern">%d{ISO8601} [%t] %-5p %logger{12} %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}/polly.log"
                     filePattern="${baseDir}/log/polly-%i.log.gz">
            <PatternLayout pattern="${logPattern}"/>
            <Policies>
                <SizeBasedTriggeringPolicy size="${maxFileSize}"/>
                <OnStartupTriggeringPolicy />
            </Policies>
            <DefaultRolloverStrategy max="${maxCount}">
                <Delete basePath="${baseDir}" maxDepth="3">
                    <IfFileName glob="*/polly-*.log.gz">
                        <IfAny>
                            <IfAccumulatedFileSize exceeds="${accumulatedFileSize}" />
                            <IfLastModified age="${lastModified}" />
                        </IfAny>
                    </IfFileName>
                </Delete>
            </DefaultRolloverStrategy>
        </RollingFile>

        <Gelf name="Gelf" host="${gelfHost}" port="${gelfPort}" version="1.1" facility="eltex-polly"
              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{12}" />
            <Field name="location" pattern="%C{1}.%M(line:%L)" />
        </Gelf>

    </Appenders>

    <Loggers>
        <Root level="${rootLevel}">
            <AppenderRef ref="RollingFile"/>
            <AppenderRef ref="STDERR" level="${consoleLevel}"/>
            <AppenderRef ref="Gelf" level="${gelfLevel}"/>
        </Root>

        <!--SQL logger-->
        <Logger name="org.jooq.tools.LoggerListener" level="OFF"/>

        <Logger name="org.springframework" level="ERROR"/>
        <Logger name="org.hibernate"       level="ERROR"/>
        <Logger name="com.zaxxer.hikari"   level="ERROR"/>
        <Logger name="io.netty"            level="ERROR"/>
        <Logger name="io.grpc"             level="ERROR"/>

        <!--Disabled loggers-->
        <Logger name="org.apache"          level="OFF"/>
    </Loggers>

</Configuration>

• Интервал автоматического перечитывания конфигурации логгера:

<Configuration monitorInterval="10">

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

<Property name="rootLevel">${env:LOG_LEVEL:-ERROR}</Property>

• Базовая директория хранения логов:

<Property name="baseDir">/var/log/eltex-polly</Property>

• Максимально допустимый размер файла (при его превышении создается новый файл, а старый архивируется):

<Property name="maxFileSize">20 MB</Property>

• Суммарный размер логов (текущий файл + архивные). При его превышении наиболее старые файлы будут удаляться:

<Property name="accumulatedFileSize">10 GB</Property>

• Срок хранения логов, файлы модифицированные раннее этого срока будут удаляться:

<Property name="lastModified">4d</Property>

• Максимальное количество архивных файлов, при его превышении наиболее старые файлы будут перезаписываться:

<Property name="maxCount">20</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>

Взаимодействие с другими сервисами

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

Ниже представлена конфигурация nginx. 

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

В случае необходимости следует изменить адреса и порты в конфигурационном файле. 

Если eltex-portal и eltex-portal-constructor установлены на разных хостах, то nginx необходимо установить на каждом из них и настроить соответствующие location.

server {
    listen 8080;
    listen [::]:8080;

    gzip off;

	proxy_cache_background_update on;
	proxy_cache_use_stale error timeout updating http_500 http_502 http_503 http_504;
    proxy_cache_revalidate on;
    proxy_cache_min_uses 2;

    client_max_body_size 25m;

    proxy_set_header Host $http_host;
    proxy_set_header X-Forwarded-Host $host;
    proxy_set_header X-Forwarded-Server $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Real-IP $remote_addr;

    
    # Eltex Portal section
    location ~* /eltex_portal/(gif|jpeg|jpg|png|svg|js|css|fonts)/ {
        proxy_cache eltex_cache;
        proxy_ignore_headers Cache-Control Expires;
        proxy_cache_valid any 1h;
        # адрес eltex portal
        proxy_pass http://127.0.0.1:9000;

    }

    location ~* /eltex_portal/(portal/download/shared/[0-9]+|img/) {
        proxy_cache eltex_cache;
        proxy_ignore_headers Cache-Control Expires;
        proxy_cache_valid 404 302 304 5m;
        proxy_cache_valid any 24h;
        # адрес eltex portal
        proxy_pass http://127.0.0.1:9000;
    }

    location ~* /eltex_portal/(portal/download/private|portal)/ {
        proxy_cache eltex_cache;
        proxy_ignore_headers Cache-Control Expires;
        proxy_cache_valid 404 302 304 5m;
        proxy_cache_valid any 1h;
        # адрес eltex portal
        proxy_pass http://127.0.0.1:9000;
    }

    location /eltex_portal/ {
        proxy_pass http://127.0.0.1:9000;
    }

    location /eltex_portal/polly {
        rewrite ^(/eltex_portal)/(.*)$ /$2 break;
        proxy_cookie_path /polly /eltex_portal/polly;
		# адрес eltex polly
        proxy_pass http://127.0.0.1:9089;
    }

    # Eltex Portal Constructor section
    location ~* /epadmin/(portal/download/[0-9]+|portal/download/shared/[0-9]+|font-awesome|img|js|css) {
        proxy_cache eltex_cache;
        proxy_cache_valid any 24h;
        # адрес eltex portal constructor
        proxy_pass http://127.0.0.1:9001;
    }

    location /epadmin {
        proxy_pass http://127.0.0.1:9001;
    }

    location /ep-demo {
        proxy_pass http://127.0.0.1:9001;
    }

    location /epadmin/polly {
        rewrite ^(/epadmin)/(.*)$ /$2 break;
        proxy_cookie_path /polly /epadmin/polly;
		# адрес eltex polly
        proxy_pass http://127.0.0.1:9089;
    }


    location / { 
        deny all; 
    }
}

Настройка доступа к сервису опросов в Конструкторе порталов

Необходимо включить интеграцию с сервисом опросов в системных настройках Конструктора порталов:

Здесь указываются настройки подключения к сервису опросов и общие настройки опросов.

Если используется схема с реверсным прокси nginx, то необходимо установить флаг "Включить сквозной прокси". В данном случае поле HTTP URL блокируется.

Если используется схема без реверсного прокси nginx, то необходимо снять флаг "Включить сквозной прокси", в поле HTTP URL ввести адрес вида http://<ip_address>:<port>, где ip_address это адрес сервера, на котором установлен сервис eltex_polly, а port это порт, соответствующий параметру HTTP_PORT конфигурационного файла /etc/defaut/eltex-polly.

Параметр GRPC хост определяет адрес сервера, на котором установлен сервис eltex-polly. 

Параметр GRPC порт определяет порт, соответствующий параметру GRPC_PORT конфигурационного файла /etc/defaut/eltex-polly.

Параметр Секретный ключ соответствует параметру secret основного файла конфигурации /etc/eltex-polly/application.conf.

Управление опросами в Конструкторе порталов

Для управления опросами нужно зайти в Конструктор порталов и выбрать необходимый портал.

В разделе Опросы доступен интерфейс для управления опросами:

В левой части указаны опросы, привязанные к выбранному порталу, в правой части указаны все опросы, доступные для управления.

Создание опроса

Для создания опроса необходимо нажать на кнопку Создать опрос.

В открывшемся редакторе указываются следующие настройки:

• Название - название опроса.
• Домен - домен опроса. При редактировании существующего опроса данный параметр изменять нельзя. Домен опроса должен быть в том же домене, что и портал, либо в его поддомене. 
• Язык - определяет языковую видимость опроса, а также локализацию надписей в web-интерфейсе. При редактировании существующего опроса данный параметр изменять нельзя.
• Приветствие на начальной странице - текст, который будет показан пользователю перед прохождением опроса. Если оставить поле пустым, страница приветствия отображаться не будет.

Возможные типы вопросов:

• Один из списка: выбор одного варианта ответа из предложенных.
• Один из списка (радио): выбор одного варианта ответа из предложенных в виде радио-кнопок с возможностью ввода собственного варианта ответа.
• Несколько из списка: выбор нескольких (в том числе всех) вариантов из предложенных с возможностью ввода собственного варианта ответа.
• Текст: ввод произвольного текста.
• Шкала: выставление оценки. Классический пример: "Оцените качество обслуживания" со шкалой оценок от 1 до 10.
• Один из списка (изображение): выбор одного изображения из предложенных
• Несколько из списка (изображение): выбор нескольких (в том числе всех) изображений из предложенных

Каждый вопрос может быть обязательным, для этого необходимо установить соответствующий флаг. Если вопрос помечен как обязательный, то пользователь обязан дать на него ответ, прежде чем сможет перейти к следующему вопросу. Чтобы подтвердить отправку результатов, все обязательные вопросы должны быть отвечены. Необязательные вопросы можно пропускать.

Сервис поддерживает использование изображений в вопросах. Поддерживаются следующие форматы изображений:

• PNG
• JPEG
• GIF
• SVG

Максимальный размер загружаемого изображения задаётся в конфигурационном файле в параметре maxSize секции images.

Просмотр опроса

На всех этапах работы с  опросами доступен предварительный просмотр опросов. Нажатие на кнопку Просмотр открывает предварительный просмотр опроса в том виде, в котором его увидит пользователь:

Просмотр статистики

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

Статистика ответов на вопросы типов один из списка, один из списка (радио), несколько из списка отображается в виде круговой диаграммы. В легенде отображается не более 7 вариантов ответа. Если вариантов больше, то в легенду добавляется пагинация.

Если на вопрос можно дать собственный ответ, то эти ответы буду выведены в отдельный сектор (их количество будет учтено), а сами ответы будут приведены в отдельном списке под диаграммой:

Статистика ответов на вопросы с изображениями отображается в виде круговой диаграммы. В центре круговой диаграммы отображается изображение, соответствующее выбранному сектору. Чтобы открыть изображение в полном размере, необходимо щёлкнуть по нему.

Статистика ответов на вопросы типа текст отображается в виде обычного списка:

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

Есть возможность сбросить результаты статистики опроса, за это отвечает кнопка Сбросить.

Возможен экспорт статистики в формат CSV, за это отвечает кнопка Экспорт.

Настройка опросов в схеме с ТД

С применением nginx

Настройка работы опросов в схеме с применением реверсного прокси nginx состоит из следующих шагов:

1. Перейти в Личный кабинет
2. Перейти в меню Сервисы и тарифы → Тарифы, выбрать фильтр Точки Доступа, создать новый тарифный план, либо отредактировать существующий
   

3. В качестве первого сценария необходимо указать URL-адрес в виде http://<portal-ip-address>:<portal_port>/eltex_portal/poll-redirect. Дальнейшие сценарии можно задать в стандартном виде (например, доступ в интернет в сценарии 2 в течение 1 минуты, третий сценарий - возврат на портал и повторная авторизация клиента).
   

   Для корректной работы в тарифе должны присутствовать не менее двух сценариев

4. Убедиться, что на всех точка доступа домена указан AP Alias.
   
   Параметр должен быть одинаковым на всех точках платформы. Настройку можно выполнить непосредственно на ТД, через групповые операции или при помощи правила инициализации ТД.
5. Зайти в Конструктор порталов, выбрать необходимый портал. В разделе меню Тарифы выбрать созданный тарифный план, задать название тарифа на портале, сохранить изменения.
6. Перейти в раздел меню Опросы, создать необходимый опрос, привязать его к порталу.
7. После аутентификации на портале пользователь будет перенаправлен на сервис опросов, если в базе для него найдётся подходящий опрос по языку, домену, расписанию, и если он ещё не проходил данный опрос.

Без применения nginx

Настройка работы опросов в схеме без применения реверсного прокси nginx состоит из следующих шагов:

1. Перейти в Личный кабинет
2. Перейти в меню Сервисы и тарифы → Тарифы, выбрать фильтр Точки Доступа, создать новый тарифный план, либо отредактировать существующий
   

3. В качестве первого сценария необходимо указать URL-адрес в виде http://<portal-ip-address>:<portal_port>/eltex_portal/poll-redirect, в список разрешённых хостов добавить адрес серевера, на котором установлен сервис eltex-polly. Дальнейшие сценарии можно задать в стандартном виде (например, доступ в интернет в сценарии 2 в течение 1 минуты, третий сценарий - возврат на портал и повторная авторизация клиента).
   

   Для корректной работы в тарифе должны присутствовать не менее двух сценариев

4. Убедиться, что на всех точка доступа домена указан AP Alias.
   
   Параметр должен быть одинаковым на всех точках платформы. Настройку можно выполнить непосредственно на ТД, через групповые операции или при помощи правила инициализации ТД.
5. На всех точках доступа домена изменить параметр Additional HTTP Port на тот, на котором работает сервис eltex-polly (по умолчанию 9089)
   
   Параметр должен быть одинаковым на всех точках платформы. Настройку можно выполнить непосредственно на ТД, через групповые операции или при помощи правила инициализации ТД.
6. На всей сети необходимо открыть порт, на котором работает сервис eltex-polly (по умолчанию 9089) со стороны клиентской сети в сторону сервера, на котором запущен сервис eltex-polly.
7. Зайти в Конструктор порталов, выбрать необходимый портал. В разделе меню Тарифы выбрать созданный тарифный план, задать название тарифа на портале, сохранить изменения.
8. Перейти в раздел меню Опросы, создать необходимый опрос, привязать его к порталу.
9. После аутентификации на портале пользователь будет перенаправлен на сервис опросов, если в базе для него найдётся подходящий опрос по языку, домену, расписанию, и если он ещё не проходил данный опрос.

Настройка опросов в схеме с BRAS

Настройка работы опросов происходит по аналогии с настройкой интеграции с рекламной площадкой HotWiFi.

1. Перейти в Личный кабинет

2. Зайти в меню Настройки PCRF → Списки URL, создать список polly.
   Список должен содержать адрес портала и URL для корректной работы AndroidConnectivityManager. Если есть корректно настроенный и работающий список для рекламной площадки Hot-WiFi, то можно использовать его вместо создания нового списка.
   

    Пример списка

   URL:
   http://100.111.40.100:8080/eltex_portal/
   http://connectivitycheck.gstatic.com/generate_204/
   https://connectivitycheck.gstatic.com/generate_204/

3. Перейти в меню Сервисы и тарифы → Сервисы PCRF, создать сервис polly (любое имя)
   Действие по умолчанию: redirect
   URL по умолчанию: http://<portal-ip-address>:<portal_port>/eltex_portal/poll-redirect
   Фильтр 
   Действие: permit
   Имя фильтра: polly
   
   
4. Перейти в меню Сервисы и тарифы  → Тарифы, выбрать фильтр PCRF/BRAS,  создать тарифный план Polly  с сервисом polly
   
   
5. Перейти в Конструктор порталов
6. Создать портал, перейти на вкладку Тарифы → Тарифы для BRAS (реклама, опросы)
7. Назначить соответствующие тарифы:
   1. Тариф для опросов: выбрать тариф, созданный в п. 4 
   2. Рекламный тариф BRAS: выбрать тариф для рекламы при необходимости
   3. Рабочий тариф BRAS: любой тариф, который будет применён после опросов и рекламы
      
      
8. Перейти в раздел меню Опросы, создать необходимый опрос, привязать его к порталу.
9. После аутентификации на портале пользователь будет перенаправлен на сервис опросов, если в базе для него найдётся подходящий опрос по языку, домену, расписанию, и если он ещё не проходил данный опрос.