В продолжение к опубликованной на днях первой части описания работа интерфейса PBX с открытым исходным кодом Asterisk я публикую вторую часть. В этой части приводятся некоторые примеры использования этого интерфейса для взаимодействия с PBX, начиная от подключения и авторизации, заканчивая осуществлением вызова и редактированием конфигурационных файлов.
Полная версия статьи писалась и будет исправляться здесь
Подключение к интерфейсу AM
Для подключения к 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 |
Пароли при авторизации в AM
Важно понимать, что пароли, передаваемые при соединении с 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]: необязательный, идентификатор, который используется для обозначения ответа на команду.