AMI

De Asterisk Wiki
Ir a la navegación Ir a la búsqueda

Las siglas AMI vienen de Asterisk Manager Interface, o Interfaz para la Gestión de Asterisk. Si pudieramos comparar a Asterisk con una PBX, AMI sería el equivalente a un CTI (Computer Interface Integration, o Interfaz de Integración con el Ordenador). Hay que considerar que aunque paradojicamente, Asterisk ya es un programa de ordenador en si, como veníamos diciendo, si consideraramos a Asterisk como otra PBX, sería como una interfaz para la integración con otras aplicaciones de ordenador.

Introducción a CTI

Clásico Key System de 6 Botones

Es interesante conocer algo sobre los sistemás CTI que incorporan muchas PBX del mercado. En los años 70, varios años después de la primera central conmutada, surgieron las primeras integraciones de sistemas no relacionadas exclusivamente con la función de conmutación de llamadas provenientes de los "Key Systems" (sistemas más sencillos que las PBX, basados en teléfonos con muchos botones) y de las propias PBX, que daban funcionalidades adicionales a las "sencillas" centralitas, como la posibilidad de tener una Operadora Autómatica, Buzones de Voz e incluso Marcadores Predictivos bastante funcionales.

Pero hasta finales de los años 80, no surgieron las primeras interfaces, capaces de enviar a través de un cable, Bus de comunicación, suficiente información acerca del estado de la PBX en cada momento, como para que una máquina conectada a esta (un ordenador), fuera capaz de interpretar estos mensajes y poder realizar funciones acorde. Sistemas CTI más avanzados permitieron incluso una comunicación de dos vías (duplex), con la cual, podriamos mandar información a la central de conmutación para que hiciera las veces de un telefono cualquiera. Durante los años 90, todas las centrales PBX ya incorporaban de alguna un otra forma, alguna interfaz CTI, el problema es que como venía siendo popular, el acceso al manejo de las mismas no estaba al alcance de cualquiera. Y la información al respecto tampoco cumplia una serie de estandares lo suficientemente divulgados como para ser comunes entre varias PBX de diferentes marcas.

A partir del siglo XXI surgió el concepto de Comunicaciones Unificadas, tratando de salvar la barrera de las CTI, dado que los programadores les resultaba demasiado complicado, tener que adaptar sus programas constantemente a las nuevas modificaciones que surgían por cuestiones de nuevas marcas en las empresas, o incluso nuevas versiones dentro de la propia marca.

Introducción a AMI

Curiosamente, es muy típico comparar a AMI con un CTI de cualquier PBX, pero AMI de hecho se aproxima más a un sistema de UC (Unified Communications, Comunicaciones Unificadas), dado que ofrece un estándar unificado, y evita la necesidad de normalizar y consolidar información proveniente de varios entornos.

De hecho, dada la rápida integración que supone este nivel que ofrece AMI, y que es muy dificil darse con otros sistemas PBX, mútliples aplicaciones provenientes del entorno Open Source, han sido capaces de adaptar sus sistemas para una correcta operación con Asterisk prácticamente desde sus inicios.

Existen innumerables proyectos que integran Asterisk para ofrecer una funcionalidad mejorada a traves de la interfaz AMI, y los tipos más comunes suelen ser:

  • Aplicaciones basadas en la Monitorización: Por ejemplo para el control de usuarios, colas como Flash Operator Panel [1]
  • Aplicaciones relacionadas al control de las llamadas, como A2Billing [2] sistema de facturación integrado en Asterisk para el control de los tiempos de llamada.

Funcionamiento General

La interfaz AMI se basa en un flujo de datos en formato de texto plano (lo que puede ser un gran compromiso para la Seguridad de nuestro sistema Asterisk), y con una estructura Estandarizada que se preserva desde la primera versión.

El flujo que se crea dentro de la AMI puede ser provocado, tanto de forma saliente, a traves de los Módulos que vuelcan información en la interfaz, como comandos entrantes, que también recepcionarían ciertos Módulos y harían alguna función con los datos recibimos.

El formato o sintaxis es relativamente sencillo:

  • La primera linea, suele ser del tipo: Event: <Comando> siendo el comando que se va a mostrar o ejecutar.
  • Cada linea siguiente al igual que la primera, debe poseer una cabecera, indicando una "propiedad", y luego una información asociada a esta. Dependiendo del módulo podra tener tantas lineas con este formato, como Datos se puedan ofrecer o precisar (dependiendo si es información entrante o saliente).
  • Al final del flujo de un Comando concreto, debe haber una linea vacía indicando el fin del comando. Esto puede ser util cara a comprobar si existe un End_of_line independiente, si creando un interprete que sea capaz de analizar todo el flujo.

Un ejemplo siguiendo estas directrices podría ser:

Event: Hangup Channel: SIP/ext11 Uniqueid: 1234567.89 Cause: 19

Esto significa, que nuestra interfaz Asterisk, ha recibido un comando Hangup (Fin de la Conversación), por el canal SIP para el dispositivo ext11, y la Causa ha sido NO ANSWER (Sin respuesta). El Uniqueid, identificaría en este caso, un evento con un código único, basado en una marca de tiempo aleatoria, podría utilizarse con fines de indexación si estamos registrando todos los eventos de alguna forma.

Configuración del Mánager

Como comentábamos al principio, AMI es realmente un concepto de Comunicaciones Unificadas más que un simple CTI, y otra prueba de ello es que la conexión a AMI se realiza a través del protocolo TCP/IP. Concretamente el puerto por defecto que se suele utilizar para este propósito es el 5038. También existe la posibilidad de habilitar la funcionalidad de conectar con interfaces basadas en la web y aplicaciones como navegadores, utilizando el protocolo HTTP, gracias a una tecnología diseñada específicamente para Asterisk basada en Java y AJAX, llamada AJAM (Asynchronous Javascript Asterisk Manager), parecida a AJAX con respecto a la equivalencia con uso de mensajes XML, y para ello se utiliza por defecto el puerto 8088.

Configuración General

La estructura del fichero es muy estándar como vistas en otros módulos como SIP, IAX, e incluso el fichero referente a Colas, definido por contextos entre corchetes, considerando uno general donde se engloban todas las opciones genéricas referentes al funcionamiento de AMI, y también otras que afectan a todos los contextos específicos por igual. En este caso el contexto principal sería [general], y el resto de los contextos serían los usuarios del sistema con sus parámetros concretos.

Los parámetros más comunes que suelen ser declarados en el apartado general son los siguientes:

  • enable: Permitimos el uso del AMI, por el protocolo TCP/IP estándar.
  • port: Podemos cambiar el puerto por defecto, 5038, por otro definido a voluntad
  • webenabled: Permitimos el uso del AMI, por HTTP utilizando la tecnología AJAM, muy útil en determinados contextos.
  • bindaddr: Si queremos asociar el Mánager a una IP concreta del servidor, o por el contrario a todas las combinaciones posibles si ponemos 0.0.0.0 (por defecto).
  • allowmultiplelogin: Permitir la posibilidad de acceder con el mismos usuario múltiples veces
  • displayconnects: Permitir que envie información en caso de conexión de un cliente a AMI a traves de la CLI
  • timestampevents: Si deseamos que además incluya una marca de tiempo en cada evento que aparezca en la consola
  • channelvars: Si queremos que se muestren determinadas variables de canal cada vez que un evento de canal salga, especificamos los nombres de las variables especificas, separadas por copas
  • debug: Podemos especificar ("on" y "off"), si queremos que aparezcan entre los eventos de AMI, mensajes de debug adicionales, además de poder ser accesibles desde la CLI
  • authlimit: Si queremos limitar el número máximo de sesiones autentificadas totales, podemos especificar el número con este parámetro.
  • httptimeout: Elegimos la cantidad de segundos que una sesión HTTP puede quedar activa antes de necesitar volverse a autentificar, en terminos de vida de una "cookie", tiempo despues de complentar una acción con éxito, o tiempo después de recibir un evento tipo WaitEvent, sin respuesta

Configuración de Usuarios

Por otra parte, tenemos que configurar los usuarios que tienen permitido el acceso a la interfaz. El nombre del contexto, tiene que ser justamente el mismo, que el nombre de usuario que queramos definir, por tanto si creamos el contexto [asterisk] tendremos un usuario para acceder a AMI llamado "asterisk".

Por otro lado, el resto de los parámetros definen algunos comportamientos y el resto de parámetros para su correcta autenticación:

  • secret: La contraseña para el usuario que hayamos definido, en formato texto plano
  • deny: Si queremos bloquear el acceso a alguna subred o dirección concreta, el formato: IP/Mascara de red, si ponemos la genérica 0.0.0.0/0.0.0.0 bloqueamos todo por defecto
  • permit: Redes o Direcciones IP permitidas de acceso, justo lo contrapuesto, si hemos especificado la genérica en deny aqui podemos desbloquear las redes o direcciones a nuestra voluntad, esto aportaría un nivel mayor de Seguridad especialmente si pudiéramos identificar exactamente una dirección desde la cual van a producirse las conexiones a AMI.
  • eventfilter: Este parámetro sirve si queremos establecer filtros de visualización en determinados Eventos exclusivos. Si tenemos un nivel de manejo sobre la aplicación que esta interfasada con nuestro AMI, o si es de nuestra propia creación, podríamos facilitar la tarea filtrando en detalle. Podemos poner varios tipos de expresiones regulares, incluyendo una exclamación para indicar lo que no queremos visualizar, y el Asterisco para indicar que afecta a todas las coincidencias que cumplan el resto de la expresión. Ej: Event: New*, solo incluiría eventos tipo NewChannel, NewExten, etc...
  • writetimeout: Expresado en milisegundos, considerar que dependiendo como hayamos diseñado el interprete de AMI es posible que si no establecemos unas "pausas" mínimas entre evento y evento, podrían escaparse algunos eventos y afectar al buen funcionamiento del mismo. Con este parámetro podremos regular esto, expresando de cuanto queremos que sean esos intervalos.

Por último existen dos parámetros orientados a los permisos de acceso. Hay que considerar que cada Comando, necesita unos permisos de acceso u otros, y es posible, tanto dar permisos de lectura a estos comandos como de escritura. Los parámetros serían:

  • read: Englobando todos los permisos de lectura
  • write: Englobando los de escritura

Los permisos de organizan por bloques. Si utilizamos el permiso all damos acceso a todos los comandos para un tipo de permiso de los dos, por tanto si especificamos:

  • read = all
  • write = all

Para ese usuario en concreto damos acceso integral al sistema AMI. En cierto nivel, esto también supone un riesgo en la seguridad, por lo que sería conveniente intentar establecer los permisos acordes a lo que pueda hacer la aplicación, especialmente si se tratan de permisos de escritura, dado que con ellos, se podría operar con nuestra máquina Asterisk como si estuviera físicamente en ella como podremos ver más en detalle en Seguridad.

Los grupos de acceso son los siguientes:

  • system: Información del sistema interno Asterisk y la posibilidad de ejecutan comandos relacionados al sistema directamente, como reiniciar el servicio, etc.
  • call: Información sobre los canales de llamada, y el acceso a poder cursar las mismas a través de ellos
  • log: Acceso de lectura exclusivamente para el sistema de logging
  • verbose: Acceso de lectura para las capacidad de mostrar información en detalle
  • agent: Información sobre el sistema de Colas y la posibilidad de introducir Agentes dentro de las mismas.
  • user: Posibilidad de mostrar y enviar eventos relacionados a Usuario, todavía no hay nada definido al respecto.
  • config: Acceso informativo y posibilidad de modificar lo relación a ficheros de configuración.
  • command: Posibilidad de lanzar y leer comandos de la CLI
  • dtmf: Acceso de solo lectura para poder recibir las pulsaciones producidas por tonos DTMF
  • reporting: Información general del sistema, como información sobre pares SIP, IAX, etc.
  • cdr: Acceso de solo lectura, para información relativa al Registro Llamadas y Eventos
  • dialplan: Acceso de solo lectura para ver el recorrido a traves del Dialplan de las llamadas en curso.
  • originate: Posibilidad de generación automática de llamadas. Fundamental para los Marcadores
  • agi: Integración entre AGI y AMI Podemos ver información sobre comandos AGI ejecutados, o lanzar aplicaciones AGI que conozcamos.
  • cc: Acceso de solo lectura, sobre manipuladores de la llamada (Buzones de Voz, transferencias, etc)
  • aoc: Posibilidad de enviar y recibir mensajes de "Advice of Charge" [3]
  • test: Si tenemos funciónes habilitadas de prueba, para depuración y modificación del codigo, podemos recibir los eventos de Test enviados al sistema de testing de Asterisk
  • message: Podemos lanzar a AMI, mensajes de llamada.

Registro de Comandos

Cada comando viene precedido como vimos antes por una cabecera Event:. A continuación vamos a ver algunos comandos de ejemplo, que podrían verse en una comunicación cualquiera:

Comandos Generales

Todos los comandos genericos de AMI para mostrar o insertar información, la mayoría requiere el permiso system salvo especificados concretamente:

  • WaitEvent: Espera a que un evento surja, no requiere ningun permiso especial
  • AGI: Permite lanzar un script AGI y requiere el permiso agi.
  • MuteAudio: Silencia un canal de audio
  • MixMonitorMute: Silencia una grabación producida por MixMonitor
  • AOCMessage: Genera un mensaje de tipo "Advice of Charge" en un canal, requiere el permiso especifico aoc
  • DBDelTree: Borra un Arbol de AstDB
  • DBDel: Borra un registro de la base de datos AstDB
  • DBPut: Borra una entrada de AstDB
  • DBGet: Para recoger un registro concreto de la BD AstDB
  • SIPnotify: Para enviar un mensaje de notificación por el protocolo SIP
  • Challenge: Genera un hash el registro MD5
  • Login: Para registrarnos en el sistema AMI
  • Logoff Para salir del sistema AMI
  • Events: Para controlar el flujo de Eventos
  • ModuleCheck: Comprueba si un modulo esta cargado
  • ModuleLoad: Para cargar un modulo concreto
  • Command: Para ejecutar un comando directamente en la CLI, requiere el permiso command.
  • Originate: Para lanzar una llamada con el comando Originate, requiere el permiso originate
  • ListCommands: Para mostrar esta lista de comandos de AMI.

Comandos de Colas

Para el sistema de Colas tenemos los siguientes eventos, todos se engloban dentro del permiso agent

  • QueueReset: Resetea el log de estadisticas de las colas
  • QueueReload: Reinicia una o varias colas
  • QueueRule: Para crear una regla de una cola
  • QueuePenalty: Para poner el nivel de "multa" a un miembro de una cola
  • QueueLog: Para añadir un registro manual al log de las colas
  • QueueAdd: Para añadir un miembro a una cola
  • QueueSummary: Mostramos el resumen de una cola.
  • QueuePenalty: Mostramos el estado de una cola

Comandos de Llamadas

Para el sistema de llamadas en general, conferencias y monitorización y grabaciones, englobados dentro del permiso call:

  • PlayDTMF: Ejecuta un tono DTMF en un canal especifico.
  • MeetmeMute: Permite silenciar un usuario del sistema MeetMe
  • MeetmeUnmute: Vuelve a permitir hablar a un usuario silenciado en el sistema MeetMe
  • UnpauseMonitor: Quita la pausa de grabación de un canal.
  • PauseMonitor: Pausa la grabación de un canal
  • ChangeMonitor: Cambia el nombre del fichero de una grabacación
  • StopMonitor: Para la grabación de un canal
  • Monitor: Inicia la grabación o monitorización de un canal
  • Bridge: Para hacer un puente entre dos canales dentro Asterisk
  • Park: Para aparcar con el sistema de Features de Asterisk.
  • Parkinglots: Mostrar una lista de plazas disponible en el sistema de "aparcamiento" de llamadas de Asterisk
  • ParkedCalls: Muestra la lista de llamadas aparcadas.
  • Atxfer: Realiza una transferencia en modo atendido.
  • Redirect: Realiza una transferencia desatentida.
  • SendText: Manda un mensaje de texto a un canal
  • Getvar: Recoge una variable de canal concreta.
  • Setvar: Asigna un valor a una variable de canal concreta, equivalente a la aplicación Set
  • Hangup: Para colgar un canal
  • AbsoluteTimeout: Sirve para asignar un tiempo absoluto, equivalente a su función

Comandos para Mostrar Información

Todos aquellos comandos que nos permiten obtener mas información de varios aspectos de Asterisk englobados en el comando reporting:

  • SIPshowregistry: Muestra los accesos al sistema Asterisk con el procolo SIP.
  • SIPqualifypeer: Sirve para controlar un par tipo SIP similar al parametro qualify de SIP.
  • SIPshowpeer: Muestra un par concreto conectado por SIP.
  • SIPpeers: Muestra todos los pares conectados por SIP.
  • IAXregistry: Equivalente a SIPshowregistry para IAX.
  • IAXpeers: Muestra los pares conectados por IAX.
  • VoicemailUsersList: Muestra la lista de usuarios del sistema de Buzones de Voz.
  • MeetmeList: Muestra los usuarios que se encuentran en una sala de conferencias MeetMe.
  • CoreStatus: Muestra el estado de las variables globales en Asterisk.
  • CoreSettings: Muestra la configuración general del sistema Asterisk
  • ShowDialPlan: Muestra los contextos y las extensiones del Dialplan
  • CoreShowChannel: Muestra todos los canales activos
  • MailboxCount: Comprueba el numero de mensajes en un buzon concreto.
  • MailboxStatus: Comprueba el estado de un |buzon de vozconcreto
  • ExtensionState: Comprueba el estado de una extensión
  • Status: Muestra el estado de un canal concreto.

Comandos de Configuración de Asterisk

  • Reload: Recarga la configuración de asterisk
  • UpdateConfig : Actualiza la configuración basica de Asterisk
  • ListCategories: Muestra las categorias en un fichero de configuración
  • CreateConfig: Crea un fichero de configuración vacio en el directorio de configuración por defecto.
  • GetConfigJSON: Recoge la información de configuración en formato JSON
  • GetConfig: Recoge la información de configuración en texto plao

Referencias

  1. Flash Operator Panel, Nicolás Gudiño (2004)
  2. A2Billing, Star2billing S.L. (2004)
  3. Advice of Charge, Wiki Oficial de Asterisk en Ingles, Digium Inc.

Véase también

Enlaces Externos