Asterisk Managment Interface (AMI), Часть 2

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

Полная версия статьи писалась и будет исправляться здесь: asteriskpbx.ru/wiki/manager-interface-doc

Подключение к интерфейсу 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

Важно понимать, что пароли, передаваемые при соединении с AMI интерфейсом передаются открытым текстом. Это может быть угрозой для работы сервиса Астериск. Чтобы скрыть передаваемый пароль, используют алгоритм md5. Использование алгоритм md5 никаким образом не снимает требований к безопасности, описанных выше. Если вы все-таки используете удаленное подключение даже в приватной сети, рекомендуется использовать запрос/ответ и алгоритм md5, принцип которого очень похож на аналогичную аутентификацию протокола HTTP и SIP. Для этого сначала вызываем действие Challenge (Запрос), который предоставит Вам маркер запроса:
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), которое было подано на вход алгоритма. Гипотетически считается, что два сообщения, которые имеют один и тот же профиль сообщения или выработаны любым сообщением, имеют определенный профиль сообщения.

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

Пакеты Action

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

Action: <key 1>: <value 1>
<key 2>: <value 2>
.......

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

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

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

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: CallerIDName: Uniqueid: 1237301090.1

Event: Newcallerid
Privilege: call,all
Channel: SIP/2401-09a1f418
CallerID: 2401
CallerIDName: Uniqueid: 1237301090.1
CID-CallingPres: 0 (Presentation Allowed, Not Screened)

Event: Newstate
Privilege: call,all
Channel: SIP/2401-09a1f418
State: Ringing
CallerID: 2401
CallerIDName: 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 — опционально.

Как было сказано выше, в 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 (только чтение);
• 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


В пакете 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.