Page tree
Skip to end of metadata
Go to start of metadata

Установка агента описана в отдельной статье: Установка агента HARD.

Общие рекомендации

  • Для наименований атрибутов и переменных использовать стиль Train-Case: слова разделять дефисом, а каждое слово писать с заглавной буквы.
    • Исключением из данного правила являются переменные, создаваемые фильтром match. Поскольку в наименованиях групп регулярных выражений запрещены дефисы, в них в качестве разделителя следует использовать подчёркивание.
  • Для наименований экземпляров фильтров использовать стиль snake_case: слова разделяют подчёркиванием и пишутся строчными буквами.
  • Избегать дублирования вычислений:
    • Повторяющиеся промежуточные вычисления выносить в фильтры, сохраняя результат преобразований в переменных;
    • Повторяющиеся проверки заменять установкой тега и дальнейшей проверкой наличия этого тега.
  • Избегать дублирования участков конфигурации, используя якори и ссылки на них.
  • Для ограничения значений и наименований параметров конфигурации (YAML-ключей) лучше использовать одиночные кавычки, а для ограничения строк в вычисляемых выражениях — двойные.
  • Наименования резервных копий конфигурационных файлов, размещённых в конфигурационной директории агента, должны иметь отличное от yml расширение. Агент при запуске загружает все файлы *.yml, которые размещены в конфигурационной директории и всех её поддиректориях.

Заполнение кэша

Отправку всех актуальных профилей и привязок оборудования из основной БД в очереди для агента HARD можно выполнить одним из способов, описанных в разделе Запрос текущего состояния.

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

При запуске собирает конфигурацию из всех файлов *.yml, которые размещены в конфигурационной директории /etc/hydra/hard/ (/etc/hydra-testing/hard-testing/ для тестового экземпляра) и всех её поддиректориях. Как правило, используется следующая структура конфигурационных файлов:

  • Файл hard.yml — общие настройки агента;
  • Файл batch.yml — настройки работы агента в режиме загрузки аккаунтинга;
  • Директория plugins:
    • Файл base.yml — фильтры и конфигурация для плагина base;
    • Файл proxy.yml — конфигурация для плагина proxy.

Значения по умолчанию всех параметров хранятся в директории установки агента. Для основного экземпляра это /opt/hydra/hard/conf/, а для тестового — /opt/hydra/hard-testing/conf/. Итоговая конфигурация формируется при запуске агента как результат наложения пользовательской (из конфигурационной директории) конфигурации на дистрибутивную (значения по умолчанию), причём для совпадающих ключей пользовательские значения имеют больший приоритет.

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

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

Пример вывода конфигурации в лог
...
10.02.2017 12:00:59. 90 136807/Master     MainThread INFO     All workers have been stopped
10.02.2017 12:00:59. 90 136807/Master     MainThread INFO     Stopped
11.02.2017 13:13:01.171 23117/MainThread       INFO
==================================================
 
11.02.2017 13:13:01.177 23117/MainThread       INFO
HARD (4.2.9.1). Configuration loaded:
  "sessions_loader":
    "bulk_size_limit": 50000,
    "plugins":
      "default":
        "sessions":
  "cache_cleaner":
    "expire_period":
      "accounting": 1440,
      "user_equip": 1440,
      "netservs": 1440
  "batch":
    "pid_path": "/var/run/hydra/hard/batch.pid",
    "mongo_pool": "main"
  "enabled_plugins": [
    "base/radius-ipoe",
    "proxy/dhcp",
    "base/dhcp-ont-mng",
    "base/dhcp-voip",
    "base/dhcp-iptv",
    "base/dhcp-internet",
    "base/dhcp-unknown"
  ],
  "log":
    "common":
...
  "plugins":
...
    "proxy":
      "main":
      "dhcp":
        "routes":
          "base/dhcp-ont-mng": "$request.RAD_REQUEST.try(\"DHCP-Relay-Circuit-Id\", \"0x00\").unhex().like?(\"^xpon 1010 GPON-H .+$\")",
          "base/dhcp-iptv": "$request.RAD_REQUEST.try(\"DHCP-Relay-Circuit-Id\", \"0x00\").unhex().like?(\"^xpon 1022 GPON-H .+$\")",
          "base/dhcp-voip": "$request.RAD_REQUEST.try(\"DHCP-Relay-Circuit-Id\", \"0x00\").unhex().like?(\"^xpon 1011 GPON-H .+$\")",
          "base/dhcp-internet": "$request.RAD_REQUEST.try(\"DHCP-Relay-Circuit-Id\", \"0x00\").unhex().like?(\"^xpon 11[0-9]2 GPON-H .+$\")"
        "default": "base/dhcp-unknown",
        "call_stack": []
11.02.2017 13:13:59.185 23123/Master     MainThread INFO     Running
11.02.2017 13:13:59.186 23123/Master     MainThread DEBUG    Handling signals
11.02.2017 13:13:59.188 23123/Master     MainThread DEBUG    Adding Worker#1, lifetime: 0.001 seconds to process pool
...

Общие настройки

Основные параметры агента HARD обычно размещаются в файле /etc/hydra/hard/hard.yml (/etc/hydra-testing/hard-testing/hard.yml для тестового экземпляра).

Список активных плагинов

Ключ enabled_plugins.

В данном ключе в виде списка перечисляются все экземпляры плагинов, которые должны использоваться агентом. Каждый экземпляр указывается в формате <plugin_name>/<plugin_instance_name>, где <plugin_name> — наименование плагина, а <plugin_instance_name> — наименование конкретного его экземпляра.

Пример списка активных плагинов: три экземпляра плагина base и один — proxy для маршрутизации запросов между ними
enabled_plugins:
  - 'proxy/dhcp'
  - 'base/dhcp-o82'
  - 'base/dhcp-ip-private'
  - 'base/dhcp-ip-public'

В целом, в конфигурации могут быть описаны и другие экземпляры плагинов. Работать будут только те, которые указаны в данном списке.

Логирование

Секции logcommon (общий лог агента) и logbatch (лог загрузчика аккаунтинга).

КлючОписание
level

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

  • error — Только критичные события: запуск и остановка агента, ошибки.
  • info — Основные события: запуск, загружаемая конфигурая, подключения к БД и очередям, полученные запросы и отправленные ответы. Рекомедуется для промышленной эксплуатации.
  • debug — Всё то же, что и в info-режиме, но с подробными сведениями о полученных из очередей сообщениях, запросах и всех этапах обработки тех и других. Рекомендуется для отладки работы агента в ходе его настройки.
pathПолный путь к лог-файлу
rotatesizeМаксимальный допустимый размер лог-файла в килобайтах. По достижении файлом указанного размера агент выполняет ротацию лога.
rotatecountКоличество хранимых лог-файлов.
Пример конфигурации логирования
...
log:
  common:
    level: 'debug'
    path: '/var/log/hydra/hard/hard.log'
    rotate:
      size: 20480
      count: 250
 
  batch:
    level: 'info'
    path: '/var/log/hydra/hard/batch.log'
    rotate:
      size: 10240
      count: 50
...

Путь к PID-файлу

Ключ pid_path.

В данном ключе указывается полный путь к файлу, в который агент при запуске запишет PID главного процесса.

Пример задания пути к PID-файлу
pid_path: '/var/run/hydra-testing/hard-testing/hard.pid'

Системные фильтры

Секция filters.

Данные фильтры используются серверными процессами агента. Наиболее важным из таких фильтров и единственным, требующим настройки является фильтр agent.basic_auth, определяющий данные для базовой HTTP-аутентификации клиента. В роли клиента, как правило, выступает модуль модуль rlm_perl FreeRADIUS — в нём для работы с агентом должны быть указаны логин и пароль из конфигурации этого агента.

КлючОписание

filtersagent.basic_authmainlogin

Логин базовой аутентификации
filtersagent.basic_authmainpasswordПароль базовой аутентификации
Пример конфигурации базовой HTTP-аутентификации клиента
...
filters:
  agent.basic_auth:
    main:
      login: 'FreeRADIUS'
      password: 'q0IkVhQf10ZKUgKYAyoE'
...

Серверные процессы агента

Секция server.

Для взаимодействия с FreeRADIUS используется клиент-серверная архитектура: агент является сервером, а модуль rlm_perl FreeRADIUS — клиентом. В данной секции задаются параметры, определяющие работу серверной части агента.

КлючОписание
addressIP-адрес сетевого интерфейса, на котором главный процесс агента должен принимать запросы
portНомер TCP-порта, на котором главный процесс агента должен принимать запросы
workersКоличество дочерних Worker-процессов агента, которые осуществляют непосредственную обработку полученных от FreeRADIUS запросов.
abort_attemptsКоличество попыток отправки дочернему процессу сигнала SIGTERM до того как завершение процесса будет выполнено принудительно посредством отправки SIGKILL.
abort_delayЗадержка в секундах между попытками отправки сигнала SIGTERM дочерним процессам.
call_stackСписок, определяющий порядок вызова системных фильтров. Как правило, не требует измений и состоит из фильтра базовой аутентификации agent.basic_auth/main, профилировщика agent.profiler/main и обработчика ошибок agent.exception_handler/main.
Пример конфигурации сервера с тремя обработчиками запросов
server:
  address: '127.0.0.1'
  port: 11080
  workers: 3

Подключение к БД кэша (MongoDB)

Секция connection_pools → mongo → <spec_name>.

В данной секции может быть описано несколько спецификаций с различными наименованиями <spec_name> для подключения агента к БД кэша. Например, одна из них может содержать параметры подключения к кластеру MongoDB Replica Set для обработки RADIUS-запросов, а другая — только к одному локальному экземпляру MongoDB для загрузки аккаунтинга в основную БД и обновления профилей и привязок оборудования в кэше.

Для работы агента HARD версии 4 рекомендуется использовать MongoDB версии 3. Установка может быть выполнена с использованием deb-пакета hydra-mongodb3 из репозитория компании Латера (deb.hydra-billing.com).

КлючОписание
hostIP-адрес или DNS-имя сервера, для подключения к отдельному экземпляру mongod.
portНомер TCP-порта, для подключения к отдельному экземпляру mongod.
nameНаименование базы данных.
user

Имя пользователя базы данных. У пользователя должны быть полные права на управления объектами БД.

passwordПароль пользователя базы данных.
replica_setnameНаименование кластера (MongoDB Replica Set)
replica_seturisСписок адресов всех участников кластера (MongoDB Replica Set) в формате <host>:<port>, где <host>IP-адрес или DNS-имя, а <port> — номер TCP-порта.
indexesНастройки управления индексами базы данных. Агент при подключении к БД автоматически проверяет наличие всех необходимых для его эффективной работы коллекций и индексов: добавляет недостающие и удаляет лишние.

Настройка агента для работы в кластерном режиме описана в отдельной статье: Кластерный режим работы.

Пример конфигурации MongoDB
systemLog:
  destination: 'file'
  path: '/var/log/hydra/mongodb3/mongod3.log'
  logAppend: true
  logRotate: 'reopen'

processManagement:
  fork: false

net:
  bindIp: '127.0.0.1'
  port: 27027
  http:
    enabled: false

security:
  authorization: 'enabled'

storage:
  dbPath: '/var/lib/hydra/mongodb3'
  directoryPerDB: true
  journal:
    enabled: true
  engine: 'wiredTiger'
  wiredTiger:
    engineConfig:
      cacheSizeGB: 1
Пример подготовки MongoDB: создание учётной записи администратора и пользователя hard
user@server:~$ mongo3 admin           # К «чистой» СУБД подключаемся без аутентификации (используется MongoDB Localhost Exception)
MongoDB shell version: 3.0.4
connecting to: 127.0.0.1:27027/admin

> // Находясь в БД admin, создаём учётную запись администратора
> db.createUser(
      {
          user: 'admin',
          pwd: 'r08gS19tZfrs51ntZEC4',
          roles: [
              {
                  role: 'root',
                  db:   'admin'
              }
          ]
      }
  );
Successfully added user: {
	"user" : "admin",
	"roles" : [
		{
			"role" : "root",
			"db" : "admin"
		}
	]
}
 
> // Авторизуемся под учётной записью администратора
> db.auth('admin', 'r08gS19tZfrs51ntZEC4');
1
 
> // Переключаемся на БД hard_cache, которая будет указана в ключе connection_pools → mongo → <spec_name> → name конфигурации агента
> use hard_cache;
switched to db hard_cache

> // Создаём в этой БД учётную запись пользователя hard, под которым будет работать агент
> db.createUser(
      {
          user: 'hard',                 // Имя пользователя - ключ connection_pools → mongo → <spec_name> → user конфигурации агента
          pwd: '56kiEh1N61GC3ga17SgD',  // Пароль пользователя - ключ connection_pools → mongo → <spec_name> → password конфигурации агента
          roles: [
              {
                  role: 'readWrite',
                  db:   'hard_cache'
              }
          ]
      }
  );
Successfully added user: {
	"user" : "hard",
	"roles" : [
		{
			"role" : "readWrite",
			"db" : "hard_cache"
		}
	]
}
Пример конфигурации подключения к БД кэша
connection_pools:
  mongo:
    # Основная спецификация для обработки RADIUS-запросов
    main:
      name: 'hard_cache'
      user: 'hard'
      password: '56kiEh1N61GC3ga17SgD'
      replica_set:
        name: 'hard_rs'
        uris:
          - '192.168.125.11:27027'
          - '192.168.125.12:27027'
          - '192.168.125.13:27027'
 
    # Локальный экземпляр для загрузки аккаунтинга и обновления кэша
    local_instance:
      name: 'hard_cache'
      user: 'hard'
      password: '56kiEh1N61GC3ga17SgD'
      host: 'localhost'
      port: 27027

Подключение к БД провижининга (Oracle)

Секция connection_pools → database → main.

В данной секции определяются параметры подключения агента к основной базе данных — провижинингу Гидры.

КлючОписание
nameНаименование (net service name) базы данных. Параметры подключения к ней описываются в файле tnsnames.ora.
userИмя пользователя базы данных (обычно AIS_RADIUS).
passwordПароль пользователя базы данных.
hydrauser

Логин пользователя Гидры для доступа к приложению RADIUS-сервер.

Такой пользователь, помимо доступа к приложению, должен обладать служебным правом:

ПравоТип доступаПриложение
RADIUS-серверЗаписьRADIUS-сервер
hydrapasswordПароль пользователя Гидры для доступа к приложению RADIUS-сервер.
Пример конфигурации подключения к основной БД
connection_pools:
  database:
    main:
      name: 'hydra'
      user: 'AIS_RADIUS'
      password: 'T7412Ph5Flzj1ApXY2SG'
      hydra:
        user: 'hard'
        password: 'aQ4kW3GP1O4LDG5WFUCI'

Синхронизация кэша с провижинингом

Секция syncer.

КлючОписание
mongo_poolНаименование спецификации подключения к БД кэша.
stomphostIP-адрес или DNS-имя сервера, для подключения к брокеру ActiveMQ по протоколу STOMP.
stompportНомер TCP-порта, для подключения к ActiveMQ.
stomploginЛогин для подключения к ActiveMQ.
stomppasswordПароль для подключения к ActiveMQ.
queuesprofilesНаименование ActiveMQ-очереди с сообщениями об изменении профилей оборудования.
queuesbindsНаименование ActiveMQ-очереди с сообщениями об изменении привязок абонентского оборудования к операторскому.
Пример настройки синхронизации кэша
syncer:
  stomp:
    host: '192.168.123.15'
    port: 61613
    login: 'hydra'
    password: 'cq48L96pV41C5l4WtiW9'
  queues:
    profiles: 'hydra_profiles'
    binds: 'hydra_equipment_binds'

Хуки

Секция hooks.

Архитектурой агента предусмотрено выполнение каких-либо дополнительных действий (хуков) при обработке запросов.

Настройка хуков описана в отдельной статье: Хуки.

Загрузка сведений о сессиях и потреблённых услугах в БД провижининга

Параметры работы агента в таком режиме рекомендуется указывать в отдельном файле: обычно это файл /etc/hydra/hard/batch.yml для основного экземпляра агента и /etc/hydra-testing/hard-testing/batch.yml — для тестового.

КлючОписание
batchmongo_poolНаименование спецификации подключения к БД кэша.
batchpid_pathПолный путь к файлу, в который агент запишет PID процесса загрузки аккаунтинга.
sessions_loaderbulk_size_limitЗагрузка данных выполняется порционно. Данный параметр ограничивает количество сессий в одной порции.
Работа загрузчика аккаунтинга описана в подразделе Плагины → Плагин base → Загрузка сведений о сессиях в БД Гидры.
  • No labels