SER Модуль usrloc


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


Соответствие контактной информации и пользователей.

То как проверяется на соответствие Контактная информация определенному пользователю (поле Contact) (тоже самое, что адрес записи: AOR - Address of Record) - является важным аспектом в работе модуля usrloc, особенно в контексте работы через NAT маршрутизаторы - где усложняется задача точного соответствия записи конкретному абоненту. Например, контактная информация разных телефонов пользователей внутренней сети может пересекаться (если они находятся в сети с NAT маршрутизатором с одинаковой конфигурацией) или контактная информация при перерегистрации одного и того же телефона может быть расценена, как регистрация нового телефона (при различных путях прохождения, через NAT маршрутизатор, например, когда назначается разный IP адрес).

В SIP RFC3261 опубликован соответствующий алгоритм для этих целей. Его работа базируется на использовании только строки из поля contact с callid и на дополнительной проверке номера в параметре cseq (если callid - один и тот же, параметр cseq должен иметь большее значение, иначе это значение неправильное). Но, как уже было описано выше, этой проверки недостаточно при работе с клиентами за NAT, таким образом, реализация проверки контактной информации в сервере OpenSER предлагает больше количество алгоритмов:

  • contact based only - строго соответствует RFC3261 - проверяется соответствие строки contact и производиться дополнительная проверка calid и cseq (если callid - одинаков, то параметр cseq должен иметь большее значение, иначе значение считается неправильным).

  • contact and callid based - это расширенный вариант для первого случая. С полем contact и callid производиться построчное сравнение; в cseq, должно быть значение большее, чем было ранее - итак, в этом случае нужно быть особо осторожным при обработке повторной передачи SIP сообщения REGISTER.

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


Зависимости от других модулей.


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

  • Необязательно: любой из модулей для интерфейса с базой данных (на данный момент: mysql, postgres, dbtext)


Зависимости от внешних библиотек и приложений.


Следующие библиотеки или приложения должны быть установлены перед использованием OpenSER с этим модулем:

Нет.


Экспортируемые параметры.


nat_bflag (integer)

Индекс branch флага, который будет использоваться как NAT маркер (если соотв. контактная информация указывает на клиента за NAT). Это branch флаг, он будет импортирован и используется всеми другими модулями, которые зависят от usrloc.

По умолчанию: "not set".

Пример использования параметра nat_bflag:
...
modparam("usrloc", "nat_bflag", 3)
...


user_column (string)

Название столбца, содержащего имена пользователей.

По умолчанию: "username".

Пример использования параметра user_column:
...
modparam("usrloc", "user_column", "username")
...


domain_column (string)

Название столбца, содержащего название доменов.

По умолчанию: "domain".

Пример использования параметра domain_column:
...
modparam("usrloc", "domain_column", "domain")
...


contact_column (string)

Название столбца, содержащего contact.

По умолчанию: "contact".

Пример использования параметра contact_column:
...
modparam("usrloc", "contact_column", "contact")
...


expires_column (string)

Название столбца, содержащего значение для expire (время жизни записи).

По умолчанию: "expires".

Пример использования параметра expires_column:
...
modparam("usrloc", "expires_column", "expires")
...


q_column (string)

Название столбца, содержащего значение для параметра "q".

По умолчанию: "q".

Пример использования параметра q_column:
...
modparam("usrloc", "q_column", "q")
...


callid_column (string)

Название столбца, содержащего значение callid.

По умолчанию: "callid".

Пример использования параметра callid_column:
...
modparam("usrloc", "callid_column", "callid")
...


cseq_column (string)

Название столбца, содержащего номер последнего cseq.

По умолчанию: "cseq".

Пример использования параметра cseq_column:
...
modparam("usrloc", "cseq_column", "cseq")
...


methods_column (string)

Название столбца, содержащего значение поддерживаемого метода.

По умолчанию: "methods".

Пример использования параметра methods_column:
...
modparam("usrloc", "methods_column", "methods")
...


flags_column (string)

Название столбца, для хранения внутренних флагов для записи.

По умолчанию: "flags".

Пример использования параметра flags_column:
...
modparam("usrloc", "flags_column", "flags")
...


cflags_column (string)

Название столбца, для хранения branch/contact флагов для записи.

По умолчанию: "cflags".

Пример использования параметра cflags_column:
...
modparam("usrloc", "cflags_column", "cflags")
...


user_agent_column (string)

Название столбца, содержащего значение поля user-agent.

По умолчанию: "user_agent".

Пример использования параметра user_agent_column:
...
modparam("usrloc", "user_agent_column", "user_agent")
...


received_column (string)

Название столбца, содержащего IP адрес источника, номер порта и протокол из сообщения REGISTER.

По умолчанию: "received".

Пример использования параметра received_column:
...
modparam("usrloc", "received_column", "received")
...


socket_column (string)

Название столбца, содержащего информацию принятой из сокета (IP адрес:port), для сообщения REGISTER.

По умолчанию: "socket".

Пример использования параметра socket_column:
...
modparam("usrloc", "socket_column", "socket")
...


path_column (string)

Название столбца, содержащего значение заголовка "Path".

По умолчанию: "path".

Пример использования параметра path_column:
...
modparam("usrloc", "path_column", "path")
...


use_domain (integer)

Если включено, то доменная часть поля имени пользователя также должна сохраняться для каждого из пользователей для их идентификации. Используется при многодоменной конфигурации. Не нулевое значение - подразумевает true.

По умолчанию: "0 (false)".

Пример использования параметра use_domain:
...
modparam("usrloc", "use_domain", 1)
...


desc_time_order (integer)

Если включено - контактная информация для пользователей должна быть упорядочена по отметкам времени (timestamp ordered); иначе она упорядочивается на основании значения параметра "q". Не нулевое значение - подразумевает true.

По умолчанию: "0 (false)".

Пример использования параметра desc_time_order:
...
modparam("usrloc", "desc_time_order", 1)
...


timer_interval (integer)

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

По умолчанию: 60.

Пример использования параметра timer_interval:
...
modparam("usrloc", "timer_interval", 120)
...


db_url (string)

URL для доступа к базе данных, которая будет использоваться.

По умолчанию: "mysql://openser:openserrw@localhost/openser".

Пример использования параметра db_url:
...
modparam("usrloc", "db_url", "mysql://username:password@localhost/openser")
...


db_mode (integer)

модуль usrloc может использовать базу данных, как постоянное хранилище контактной информации пользователей. Если Вы будете использовать базу данных, тогда ваша контактная информация переживет рестарты сервера и сбои в его работе. Однако, тут есть недостаток, заключающийся в том, что доступ к базе данных может требовать много ресурсов. Поэтому в модуле usrloc реализованы четыре режима доступа к базе данных:

  • 0 - Использование базы данных полностью отключено. Используется только память. Контактная информация будет теряться при рестартах. Используйте этот режим, если Вам нужно максимальная производительность модуля usrloc, а в постоянном хранилище для контактной информации нет необходимости или оно реализовано другими средствами.

  • 1 - Схема со сквозной записью (Write-Through). Все изменения в usrloc немедленно отражаются и в базе данных. Это очень медленный, но очень надежный вариант. Используйте эту схему, если скорость не является приоритетной задачей, но нужна гарантия того, что при аварийной остановке или перезагрузке, не будут потеряны данные контактов зарегистрированных пользователей.

  • 2 - Схема с отложенной записью (Write-Back). Является комбинацией предыдущих двух вариантов. Все изменения будут отражаться в памяти, а синхронизация с базой данных производиться по таймеру. При срабатывании таймера удаляются все контакты с истекшим сроком годности и сохраняются в базе все измененные или новые записи c контактной информацией. Используйте эту схему, если Вы сталкиваетесь со случаями пиковых нагрузок и хотите, чтобы эти ситуации обрабатывались с максимально возможной скоростью. Использование этого режима не поможет в том случае, если загрузка высокая все время. Кроме того, задержки в обработке данных в этом режиме намного меньше, чем в варианте 1, но немного больше, чем в варианте 0.

  • 3 - Схема с использованием только базы данных (DB-Only). Не производиться никакого кеширования данных в памяти, все операции выполняются напрямую с базой данных. По таймеру удаляются все контакты с истекшим сроком годности прямо из базы данных - производиться зачистка за клиентами, которые не убрали регистрацию или не перерегистрировались. Этот режим полезен, когда Вы используете несколько серверов, которые совместно используют одну базу данных, без какой-либо репликации на SIP уровне. В этом режиме обработка данных может быть медленной из-за большого числа операции с базой данных. Например, периодический пинг NAT клиентов - создает хорошую нагрузку, т.к. для каждого цикла пингования, загружается вся контактная информация для NAT клиентов из базы данных; отсутствие кеширования также выключает возможность онлайн отслеживания состояния клиентов (не будет работать с модулем pa - "Presence"), и не работает экспорт статистики.

exclaimВ случае отказа сервера или рестарта контактная информация, которая находятся только в памяти, и не была сохранена в базе, будет потеряна! Если Вы хотите минимизировать этот риск, используйте более короткий интервал для срабатывания таймера.

По умолчанию: 0

Пример использования параметра db_mode:
...
modparam("usrloc", "db_mode", 2)
...


matching_mode (integer)

Какой из алгоритмов сравнения контактной информации будет использоваться. Смотри описание этих алгоритмов выше.

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

  • 0 - Алгоритм сравнения на основе ТОЛЬКО поля CONTACT.
  • 1 - Алгоритм сравнения на основе полей CONTACT и CALLID.

По умолчанию: 0 (CONTACT_ONLY).

Пример использования параметра matching_mode:
...
modparam("usrloc", "matching_mode", 1)
...


cseq_delay (integer)

Задержка (в секундах) для обеспечения правильной обработки повторных передач запросов на регистрацию с одинаковыми полями Call-ID и Cseq. Задержка начинает отсчитываться с момента приема первого запроса на регистрацию с определенными Call-ID и Cseq.

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

Значение 0 - выключает алгоритм обнаружение повторных передач.

По умолчанию: "20 секунд".

Пример использования параметра cseq_delay:
...
modparam("usrloc", "cseq_delay", 5)
...


fetch_rows (integer)

Количество записей, которые будут выбраны за один раз из базы данных, при загрузке записей с контактной информацией. Это значение может использоваться для настройки времени загрузки этих записей при старте сервера. Для размера выделенной внутренней памяти в 1MB (по умолчанию) значение этого параметра должно быть менее 4000. Драйвер базы данных должен поддерживать совместимость с функцией fetch_result().

По умолчанию: "2000".

Пример использования параметра fetch_rows:
...
modparam("usrloc", "fetch_rows", 3000)
...


hash_size (integer)

количество записей для хеш-таблицы, используемой модулем usrloc, для хранения записей с контактной информации, из расчета: 2^hash_size . Для hash_size=4, количество записей для хеш-таблицы составляет - 16.

По умолчанию: "9".

Пример использования параметра hash_size:
...
modparam("usrloc", "hash_size", 10)
...



Экспортируемые функции.


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


Экспортируемая статистика.


users

Количество AOR, присутствующих в кэш памяти модуля USRLOC, для данного домена. Значение не может быть сброшено; данную статистику можно зарегистрировать для каждого используемого домена (Ex: location).

contacts

Количество контактов, присутствующих в кэш памяти модуля USRLOC, для данного домена. Значение не может быть сброшено; данную статистику можно зарегистрировать для каждого используемого домена (Ex: location).

expires

Количество просроченных контактов, для данного домена. Значение можно сбросить; данную статистику можно зарегистрировать для каждого используемого домена (Ex: location).

registered_users

Количество AOR, присутствующих в кэш памяти модуля USRLOC, для всех доменов. Значение не может быть сброшено.


Ссылки по теме