SER модуль acc


Модуль acc используется для ведения протоколов транзакций через syslog, SQL, RADIUS или DIAMETER (beta).

Для учета транзакций и выбора интерфейса (backend), который будет использоваться для отправки данных учета (accouting), Вы должны в скрипте устанавливать некоторые флаги (см. раздел с определением экспортируемых параметров этого модуля). Если установлен accouting флаг для определенного backend, то модуль acc будет использовать соответствующий интерфейс для записи учетных данных при завершении транзакции. При штатном использовании этого модуля не требуется использование каких-либо специфичных команд для получения учетных данных - основная функциональность неявно связана с обработкой транзакций. Вам необходимо только отметить транзакцию, данные которой вы хотите учитывать, соответствующей функцией setflag. В дополнение, модуль позволяет Вам использовать функции для accouting'а, этого модуля, в некоторых специальных случаях.

Модуль accouting'а, по умолчанию, протоколирует фиксированный набор атрибутов транзакции, если Вы хотите учитывать некоторые дополнительные атрибуты, обратите внимание на раздел: ''Учет расширенного набора информации".

Ниже представлен минимальный фиксированный набор атрибутов для accouting'a:

  • Имя метода, который использовался в запросе (Request Method)
  • Значение из заголовочного поля From.
  • Значение из заголовочного поля To.
  • Call-Id
  • Трехзначный код возврата финального ответа на запрос.
  • Поле причины финального ответа на запрос (Reason phrase).
  • Отметка времени окончания транзакции.

Если значение какого-либо поля не присутствует в запросе, вместо него будет использоваться пустая строка.

Обратите внимание на следующие моменты:

  • Один INVITE запрос может породить несколько учетных записей в accounting'е --это следует из того, что запрос может быть переправлен по нескольким направлениям одновременно (SIP forking feature).

  • Все флаги для аккаутинга необходимо устанавливать в блоке маршрутизации обработки запросов - только флаг "missed-call" может быть установлен в других блоках маршрутизации.

  • Модуль не занимается учетом сессий/диалогов (пока) - OpenSER не поддерживает учет диалогов и сессий. Если Вам необходимо, для запроса INVITE, найти соответствующее сообщение BYE, для генерации соответствующей CDR записи, например, для билинга, то это лучше реализовывать в программе, которая собирает информацию из accounting'a и обрабатывает ее.

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

Поддержка для интерфейса (backend) к SQL базам уже включена в сам модуль. Для аккаутинга с использованием интерфейса к серверам RADIUS и DIAMETER Вам необходимо явно включить эту поддержку, пересобрав модуль, установив нужные определения: раскоментируйте строки с определением RAD_ACC или DDIAM_ACC в файле modules/acc/Makefile. Для включения поддержки RADIUS, Вам понадобиться установленный radiusclient-ng (версии большей или равной 0.5.0), который можно найти по адресу: http://developer.berlios.de/projects/radiusclient-ng/. Radius клиент должен быть правильно настроен. Для этого, используйте шаблон: etc/radiusclient.conf и убедитесь, что параметр модуля - radius_config указывает на правильное местонахождение этого файла. В частности, secret для аккаутинга должен совпадать с тем, который указан на сервере и используется нужная dictionary (один из вариантов есть в: etc/sip_dictionary).


Основной пример.

loadmodule "modules/acc/acc.so"
modparam("acc", "log_level", 1)
modparam("acc", "log_flag", 1)

if (uri=~"sip:+40") /* calls to Romania */ {
    if (!proxy_authorize("sip_domain.net" /* realm */,
    "subscriber" /* table name */))  {
        proxy_challenge("sip_domain.net" /* realm */, "0" /* no qop */ );
        break;
    }

    if (method=="INVITE" & !check_from()) {
        log("from!=digest\n");
        sl_send_reply("403","Forbidden");
    }

    setflag(1); /* установка флага для accounting'а (в то же значение, что задано в параметре log_flag!)
    t_relay(); 	/* переходим в stateful режим */
};



Учет расширенного набора информации.


Обзор.

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

Определения и синтаксис.

Выбор дополнительной информации для протоколирования производиться с помощью параметры xxx_extra, указывая в нем названия для дополнительной информации, которую Вы хотите протоколировать. Эта информация определяется с помощью использования псевдопеременных и может включать имена заголовков или значения AVP или другие значения из сообщений или системных переменных. Синтаксис параметра:

  • xxx_extra = extra_definition (';'extra_definition)*
  • extra_definition = log_name '=' pseudo_variable

полный список псевдопеременных для Kamailio (ex OpenSER) можно найти по адресу: http://www.kamailio.net/dokuwiki/doku.php/pseudovariables:1.2.x.

С помощью "log_name" вы определяете, как и куда данные будут протоколироваться. Ее значение зависит от того, поддержка каких типов аккаутинга у Вас используется:

  • LOG accounting - log_name будет занесено в лог наряду с другими данными в формате: "log_name=data format;"

  • DB accounting - log_name должна указывать на имя колонки базы данных, куда будут заноситься данные. ВАЖНО: добавьте в таблицу базы данных acc, колонку с соответствующими именами для каждой дополнительно протоколируемой информации.

  • RADIUS accounting - log_name будет содержать имя AVP, которая используется для подготовки данных RADIUS сообщения. log_name будет транслироваться в номер AVP с использованием dictionary. ВАЖНО: добавьте в RADIUS dictionary атрибут для используемого log_name.

  • DIAMETER accounting - log_name будет содержать AVP код, который используется для подготовки DIAMETER сообщения. AVP код указывается напрямую в числовом виде, т.к. DIAMETER не поддерживает dictionary. ВАЖНО: log_name должно быть числом.

Как это работает.

Некоторые псевдопеременные могут возвращать более одного значения (такие, как заголовочные поля или AVP). В этом случае, возвращенные значения объединяются в одну строку, где они будут разделяться запятыми.


Поддержка аккаутинга соединений с несколькими плечами (Multi Call-Legs accounting).

P.s: с несколькими ногами - мне не нравиться. :)

Обзор.

SIP вызов может иметь несколько маршрутов, когда происходит его переназначение. Например, пользователь A звонит пользователю B, который переводит вызов на пользователя C. Тут у нас только один SIP вызов, но с двумя плечами (A к B, и B к C). Нам требуется учитывать эти два различных плеча соединения для надлежащего билинга вызовов (если пользователь C - имеет номер в PSTN, и вызов до него платный, пользователь B должен оплачивать этот вызов - как последняя сторона, которая изменила пункт назначения вызова, а не пользователь A, который был его инициатором). Переназначение вызова на сервере - это только один пример, который указывает нам на необходимость механизма по учету вызовов с несколькими плечами (или ногами, как Вам удобнее).

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

Для начала, как это работает? Идея состоит в том, что у нас имеется набор AVP для каждого плеча вызова, для хранения другого набора значений AVP. Значение содержимого включаемых AVP полностью определяется в настройках сервера, это может быть источник происхождения этого плеча вызова, его состояния, или любая другая связанная с ним информация. Если у Вас имеется набор из 4 AVP (AVP1, AVP2, AVP3, AVP4), тогда, для примера вызова из A к B и переназначения вызова пользователем B к пользователю C, для каждого плеча вызова (A, B и B, C), Вы должны установить различный набор значений для AVP. Автор сценария обработки вызовов должен сам позаботиться и должным образом выставлять значения всех AVP из скрипта (в правильном порядке и с правильным типом).

Когда accouning информация для вызова будет записываться или отправляться, будут добавлены все пары плеч вызова (на основании найденных наборов AVP).

По умолчанию, поддержка вызовов с множеством плеч (multiple call-legs) - отключена. Ее можно включить, задав набор AVP для плеч вызовов, с помощью параметра модуля - multi_leg_info.

Протоколируемые данные.

Для каждого вызова, будут протоколироваться все значения из набора AVP (которые определены для плеча вызова). То, как информация фактически будет протоколироваться, зависит от используемого интерфейса (backend):

  • syslog - все данные плеч соединения будут добавлены в одну строку в виде набора: AVP1=xxx, AVP2=xxxx ,...

  • database - каждая пара будет сохранена раздельно (в силу структуры базы данных); Будут записаны несколько записей, различие в них будут заключаться только в полях, которые относятся к информации о плече вызова.
exclaim Вам будет необходимо добавить в вашей базе данных (для всех таблиц, связанных с работой acc), колонки для хранения информации, связанной с плечом вызова (по одной колонке для каждого AVP из набора).

  • Radius - все наборы будут добавлены в одно RADIUS сообщение для аккаутинга, как RADIUS AVP - для каждого плеча вызова будет добавлен свой набор из RADIUS AVP (соответствующий набор из AVP для каждого плеча вызова).
exclaim Вам будет необходимо добавить все эти используемые AVP в Ваш RADIUS dictionary.

  • Diameter - по аналогии с RADIUS.


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


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

  • tm: Модуль управления транзакциями (Transaction Manager)

  • модули поддержки баз данных — если скомпилирован с поддержкой общения с базами данных.

  • rr: Логика маршрутизации сообщений и поддержка SIP диалогов, если включен параметр модуля - "detect_direction".


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


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



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


early_media (integer)

Надо ли протоколировать использование "early media" (183) ? (поток, до фактического установления соединения)

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

Пример использования параметра early_media:

modparam("acc", "early_media", 1)


failed_transaction_flag (integer)

Флаг для транзакции, указывающий на то, что данные транзакции должны быть запротоколированы также и в случае неуспешного завершения (status>=300).

По умолчанию: не установлено (нет флага).

Пример использования параметра failed_transaction_flag:

modparam("acc", "failed_transaction_flag", 4)


report_ack (integer)

Должен ли модуль acc также пытаться учитывать e2e ACKs? Стоит отметить, что это действительно будет только попытка, поскольку e2e ACK может иметь другой маршрут (если не включены возможности модуля rr ), и не соответствовать оригинальному сообщению INVITE (e2e ACK - это отдельная транзакция).

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

Пример использования параметра report_ack:

modparam("acc", "report_ack", 1)


report_cancels (integer)

По умолчанию, протоколирование сообщений CANCEL выключено. Многим аккаутинговым приложениям очень нравиться, когда они видят отменяемые INVITE запросы. Вы можете включить эту возможность, если вы хотите протоколировать CANCEL транзакции.

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

Пример использования параметра report_cancels:

modparam("acc", "report_cancels", 1)


detect_direction (integer)

Управляет обнаружением направления движения последовательности запросов. Если включено (не нулевое значение), то для последовательности запросов с upstream (от вызываемого к вызывающему), поля FROM и TO будут поменяны местами (направление вызова сохраняется в оригинальном инициирующем запросе).

Это касается всех значений в заголовочных полях TO и FROM (body, URI, username, domain, TAG).

По умолчанию: 0 (выключено).

Пример использования параметра detect_direction:

modparam("acc", "detect_direction", 1)


multi_leg_info (string)

Параметр определяет набор AVP, которые будут использоваться для учета каждого плеча соединения. См. соответствующий раздел выше по этому поводу.

Если задана пустая строка, учет для каждого из плеч вызовов выключен.

По умолчанию: 0 (выключено).
Пример использования параметра multi_leg_info:

# для учета с использованием syslog, используйте любой текст, который вы хотите напечатать в логе
modparam("acc", "multi_leg_info",
    "text1=$avp(src);text2=$avp(dst)")
# для учета с использованием базы данных, используйте имена колонок
modparam("acc", "multi_leg_info",
    "leg_src=$avp(src);leg_dst=$avp(dst)")
# для учета с использованием RADIUS, используйте имена RADIUS AVP
modparam("acc", "multi_leg_info",
    "RAD_LEG_SRC=$avp(src);RAD_LEG_SRC=$avp(dst)")
# для учета с использованием DIAMETER, используйте DIAMETER AVP ID (число)
modparam("acc", "multi_leg_info",
    "2345=$avp(src);2346=$avp(dst)")



log_flag (integer)

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

По умолчанию: не установлено (нет флага).

Пример использования параметра log_flag:

modparam("acc", "log_flag", 2)


log_missed_flag (integer)

Флаг запроса, который необходимо установить для учета пропущенных вызовов с использованием syslog.

По умолчанию: не установлено (нет флага).

Пример использования параметра log_missed_flag:

modparam("acc", "log_missed_flag", 3)


log_level (integer)

Log level для учетных сообщений при использовании syslog.

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

Пример использования параметра log_level:

modparam("acc", "log_level", 2) # Set log_level to 2


log_extra (string)

Дополнительная информация для протоколирования при использовании syslog.

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

Пример использования параметра log_extra:

modparam("acc", "log_extra", "ua=$hdr(User-Agent);uuid=$avp(i:123)")


radius_config (string)

Этот параметр нужен только при использовании RADIUS сервера.
Он определяет путь к файлу конфигурации radius клиента. В указанном файле нужно указать корректные данные адреса сервера, secret (должен соответствовать с тем, что указано в /usr/local/etc/raddb/clients для freeRadius сервера) и dictionary, смотри содержимое директории etc с примерами файлов конфигурации и dictionary.

Если в качестве параметра указана пустая строка, поддержка аккаутинга с использованием RADIUS будет отключена (даже если она скомпилирована).

По умолчанию: "/usr/local/etc/radiusclient/radiusclient.conf ".

Пример использования параметра radius_config:

modparam("acc", "radius_config", "/etc/radiusclient/radiusclient.conf")


radius_flag (integer)

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

По умолчанию: не установлено (нет флага).

Пример использования параметра radius_flag:

modparam("acc", "radius_flag", 2)


radius_missed_flag (integer)
Флаг запроса, который необходимо установить для учета пропущенных вызовов с использованием radius сервера.
Этот параметр нужен только при использовании RADIUS сервера.

По умолчанию: не установлено (нет флага).

Пример использования параметра radius_missed_flag:

modparam("acc", "radius_missed_flag", 3)


service_type (integer)

Тип сервиса для Radius, используемый для учета данных.

По умолчанию: 15 (SIP).

Пример использования параметра service_type:

modparam("acc", "service_type", 16)


radius_extra (string)

Дополнительная информация для протоколирования при использовании radius сервера.
Этот параметр нужен только при использовании RADIUS сервера.

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

Пример использования параметра radius_extra:

modparam("acc", "radius_extra", "via=$hdr(Via*); email=$avp(s:email)")


db_flag (integer)

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

По умолчанию: не установлено (нет флага).

Пример использования параметра db_flag:

modparam("acc", "db_flag", 2)


db_missed_flag (integer)

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

По умолчанию: не установлено (нет флага).

Пример использования параметра db_missed_flag:

modparam("acc", "db_missed_flag", 3)


db_table_acc (string)

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

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

Пример использования параметра db_table_acc:

modparam("acc", "db_table_acc", "myacc_table")


db_table_missed_calls (string)

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

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

Пример использования параметра db_table_missed_calls:

modparam("acc", "db_table_missed_calls", "myMC_table")


db_url (string)

Адрес для подключения к SQL базе. Если установлено в NULL или пустую строку, поддержка SQL базы выключена.
Этот параметр нужен только при использовании базы данных.

По умолчанию: "NULL" (поддержка SQL выключена).

Пример использования параметра db_url:

modparam("acc", "db_url", "mysql://user:password@localhost/openser")


acc_method_column (string)

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

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

Пример использования параметра acc_method_column:

modparam("acc", "acc_method_column", "method")


acc_from_tag_column (string)

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

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

Пример использования параметра acc_from_tag_column:

modparam("acc", "acc_from_tag_column", "from_tag")


acc_to_tag_column (string)

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

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

Пример использования параметра acc_to_tag_column:

modparam("acc", "acc_to_tag_column", "to_tag")


acc_callid_column (string)

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

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

Пример использования параметра acc_callid_column:

modparam("acc", "acc_callid_column", "callid")


acc_sip_code_column (string)

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

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

Пример использования параметра acc_sip_code_column:

modparam("acc", "acc_sip_code_column", "sip_code")


acc_sip_reason_column (string)

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

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

Пример использования параметра acc_sip_reason_column:

modparam("acc", "acc_sip_reason_column", "sip_reason")


acc_time_column (string)

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

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

Пример использования параметра acc_time_column:

modparam("acc", "acc_time_column", "time")


db_extra (string)

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

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

Пример использования параметра db_extra:

modparam("acc", "db_extra", "ct=$hdr(Content-type); email=$avp(s:email)")


diameter_flag (integer)

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

По умолчанию: не установлено (нет флага).

Пример использования параметра diameter_flag:

modparam("acc", "diameter_flag", 2)


diameter_missed_flag (integer)

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

По умолчанию: не установлено (нет флага).


Пример использования параметра diameter_missed_flag:

modparam("acc", "diameter_missed_flag", 3)


diameter_client_host (string)

Имя хоста, где запущен клиент DIAMETER.
Этот параметр нужен только при использовании DIAMETER сервера.

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

Пример использования параметра diameter_client_host:

modparam("acc", "diameter_client_host", "3a_server.net")


diameter_client_port (int)

Номер порта, который слушает клиент DIAMETER.
Этот параметр нужен только при использовании DIAMETER сервера.

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

Пример использования параметра diameter_client_host:

modparam("acc", "diameter_client_port", 3000)


diameter_extra (string)

Дополнительная информация для протоколирования при использовании diameter сервера.
Этот параметр нужен только при использовании DIAMETER сервера.

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

Пример использования параметра diameter_extra:

modparam("acc", "diameter_extra", "7846=$hdr(Content-type);7847=$avp(s:email)")



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


acc_log_request(comment)

Функция протоколирует запрос, например, она может быть использована для учета неудавшихся вызовов телефонов пользователей, которые находятся в выключенном состоянии или не найдены, когда на запрос получен ответ: "404 - Not Found". Для предотвращения множество таких записей в аккаутинге, которые могут появляться при повторных передачах запроса по протоколу UDP, Вы можете внедрить эту функцию в процесс обработки запроса в stateful режиме.

Параметры имеют следующие значения:

  • comment - Добавляемый комментарий.

Эта функция может использоваться из блоков: REQUEST_ROUTE, FAILURE_ROUTE.

Пример использования функции acc_log_request:
...
acc_log_request("Some comment");
...


acc_db_request(comment, table)

По аналогии с функцией acc_log_request, acc_db_request протоколирует данные запроса. Эти учетные данные отправляются базе данных, указанной в параметре "db_url", в таблицу, которая указана во втором параметре.

Параметры имеют следующие значения:

  • comment - Добавляемый комментарий.
  • table - Используемая таблица базы данных.

Эта функция может использоваться из блоков: REQUEST_ROUTE, FAILURE_ROUTE.

Пример использования функции acc_db_request:
...
acc_log_request("Some comment", "Some table");
...


1.6.3. acc_rad_request(comment)
По аналогии с функцией acc_log_request, acc_rad_request протоколирует данные запроса. Эти учетные данные отправляются на radius сервер, определенный в "radius_config".

Параметры имеют следующие значения:

  • comment - Добавляемый комментарий.

Эта функция может использоваться из блоков: REQUEST_ROUTE, FAILURE_ROUTE.

Пример использования функции acc_rad_request:
...
acc_rad_request("Some comment");
...


acc_diam_request(comment)

протоколирует данные запроса acc_log_request, acc_diam_request протоколирует данные запроса. Эти учетные данные отправляются на Diameter сервер.

Параметры имеют следующие значения:

  • comment - Добавляемый комментарий.

Эта функция может использоваться из блоков: REQUEST_ROUTE, FAILURE_ROUTE.

Пример использования функции acc_diam_request:
...
acc_diam_request("Some comment");
...



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