Введение

• Необходимо узнать состояние системы
• Количество активных абонентов
• Выполнять команды CLI удаленно
• Улучшить хранение CDR
• ... и пр. и др. и т.п.

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

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

Как работает AMI

Между сервером Asterisk и клиентской программой для установления связи используется простой по-строчный протокол, каждая строка сообщения которого состоит из двух строк:

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

Далее мы будем использовать термин «пакет», что будет описывать серию конструкций «key:value», разделенных CRLF и завершеных дополнительной последовательностью CRLF.

Протокол взаимодействия между Астериском и клиентом можно описать следующими характеристиками:

• Перед тем как посылать команды в сервер Астериск, необходимо выполнить сессию соединения клиента с сервером Астериск;
• Пакеты могут быть переданы в любой последовательности и в любое время после прохождения процедуры аутентификации;
• Первая строка пакета должна содержать один из следующих ключей: «Action» (единственный вариант при отправки клиентом), и ключи «Event» (Событие) и «Response» (Ответ) (должны быть отправлены от Астериска к клиенту);
• Порядок строк в пакете не имеет значения, вы можете использовать любой язык программирования, которым можно формировать пакеты на стороне клиента;
• CRLF используется для разделения каждой из строк в пакете и двух последовательностей CRLF (она же \r\n) для того, чтобы обозначить завершение передачи команды в Астериск

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

Типы пакетов

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

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

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

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

*CLI> manager show commands 

Пакеты Response. Как написано выше, служат ответами на переданные команды. Передается один ответ на команду и может нести несколько значений:

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

Event пакеты (события) применяются в двух контекстах. С одной стороны -- они информируют клиента об изменении состояния подсистем Астериска (пр. изменения состояния канала), с другой стороны -- они переносят набор данных, который возвращает Астериск в ответ на действие Action.

• Когда клиент отсылает пакет Action, Астериск может (в случаях если требуется вернуть много однородных записей) отправить Response пакет, содержащий толко запись «Response: Follows». Далее Астериск отсылает некоторое количество событий, содержащих набор данных и, наконец, событие, которое сообщает, что все данные были отправлены. Все генерируемые при этом пакеты Event содержат 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, там где различия существуют пояснения будут даны в скобках.

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

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

Если же использование из публичной сети необходимо, то необходимо проследить чтобы доступ был ограничен с помощью iptables или производился через VPN туннели любого типа. Доступ к AMI интерфейсу так же может быть получен через встроенный HTTP(S) сервер, настраивается доступ в файле http.conf. Стоит заметить что по-умолчанию интерфейс AMI запрещён, ровно как и работа с ним через HTTP сервер.

Так же в ненадежной сети, если требуется предоставить доступ конечному пользователю к AMI (например, функциональность click-2-call через TAPI), для обработки всех соединений с API интерфейса Manager, рекомендуют использовать программу AstManProxy. О нём в другой раз.

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

Для того, чтобы использовать интерфейс AMI, необходимо отредактировать файл /etc/asterisk/manager.conf, который отвечает за настройку.
Manager.conf

[general] enabled=yes ; возможность работать с AMI (по-умолчанию no) 

port=5038 ; на порту TCP 5038 

bindaddr=192.168.0.1 ; принимать соединения в локальной сети 

(0.0.0.0 - на всех интерфейсах) 

timestampevents = yes ; Отправлять в пакетах событий временную метку 

displayconnects = yes ; Отображать факт подключения пользователя к AMI 

allowmultiplelogin = yes ; Разрешить несколько параллельных подключений с одним 

именем ; Начало секции, описывающей пользователя [admin] ; имя пользователя, 

которое определяется администратором Астериска 

secret=passwd1234 ; пароль пользователя 

AMI deny=0.0.0.0/0.0.0.0 ; запретить все ip-адреса 

permit=192.168.0.2/255.255.255.0 ; разрешить соединение только с одного ip 

read=system, call, log, verbose, command, agent, user ; список передаваемых 

пользователю классов событий 

write=system, call,log, verbose, command, agent, user ; 

список разрешенных классов команд 

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

*CLI>module reload manager 

или

*CLI>manager reload 

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

• read — права на чтение;
• write — права на запись.

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

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

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

$ telnet 127.0.0.1 5038 Trying 127.0.0.1... Connected to localhost. 

Escape character is '^]'. Asterisk Call Manager/1.1 

Далее набираем:

Action: login Username: admin Secret: passwd1234 

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

Response: Success Message: Authentication accepted 

Что говорит нам о том, что мы удачно залогинились в интерфейс AMI.
Во время успешного входа в AMI, в консоли Астериска мы увидим (в 1.4):

asterisk*CLI> == Parsing '/etc/asterisk/manager.conf': 

Found == Manager 'admin' logged on from 127.0.0.1 

В 1.6 устранена необходимость считывать с диска конфигурацию при каждом подключении к AMI. Они считывается единожды при старте программы и может быть перечитана при перезагрузке (команды приведены выше).

Увидеть всех пользователей, соединенных в данный момент с интерфейсом AMI, можно из консоли Астериска:

*CLI> manager show connected 

Замена пароля и выполнение команды 'manager reload' никак не влияют на права для уже установленных сессий AMI. Это означает что если в файле изменены пароль или права доступа, то эти изменения не затронут уже работающих с сервером клиентов

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

Events: off 

Эта запись предотвратить посылку пакетов Event со стороны сервера в рамках установленного соединения

Чтобы завершить сессию подключения к AMI, необходимо выполнить:

Action: logoff 

После чего мы увидим на экране telnet сессии:

Response: Goodbye Message: Thanks for all the fish. 

Во время завершения AMI сессии, в консоли Астериска мы можем увидеть следующее:

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

Примечание Естественно, AMI интерфейс не предназначен для того, чтобы вручную администратор с помощью клиента telnet и ему подобных, осуществлял соединение с сервером Астериск. Здесь этот пример показан исключительно как демонстрация возможностей и наглядности работы обмена пакетами Action, Event и Response. Однако такой подход может пригодиться при обучении и отладке действия той или иной команды.

Примечание Увидеть все команды, относящиеся к CLI интерфейсу управления Астериска AMI, можно набрав в консоли:

asterisk *CLI> help manager 

Пароли при авторизации в AMI

Action: Challenge AuthType: md5 Response: Success Challenge: 84041345 

После этого можно взять маркер полученного запроса и доваить в конце незашифрованный пароль и вычислить контрольную сумму результирующей строки по алгоритму md5. Результат может использоваться для регистрации без необходимости передачи секрета открытым текстом (plain text). Это будет выглядеть следующим образом:

Action: login AuthType: MD5 Username: admin Key: qwf32r23p98yvdspa9h4o4woaewv7 

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

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

Пакеты Action

В то время, когда Астериск отсылает пакеты Action, необходимо обеспечить дополнительные ключи для правильного выполнения, например, вы захотите определить номер вызова и прочее. Более того, возможно вы захотите выполнить вход в номерной план Астериск и передать некоторые параметры канальным переменным. В этом случае, процесс передачи ключей будет выглядеть так:

Action: <action type> <CRLF> <key 1>: <value 1> <CRLF> <key 2>: <value 2> <CRLF> ....... <CRLF> 

Приведем пример, как с помощью AMI интерфейса можно осуществить вызов (допустим сессия Manager'а уже установлена):

Action: Originate Channel: SIP/2401 Context: incoming Exten: 2401 Priority: 1 Callerid: 2401 Variable: ANSWER=1 Variable: _ACC=2 

Необходимо, чтобы SIP пользователь 2401 присутствовал в системе и был зарегистрирован. После нажатия двух раз Enter, мы получили вызов на IP-телефон. В это время в консоли Астериска получим такое:

Action: Originate 

Channel: SIP/2401 

Context: incoming 

Exten: 2401 

Priority: 1 

Callerid: 2401 

Variable: ANSWER=1 

Variable: _ACC=2 

Event: Newchannel 

Privilege: call,all

Channel: SIP/2401-09a1f418 

State: Down 

CallerIDNum: <unknown> 

CallerIDName: <unknown> 

Uniqueid: 1237301090.1 

Event: Newcallerid 

Privilege: call,all 

Channel: SIP/2401-09a1f418 

CallerID: 2401 

CallerIDName: <Unknown> 

Uniqueid: 1237301090.1 

CID-CallingPres: 0 (Presentation Allowed, Not Screened) 

Event: Newstate Privilege: call,all 

Channel: SIP/2401-09a1f418 State: Ringing 

CallerID: 2401 

CallerIDName: <unknown> 

Uniqueid: 1237301090.1 

Event: Hangup 

Privilege: call,all 

Channel: SIP/2401-09a1f418 

Uniqueid: 1237301090.1 Cause: 19 Cause-txt: User alerting, no answer 

Чтобы увидеть все события, которые ожидают отправки в Астериске, необходимо в CLI написать;

asterisk*CLI> manager show eventq 

на что в ответ получим:

Usecount: 1 

Category: 2 

Event: Event: Hangup 

Privilege: call,all 

Channel: SIP/2401-09a1f418 Uniqueid: 1237301603.2 Cause: 21 Cause-txt: 

Как видно из примера, мы выполнили команду Originate, которая доступна в интерфейсе AMI. Более подробную информацию по каждой из команд AMI, можно увидеть выполнив в CLI команду:

asterisk *CLI> manager show command [имя_команды] 

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

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

asterisk*CLI> manager show command Command Action: Command Synopsis: 

Execute Asterisk CLI Command Privilege: command,all Description: 

Run a CLI command. 

Variables: (Names marked with * are required) *Command: 

Asterisk CLI command to run ActionID: Optional Action id for message matching. 

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

• 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 (только чтение);
• originate - доступ к возможности создавать новые вызовы (только запись).

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

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

В списке команд AMI есть команда, которая запрашивает конфигурационные данные от Астериска. Более подробную информацию можно узнать:

asterisk *CLI> manager show command GetConfig 

Запрос на получения настроек файла sip.conf можно получить так:

Action: GetConfig Filename: sip.conf ActionID: 435430239485234 

После чего мы получим следующее:

Response: Success 

ActionID: 435430239485234 

Category-000000: general 

Line-000000-000000: context=incoming 

Line-000000-000001: language=ru 

Line-000000-000002: allowguest=yes 

Line-000000-000003: bindport=5060 

Line-000000-000004: bindaddr=0.0.0.0 

Line-000000-000005: dtmfmode=info 

Line-000000-000006: disallow=all 

Line-000000-000007: allow=alaw 

Line-000000-000008: allow=ulaw 

Line-000000-000009: allow=gsm 

Line-000000-000010: nat=never 

Line-000000-000011: canreinvite=no 

Category-000001: 2401 

Line-000001-000000: type=friend 

Line-000001-000001: host=dynamic 

Line-000001-000002: username=2401 

Line-000001-000003: secret=2401 

Line-000001-000004: callerid=2401 

Line-000001-000005: context=incoming 

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

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

Action: Command Command: sip reload ActionID: 230432984582 

Получаем ответ от AMI:

Response: Follows Privilege: Command ActionID: 230432984582 

--END COMMAND-- Event: ChannelReload Privilege: system,all Channel: 

SIP ReloadReason: CLIRELOAD (Channel module reload by CLI command) 

Registry_Count: 0 Peer_Count: 2 User_Count: 2 

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

asterisk*CLI> manager show command UpdateConfig Action: UpdateConfig Synopsis: 

Update basic configuration Privilege: config,all Description: 

A 'UpdateConfig' action will modify, create, or delete configuration elements in 

Asterisk configuration files. Variables (X's represent 6 digit number beginning with 

000000): SrcFilename: Configuration filename to read(e.g. foo.conf) DstFilename: 

Configuration filename to write(e.g. foo.conf) Reload: Whether or not a reload 

should take place (or name of specific module) Action-XXXXXX: Action to Take (

NewCat,RenameCat,DelCat,Update,Delete,Append) Cat-XXXXXX: Category to operate on 

Var-XXXXXX: Variable to work on Value-XXXXXX: Value to work on Match-XXXXXX: Extra 

match required to match line 

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

• SrcFilename: имеет статус обязательного параметра вызова команды UpdateConfig, определяет имя конфигурационного файла из которого следует считать текущую конфигурацию;
• DstFilename: обязательный, имя записываемого конфигурационного файла;
• Reload: необязательный, определяет, должна ли быть выполнена перезагрузка после того, как конфигурация обновится или же задает имя конкретного модуля, который необходимо перегрузить;
• Action-XXXXX: обязательный, действие, которое необходимо предпринять. Это может быть: NewCat, RenameCat, DelCat, Update, Delete или Append;
• Cat-XXXXX: обязательный, имя изменяемой категории;
• Var-XXXXX: необязательный, имя изменяемой переменной;
• Value-XXXXX: необязательный, значение изменяемой переменной;
• Match-XXXXX: необязательный, если задан,является дополнительным параметром, которому должен соответствовать параметр линии;
• ActionID: необязательный, идентификатор, который используется для обозначения ответа на команду.

Привилегии для этой команды нужны такие: config, all.