Мы начинаем публикацию статей об Asterisk IP-PBX — одном из наиболее популярных в мире свободных решений компьютерной телефонии.

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

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

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

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

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

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

• 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

Пакеты Respons

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

• «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.

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

Возможности управления работой системы, предоставляемые через 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, который отвечает за настройку.

[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 команды, которые могут привести к остановке астериска.

В ближайшее время будет опубликовано продолжение статьи.

Компания Equelli является экспертом в разработке приложений на базе технологий VoIP.

• Создание приложений телефонии на базе платформы Asterisk.
• Опыт в определении причин и устранении проблем вызовов в IP среде, проблем со слышимостью, работе факсов и модемов в VoIP.
• Расширение существующих телефонных станций путём присоединения IP PBX потоками PRI.
• Установление и решение проблем с SIP протоколами, работа с поддержкой и инженерами компаний-производителей абонентского оборудования и оборудования оператора.
• Тестирование работы SIP устройств и протокола: sipp, sipsak, PROTOS Test-Suite: c07-sip.
• Разработка и внедрение VoIP сети оператора.
• Cтек протоколов TCP/IP, UDP, ICMP, DHCP, DNS.
• Интеграция приложений телефонии в бизнес-процессы, построение сложных IVR систем.
• Построение инфраструктуры и системы автоматического сопровождения абонентского оборудования Linksys. 
• Построение и планирование сетей передачи данных с учётом безопасности и QoS.