Asterisk Managment Interface (AMI)

Version 1 by Admin
on Feb 21, 2011 11:58.

compared with
Current by Admin
on Feb 28, 2011 10:42.

Key
This line was removed.
This word was removed. This word was added.
This line was added.

Changes (58)

View Page History
h2. Введение

AMI --- мощный и удобный программный интерфейс (API) Asterisk для управления системой из внешних программ. В дополнение к AMI, часто используется AGI --- это интерфейс для запуска внешних приложений, управляющих каналом Астериска в рамках конкретного вызова.
Благодаря AMI внешние программы могут осуществлять соединения с Астериском посредством TCP протокола, инициировать выполнение команд, считывать результат их выполнения, а так же получать уведомления о происходящих событиях в реальном времени. Этими механизмами можно пользоваться, например в следующих случаях:
* Необходимо узнать состояние системы
* ... и пр. и др. и т.п.

AMI часто используют для интеграции с бизнес-процессами и системами, программным обеспечением CRM (Customer Relationship Managment --- управление взаимодействия с клиентами). Он также может применяться для разнообразных приложений, таких как программы автоматического набора номера и системы click-to-call (звонок-по-щелчку).

Управление Астериском часто осуществляется из консоли CLI, но при использовании AMI не требуется прямой доступ к серверу, на котором запущен Астериск.
AMI --- это наиболее простой инструмент, который в руках разработчика может оказаться очень мощным и гибким средством для интеграции с другими программными продуктами. Он дает возможность разработчикам использовать информацию, генерируемую Астериском, в реальном масштабе времени.

Стоит так же отметить, что Астериск начиная с версии 1.6 использует интерфейс менеджера версии 1.1. В основном изменения коснулись объединения множества однотипных команд и стандартизации ответов, выдаваемых различными модулями. Выяснить версию интерфейсам можно с помощью команды CoreSettings. Версия может меняться в дальнейшем, если интерфейс AMI будет терять полную совместимость с предыдущими версиями.

Между сервером Астериск и клиентской программой для установления связи используется простой по-строчный протокол, каждая строка сообщения которого состоит из двух строк:
* key \\- - ключевое слово, описывающее характер информации, содержащейся в текущей строке. Ключевое слово не является уникальным и может встречаться несколько раз в рамках одной посылки
* value \\- - значение параметра
* Ключевое слово от значения отделяется двоеточием

* CRLF используется для разделения каждой из строк в пакете и двух последовательностей CRLF (она же \r\n) для того, чтобы обозначить завершение передачи команды в Астериск

AMI принимает подключения, устанавливаемые на сетевой порт (по умолчанию \-\- TCP порт 5038). Клиентская программа подключается к AMI через этот порт и аутентифицируется, после этого Астериск будет отвечать на запросы, а также отправлять извещения о изменениях состояния заданных подсистем

h2. Типы пакетов

Пакет, передаваемый от клиента в Астериск сервер и назад определяется следующими ключевыми характеристиками:
* _Action_, пакеты отправляемые клиентом, соединенным с AMI. После обработки сервером такого пакета будет осуществлено некоторое действие. Существуют относительно гибкие ограничения на действия, осуществляемые клиентом. Один пакет \\- - одно действие. В пакете Action должно содержаться имя операции, которую необходимо выполнить, а также все необходимые параметры;
* _Response_, определяет ответ, отсылаемый Астериском клиенту по факту выполнения действия;
* _Event_, данные, относящиеся к событию, которое сгенерировано внутри ядра Астериска или модуля расширения.

Как правило, клиент отсылает пакеты _Action_ в Астериск (они так же называются коммандами). Астериск, в свою очередь, выполняет запрос и возвращает результат (часто результат \\- - успешность действия с кратким описанием в случае неудачи), получаемое в пакете Response. Нет гарантии касательно порядка прихода результатов (пакетов Response), поэтому в клиентском запросе обычно включают параметр ActionID в ActionID в каждый пакет Action, при этом соответствующий пакет Response будет содержать такое же значение в поле ActionID. Таким образом, клиент может очень легко обрабатывать Action и Response пакеты, в любом желаемом порядке, не ожидая пакетов Response, чтобы произвести следующее действие.

Следующая команда CLI (работает автодополнение Tab'ом) поможет получить полный списко команд AMI, доступных в вашей версии Астериска:

Пакеты _Response_. Как написано выше, служат ответами на переданные команды. Передается один ответ на команду и может нести несколько значений:
* "Success"
\\
* "Success" \\- \- действие успешно и вся информация содержится в данном пакете
* "Error"
\\
* "Error" \\- \- произошла ошибка, подробное описание в заголовке "Message"
* "Follows"
\\
* "Follows" \\- \- результат выполнения будет передан в последующих Event пакетах

_Event_ пакеты (события) применяются в двух контекстах. С одной стороны \-\- они информируют клиента об изменении состояния подсистем Астериска (пр. изменения состояния канала), с другой стороны \-\- они переносят набор данных, который возвращает Астериск в ответ на действие Action.
* Когда клиент отсылает пакет Action, Астериск может (в случаях если требуется вернуть много однородных записей) отправить _Response_ пакет, содержащий толко запись «Response: Follows». Далее Астериск отсылает некоторое количество событий, содержащих набор данных и, наконец, событие, которое сообщает, что все данные были отправлены. Все генерируемые при этом пакеты Event содержат ActionID первоначального ActionID первоначального пакета Action, который инициировал запрос. Таким образом, можно легко обрабатывать их, как и пакеты Response. Пример события, генерируемого Action'ом --- это Action _Status_, который инициирует событие _Status_ для каждого из активных каналов. После передачи всех событий Status, отправляется событие StatusComplete.
* События создаются различными структурными частями Астериска (каналы SIP/IAX2/..., CDR, диалплан, различные части ядра). Основная задача, которая возложена на события, позволить внешней присоединенной системе получить информацию от Астериска, собирая эти все события, анализируя их и выполняя действия в зависимости от полученных результатов.

События не документированы в CLI, поэтому подробную информацию можно найти в документации (файл manager_1_1.txt), на сайте voip-info.org. Если всё-таки остается впечатление, что какое-то событие не описано, но должно быть \\- - можно найти всевозможные события в исходном коде соответствующего модуля по имени функции \\- - _manager_event_

Перед тем как перейти к практическим примерам, стоит отметить, что начиная с версии 1.6 Астериска интерфейс AMI приобрел номер версии 1.1. Это связано с приведением формата команд к единому формату и частичной потерей совместимости. Статья будет освещать работу версии 1.6, там где различия существуют пояснения будут даны в скобках.

h2. Безопасность

Так как возможности по управлению работой системы, предоставляемые через AMI интерфейс, практически безграничны. Кроме не шифрованного пароля и возможности ограничить доступ к AMI с тех или иных ip-адресов, в интерфейсе Manager (так еще его называют) нет других средств обеспечения безопасности, поэтому крайне не рекомендуется использовать его на публичных IP адресах.

{noformat}

Секция [general] определяет general определяет общие настройки подключения. Активирует AMI опция enabled=yes.
Примечание: Чтобы настройки вступили в силу, необходимо сделать перегрузку AMI:


С помощью опций deny и permit можно указать ip-адреса, с которых возможно осуществлять подключение к Астериску. Можно добавить еще пользователей системы (скопировав секцию начиная с квадратных скобок) и назначить им права доступа:
* read --- права на чтение;
* write --- права на запись.

В указанном выше примере, пользователю admin были даны обширные права, вплоть до остановки сервиса Астериск (за это отвечает опция command). В последующих версиях (1.6.1 и позже) запрещено использовать в AMI команды, которые могут привести к остановке астериска.

h2. Подключение к интерфейсу AMI

Для подключения к AMI, можно использовать программу telnet. Так выглядит приветствие системы:

{noformat}

[два раза Enter, что равносильно вводу CRLF|жмем]
После, должны увидеть такой ответ (пакет Response):


{noformat}
asterisk*CLI>
== Parsing '/etc/asterisk/manager.conf': Found
== Manager 'admin' logged on from 127.0.0.1
Замена пароля и выполнение команды 'manager reload' никак не влияют на права для уже установленных сессий AMI. Это означает что если в файле изменены пароль или права доступа, то эти изменения не затронут уже работающих с сервером клиентов

Если Вам не нужны события, генерируемые Астериском (их может быть очень много, что затруднить чтение в консоли ответов Астериска), то в параметры, передаваемые во время процедура аутентификации, можно включить еще запись

{noformat}

{noformat}
asterisk*CLI>
== Manager 'admin' logged off from 127.0.0.1
{noformat}
{noformat}

где Key --- результирующая сумма.

Примечание md5 алгоритм на входе принимает любую длину символов и на выходе выдать 128-битный отпечаток (finger-print) или профиль сообщения (message digest), которое было подано на вход алгоритма. Гипотетически считается, что два сообщения, которые имеют один и тот же профиль сообщения или выработаны любым сообщением, имеют определенный профиль сообщения.

Message digest --- коротка цифровая строка фиксированной длины, формируется из более длинного сообщения с использованием специального алгоритма. Алгоритм md5 назначен для цифровой подписи (digital signature) приложений, где большие файлы должны быть «сжаты» в безопасный способ, до того как они будут закриптованы с помощью публичного или скрытого ключа с помощью криптосистемы с открытым ключом, например RSA.
Digital signature --- цифровая подпись, которая является уникальным электронным идентификатором, обеспечивающим проверку сообщения с установлением подлинности отправителя и гарантии то, что документ не был изменен с момента подписания.
[статья|недописанная]



h3. Пакеты Action

h2. Уровни авторизации read и write

Параметры read и write в файле manager.conf задают уровни авторизации для различных классов команд AMI. Например, если для пользователя AMI определено в настройках manager.conf обе секции read и write без уровня авторизации «command», тогда этот пользователь не сможет выполнять те команды, для которых определены привилегии --- privilege:command. Узнать, какой класс привилегий необходимо иметь, чтобы выполнить ту или иную AMI команду в Астериске, можно просмотрев описание этой команды в консоли Астериска:

{noformat}
{noformat}

В выводе присутствует краткое описание (Synopsis) действия,выполняемого на Астериске. В Privilege говориться о том, какие привилегии должны быть установлены в manager.conf подключенному пользователю, чтобы выполнить ее в сессии AMI. Variables говорит нам о том, какие параметры возможно передать для успешной отработки команды. Команда обозначенная звездочкой \-\- \*Command, является обязательной (не во всех командах соблюден такой порядок обозначения), а вот ActionID — [ActionID] --- опционально.

Как было сказано выше, в manager.conf мы определяем пользователей AMI --- список доступа (access list). Для каждого из пользователей со списка, необходимо определить множество событий (events) и действий (actions), которые этим пользователям будут давать доступ. Это задается директивами read/write.
Read директива определяет те типы событий, которые отсылаются к пользователю AMI.

Write директива определяет, что для AMI пользователей разрешено инициировать действия, определенные этой директивой.
Следующая информация по значениям для директивы read/write, должна пролить свет на их предназначение:
* _system_ --- действия и события, которые относятся к ядру Астериска, такие как SIP пиры и БД;
* _call_ --- действия и события, относящиеся непосредственно статусов экстеншинов, протекание и управление звонком;
* _log_ --- Logging information, исходная документация не дает детальной информации о том, что именно определено событиями этого типа;
* _verbose_ \\- Verbose information, исходная документация не дает детальной информации о том, что именно определено событиями этого типа;
* _command_ --- эта директива позволяет присоединенным пользователям отсылать команды в консоль CLI Астериска;
* _agent_ --- действия и события, которые относятся к приложения очередей (queue);
* _user_ --- определяет события, которые могут быть сгенерированы с номерного плана, используя приложение [UserEvent]. Использование событий этого типа является полезным средством для разработки приложений, которые соединяют номерной план, AGI, AMI одновременно;
* _config_ \\- возможность читать и записывать содержимое в конфигурационные файлы;
* _dtmf_ \\- получение DTMF событий (только чтение);
* _reporting_ \\- возможность получать информацию о системе;
* _cdr_ \\- результаты работы модуля cdr_manager (если загружен, только чтение);
* _dialplan_ \\- получение событий NewExten и VarSet (только чтение);
* _dialplan_ \- получение событий NewExten и VarSet (только чтение);
* _originate_ \\- доступ к возможности создавать новые вызовы (только запись).

*Примечание* Следует сказать, что время от времени AMI интерфейс расширяется новыми функциями и возможностями. Например, в версии Астериска 1.4 и 1.6 были переписаны AMI интерфейсы, что позволит реализовывать много-поточные операции и лучше управлять потоками (flow control) или обменом сигналами, присоединенных пользователей. Не смотря на постоянно совершенствование AMI интерфейса, шанс получить при активной работе с AMI взаимную блокировку потоков существует.

h2. Примеры использования AMI. Почему нужен уникальный ActionID. Параметры команд AMI
{noformat}

Надо обратить внимание на подчеркнутые строки с ActionID. В пакете Action мы сгенерировали номер, который настоятельно рекомендуют делать уникальным, а в ответе Response мы получили такой же ActionID. Если бы мы сгенерировали много запросов через интерфейс AMI, при этом не обозначив каждый из запросов уникальным ActionID и ActionID и имея «плохой» канал связи, в котором могли быть задержки, пакеты, сгенерированный со стороны клиента (Action-пакеты), в ответ от Астериска, вызывали бы несколько ответных Response-пакетов. В виду плохого канала, ответные Response-пакеты приходили бы не в том порядке, в котором они были сгенерированы клиентом AMI. Следовательно, программа пославшая Action-пакеты, не знала бы на какой запрос Action пришел тот или иной Response. Это могло бы вызвать проблемы с обработкой пакетов на стороне клиента, который имеет соединение через AMI интерфейс.

Чтобы перезагрузить конфигурацию sip.conf, через AMI можно сделать следующее:
{noformat}

Часто может оказаться полезным делать обновление конфигурационных файлов через AMI интерфейс. Для этого используется команда UpdateConfig. Например, удалим пользователя 2402 из файла sip.conf. Команда UpdateConfig имеет UpdateConfig имеет много параметров:

{noformat}

h2. Ссылки

* [http://svn.digium.com/svn/asterisk/trunk/doc/manager_1_1.txt]
* http://svn.digium.com/svn/asterisk/trunk/doc/manager_1_1.txt [http://svn.digium.com/svn/asterisk/trunk/configs/manager.conf.sample]
* http://svn.digium.com/svn/asterisk/trunk/configs/manager.conf.sample [http://www.voip-info.org/tiki-index.php?page=AstManProxy]
* http://www.voip-info.org/tiki-index.php?page=AstManProxy [http://phpagi.sourceforge.net/]
* http://phpagi.sourceforge.net/
* [http://www.voip-info.org/wiki/view/Aynchronous+Javascript+Asterisk+Manager+(AJAM]).