manager.h File Reference

The AMI - Asterisk Manager Interface - is a TCP protocol created to manage Asterisk with third-party software. More...

#include <stdarg.h>
#include <sys/types.h>
#include <sys/socket.h>
#include <netinet/in.h>
#include <arpa/inet.h>
#include "asterisk/lock.h"

Include dependency graph for manager.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	manager_action
struct	message
Defines
#define	ast_manager_register(a, b, c, d)   ast_manager_register2(a, b, c, d, NULL)
#define	AST_MAX_MANHEADERS   128
#define	DEFAULT_MANAGER_PORT   5038
#define	EVENT_FLAG_AGENT   (1 << 5)
#define	EVENT_FLAG_CALL   (1 << 1)
#define	EVENT_FLAG_COMMAND   (1 << 4)
#define	EVENT_FLAG_CONFIG   (1 << 7)
#define	EVENT_FLAG_LOG   (1 << 2)
#define	EVENT_FLAG_SYSTEM   (1 << 0)
#define	EVENT_FLAG_USER   (1 << 6)
#define	EVENT_FLAG_VERBOSE   (1 << 3)
Functions
int	ast_manager_register2 (const char *action, int authority, int(*func)(struct mansession *s, const struct message *m), const char *synopsis, const char *description)
	register a new command with manager, including online help. This is the preferred way to register a manager command
int	ast_manager_unregister (char *action)
void	astman_append (struct mansession *s, const char *fmt,...)
const char *	astman_get_header (const struct message *m, char *var)
struct ast_variable *	astman_get_variables (const struct message *m)
void	astman_send_ack (struct mansession *s, const struct message *m, char *msg)
void	astman_send_error (struct mansession *s, const struct message *m, char *error)
void	astman_send_response (struct mansession *s, const struct message *m, char *resp, char *msg)
int	astman_verify_session_readpermissions (uint32_t ident, int perm)
	Verify a session's read permissions against a permission mask.
int	astman_verify_session_writepermissions (uint32_t ident, int perm)
	Verify a session's write permissions against a permission mask.
int	init_manager (void)
int	manager_event (int category, const char *event, const char *contents,...)
	manager_event: Send AMI event to client
int	reload_manager (void)

---

Detailed Description

The AMI - Asterisk Manager Interface - is a TCP protocol created to manage Asterisk with third-party software.

Manager protocol packages are text fields of the form a: b. There is always exactly one space after the colon.

The first header type is the "Event" header. Other headers vary from event to event. Headers end with standard
termination. The last line of the manager response or event is an empty line. (
)

Please try to re-use existing headers to simplify manager message parsing in clients. Don't re-use an existing header with a new meaning, please. You can find a reference of standard headers in doc/manager.txt

Definition in file manager.h.

---

Define Documentation

#define ast_manager_register	(	a,
		b,
		c,
		d		)	ast_manager_register2(a, b, c, d, NULL)

Definition at line 85 of file manager.h.

Referenced by astdb_init(), init_manager(), and load_module().

#define AST_MAX_MANHEADERS   128

Definition at line 60 of file manager.h.

Referenced by do_message(), and generic_http_callback().

#define DEFAULT_MANAGER_PORT   5038

Definition at line 48 of file manager.h.

Referenced by init_manager().

#define EVENT_FLAG_AGENT   (1 << 5)

Definition at line 55 of file manager.h.

Referenced by __login_exec(), action_agent_callback_login(), add_to_queue(), agent_logoff_maintenance(), load_module(), record_abandoned(), remove_from_queue(), ring_entry(), set_member_paused(), try_calling(), and update_status().

#define EVENT_FLAG_CALL   (1 << 1)

Definition at line 51 of file manager.h.

Referenced by ast_change_name(), ast_channel_alloc(), ast_channel_bridge(), ast_do_masquerade(), ast_hangup(), ast_setstate(), change_hold_state(), conf_run(), fast_originate(), init_manager(), join_queue(), leave_queue(), load_module(), manager_log(), manager_state_cb(), notify_new_message(), park_call_full(), park_exec(), pbx_extension_helper(), post_manager_event(), realtime_exec(), report_new_callerid(), send_talking_event(), senddialevent(), socket_process(), and vm_execmain().

#define EVENT_FLAG_COMMAND   (1 << 4)

Definition at line 54 of file manager.h.

Referenced by init_manager().

#define EVENT_FLAG_CONFIG   (1 << 7)

Definition at line 57 of file manager.h.

Referenced by init_manager().

#define EVENT_FLAG_LOG   (1 << 2)

Definition at line 52 of file manager.h.

#define EVENT_FLAG_SYSTEM   (1 << 0)

Definition at line 50 of file manager.h.

Referenced by __expire_registry(), __iax2_poke_noanswer(), ast_log(), astdb_init(), dahdi_handle_event(), expire_register(), handle_alarms(), handle_init_event(), handle_response_peerpoke(), handle_response_register(), iax2_ack_registry(), load_module(), main(), parse_register_contact(), process_message(), quit_handler(), register_verify(), reload_config(), reload_logger(), reload_manager(), sip_poke_noanswer(), sip_reg_timeout(), socket_process(), ss_thread(), and update_registry().

#define EVENT_FLAG_USER   (1 << 6)

Definition at line 56 of file manager.h.

Referenced by action_userevent(), aji_log_hook(), init_manager(), and userevent_exec().

#define EVENT_FLAG_VERBOSE   (1 << 3)

Definition at line 53 of file manager.h.

---

Function Documentation

int astman_verify_session_readpermissions	(	uint32_t	ident,
		int	perm
	)

Verify a session's read permissions against a permission mask.

Parameters:

	ident	session identity
	perm	permission mask to verify

Returns:

1 if the session has the permission mask capabilities, otherwise 0

Definition at line 2841 of file manager.c.

References mansession_session::__lock, AST_LIST_LOCK, AST_LIST_TRAVERSE, AST_LIST_UNLOCK, ast_mutex_lock(), ast_mutex_unlock(), mansession_session::list, mansession_session::managerid, mansession_session::readperm, and s.

{
   int result = 0;
   struct mansession_session *s;

   AST_LIST_LOCK(&sessions);
   AST_LIST_TRAVERSE(&sessions, s, list) {
      ast_mutex_lock(&s->__lock);
      if ((s->managerid == ident) && (s->readperm & perm)) {
         result = 1;
         ast_mutex_unlock(&s->__lock);
         break;
      }
      ast_mutex_unlock(&s->__lock);
   }
   AST_LIST_UNLOCK(&sessions);
   return result;
}

int astman_verify_session_writepermissions	(	uint32_t	ident,
		int	perm
	)

Verify a session's write permissions against a permission mask.

Parameters:

	ident	session identity
	perm	permission mask to verify

Returns:

1 if the session has the permission mask capabilities, otherwise 0

Definition at line 2860 of file manager.c.

References mansession_session::__lock, AST_LIST_LOCK, AST_LIST_TRAVERSE, AST_LIST_UNLOCK, ast_mutex_lock(), ast_mutex_unlock(), mansession_session::list, mansession_session::managerid, s, and mansession_session::writeperm.

{
   int result = 0;
   struct mansession_session *s;

   AST_LIST_LOCK(&sessions);
   AST_LIST_TRAVERSE(&sessions, s, list) {
      ast_mutex_lock(&s->__lock);
      if ((s->managerid == ident) && (s->writeperm & perm)) {
         result = 1;
         ast_mutex_unlock(&s->__lock);
         break;
      }
      ast_mutex_unlock(&s->__lock);
   }
   AST_LIST_UNLOCK(&sessions);
   return result;
}

int init_manager

(

void

)

Called by Asterisk initialization

Definition at line 3129 of file manager.c.

References accept_thread(), action_command(), action_events(), action_extensionstate(), action_getconfig(), action_getvar(), action_hangup(), action_listcommands(), action_logoff(), action_mailboxcount(), action_mailboxstatus(), action_originate(), action_ping(), action_redirect(), action_setvar(), action_status(), action_timeout(), action_updateconfig(), action_userevent(), action_waitevent(), append_event(), ast_calloc, ast_category_browse(), ast_cli_register_multiple(), ast_config_destroy(), ast_config_load(), ast_copy_string(), ast_extension_state_add(), ast_get_manager_by_name_locked(), ast_http_uri_link(), ast_http_uri_unlink(), AST_LIST_INSERT_TAIL, AST_LIST_LOCK, AST_LIST_REMOVE_CURRENT, AST_LIST_TRAVERSE_SAFE_BEGIN, AST_LIST_TRAVERSE_SAFE_END, AST_LIST_UNLOCK, ast_log(), ast_manager_register, ast_manager_register2(), ast_pthread_create_background, ast_strdup, ast_true(), ast_variable_browse(), ast_variable_retrieve(), ast_verbose(), cli_manager, DEFAULT_MANAGER_PORT, ast_manager_user::deny, ast_manager_user::displayconnects, errno, EVENT_FLAG_CALL, EVENT_FLAG_COMMAND, EVENT_FLAG_CONFIG, EVENT_FLAG_USER, ast_channel::flags, free, ast_manager_user::keep, mansession_session::list, LOG_DEBUG, LOG_NOTICE, LOG_WARNING, manager_state_cb(), manageruri, managerxmluri, mandescr_command, mandescr_events, mandescr_extensionstate, mandescr_getconfig, mandescr_getvar, mandescr_hangup, mandescr_listcommands, mandescr_logoff, mandescr_mailboxcount, mandescr_mailboxstatus, mandescr_originate, mandescr_ping, mandescr_redirect, mandescr_setvar, mandescr_timeout, mandescr_updateconfig, mandescr_userevent, mandescr_waitevent, ast_variable::name, ast_variable::next, option_verbose, ast_manager_user::permit, rawmanuri, ast_manager_user::read, registered, ast_manager_user::secret, ast_manager_user::username, ast_variable::value, var, webregged, and ast_manager_user::write.

Referenced by main(), and reload_manager().

{
   struct ast_config *cfg = NULL, *ucfg = NULL;
   const char *val;
   char *cat = NULL;
   int oldportno = portno;
   static struct sockaddr_in ba;
   int x = 1;
   int flags;
   int webenabled = DEFAULT_WEBENABLED;
   int newhttptimeout = DEFAULT_HTTPTIMEOUT;
   struct ast_manager_user *user = NULL;

   if (!registered) {
      /* Register default actions */
      ast_manager_register2("Ping", 0, action_ping, "Keepalive command", mandescr_ping);
      ast_manager_register2("Events", 0, action_events, "Control Event Flow", mandescr_events);
      ast_manager_register2("Logoff", 0, action_logoff, "Logoff Manager", mandescr_logoff);
      ast_manager_register2("Hangup", EVENT_FLAG_CALL, action_hangup, "Hangup Channel", mandescr_hangup);
      ast_manager_register("Status", EVENT_FLAG_CALL, action_status, "Lists channel status" );
      ast_manager_register2("Setvar", EVENT_FLAG_CALL, action_setvar, "Set Channel Variable", mandescr_setvar );
      ast_manager_register2("Getvar", EVENT_FLAG_CALL, action_getvar, "Gets a Channel Variable", mandescr_getvar );
      ast_manager_register2("GetConfig", EVENT_FLAG_CONFIG, action_getconfig, "Retrieve configuration", mandescr_getconfig);
      ast_manager_register2("UpdateConfig", EVENT_FLAG_CONFIG, action_updateconfig, "Update basic configuration", mandescr_updateconfig);
      ast_manager_register2("Redirect", EVENT_FLAG_CALL, action_redirect, "Redirect (transfer) a call", mandescr_redirect );
      ast_manager_register2("Originate", EVENT_FLAG_CALL, action_originate, "Originate Call", mandescr_originate);
      ast_manager_register2("Command", EVENT_FLAG_COMMAND, action_command, "Execute Asterisk CLI Command", mandescr_command );
      ast_manager_register2("ExtensionState", EVENT_FLAG_CALL, action_extensionstate, "Check Extension Status", mandescr_extensionstate );
      ast_manager_register2("AbsoluteTimeout", EVENT_FLAG_CALL, action_timeout, "Set Absolute Timeout", mandescr_timeout );
      ast_manager_register2("MailboxStatus", EVENT_FLAG_CALL, action_mailboxstatus, "Check Mailbox", mandescr_mailboxstatus );
      ast_manager_register2("MailboxCount", EVENT_FLAG_CALL, action_mailboxcount, "Check Mailbox Message Count", mandescr_mailboxcount );
      ast_manager_register2("ListCommands", 0, action_listcommands, "List available manager commands", mandescr_listcommands);
      ast_manager_register2("UserEvent", EVENT_FLAG_USER, action_userevent, "Send an arbitrary event", mandescr_userevent);
      ast_manager_register2("WaitEvent", 0, action_waitevent, "Wait for an event to occur", mandescr_waitevent);

      ast_cli_register_multiple(cli_manager, sizeof(cli_manager) / sizeof(struct ast_cli_entry));
      ast_extension_state_add(NULL, NULL, manager_state_cb, NULL);
      registered = 1;
      /* Append placeholder event so master_eventq never runs dry */
      append_event("Event: Placeholder\r\n\r\n", 0);
   }

   portno = DEFAULT_MANAGER_PORT;
   displayconnects = DEFAULT_DISPLAYCONNECTS;
   broken_events_action = DEFAULT_BROKENEVENTSACTION;
   block_sockets = DEFAULT_BLOCKSOCKETS;
   timestampevents = DEFAULT_TIMESTAMPEVENTS;
   httptimeout = DEFAULT_HTTPTIMEOUT;
   authtimeout = DEFAULT_AUTHTIMEOUT;
   authlimit = DEFAULT_AUTHLIMIT;

   cfg = ast_config_load("manager.conf");
   if (!cfg) {
      ast_log(LOG_NOTICE, "Unable to open management configuration manager.conf.  Call management disabled.\n");
      return 0;
   }
   val = ast_variable_retrieve(cfg, "general", "enabled");
   if (val)
      enabled = ast_true(val);

   val = ast_variable_retrieve(cfg, "general", "block-sockets");
   if (val)
      block_sockets = ast_true(val);

   val = ast_variable_retrieve(cfg, "general", "webenabled");
   if (val)
      webenabled = ast_true(val);

   if ((val = ast_variable_retrieve(cfg, "general", "port"))) {
      if (sscanf(val, "%5d", &portno) != 1) {
         ast_log(LOG_WARNING, "Invalid port number '%s'\n", val);
         portno = DEFAULT_MANAGER_PORT;
      }
   }

   if ((val = ast_variable_retrieve(cfg, "general", "displayconnects")))
      displayconnects = ast_true(val);

   if ((val = ast_variable_retrieve(cfg, "general", "brokeneventsaction")))
      broken_events_action = ast_true(val);

   if ((val = ast_variable_retrieve(cfg, "general", "timestampevents")))
      timestampevents = ast_true(val);

   if ((val = ast_variable_retrieve(cfg, "general", "httptimeout")))
      newhttptimeout = atoi(val);

   if ((val = ast_variable_retrieve(cfg, "general", "authtimeout"))) {
      int timeout = atoi(val);

      if (timeout < 1) {
         ast_log(LOG_WARNING, "Invalid authtimeout value '%s', using default value\n", val);
      } else {
         authtimeout = timeout;
      }
   }

   if ((val = ast_variable_retrieve(cfg, "general", "authlimit"))) {
      int limit = atoi(val);

      if (limit < 1) {
         ast_log(LOG_WARNING, "Invalid authlimit value '%s', using default value\n", val);
      } else {
         authlimit = limit;
      }
   }

   memset(&ba, 0, sizeof(ba));
   ba.sin_family = AF_INET;
   ba.sin_port = htons(portno);

   if ((val = ast_variable_retrieve(cfg, "general", "bindaddr"))) {
      if (!inet_aton(val, &ba.sin_addr)) { 
         ast_log(LOG_WARNING, "Invalid address '%s' specified, using 0.0.0.0\n", val);
         memset(&ba.sin_addr, 0, sizeof(ba.sin_addr));
      }
   }
   

   if ((asock > -1) && ((portno != oldportno) || !enabled)) {
#if 0
      /* Can't be done yet */
      close(asock);
      asock = -1;
#else
      ast_log(LOG_WARNING, "Unable to change management port / enabled\n");
#endif
   }

   AST_LIST_LOCK(&users);

   if ((ucfg = ast_config_load("users.conf"))) {
      while ((cat = ast_category_browse(ucfg, cat))) {
         int hasmanager = 0;
         struct ast_variable *var = NULL;

         if (!strcasecmp(cat, "general")) {
            continue;
         }

         if (!(hasmanager = ast_true(ast_variable_retrieve(ucfg, cat, "hasmanager")))) {
            continue;
         }

         /* Look for an existing entry, if none found - create one and add it to the list */
         if (!(user = ast_get_manager_by_name_locked(cat))) {
            if (!(user = ast_calloc(1, sizeof(*user)))) {
               break;
            }
            /* Copy name over */
            ast_copy_string(user->username, cat, sizeof(user->username));
            /* Insert into list */
            AST_LIST_INSERT_TAIL(&users, user, list);
         }

         /* Make sure we keep this user and don't destroy it during cleanup */
         user->keep = 1;

         for (var = ast_variable_browse(ucfg, cat); var; var = var->next) {
            if (!strcasecmp(var->name, "secret")) {
               if (user->secret) {
                  free(user->secret);
               }
               user->secret = ast_strdup(var->value);
            } else if (!strcasecmp(var->name, "deny") ) {
               if (user->deny) {
                  free(user->deny);
               }
               user->deny = ast_strdup(var->value);
            } else if (!strcasecmp(var->name, "permit") ) {
               if (user->permit) {
                  free(user->permit);
               }
               user->permit = ast_strdup(var->value);
            } else if (!strcasecmp(var->name, "read") ) {
               if (user->read) {
                  free(user->read);
               }
               user->read = ast_strdup(var->value);
            } else if (!strcasecmp(var->name, "write") ) {
               if (user->write) {
                  free(user->write);
               }
               user->write = ast_strdup(var->value);
            } else if (!strcasecmp(var->name, "displayconnects") ) {
               user->displayconnects = ast_true(var->value);
            } else if (!strcasecmp(var->name, "hasmanager")) {
               /* already handled */
            } else {
               ast_log(LOG_DEBUG, "%s is an unknown option (to the manager module).\n", var->name);
            }
         }
      }
      ast_config_destroy(ucfg);
   }

   while ((cat = ast_category_browse(cfg, cat))) {
      struct ast_variable *var = NULL;

      if (!strcasecmp(cat, "general"))
         continue;

      /* Look for an existing entry, if none found - create one and add it to the list */
      if (!(user = ast_get_manager_by_name_locked(cat))) {
         if (!(user = ast_calloc(1, sizeof(*user))))
            break;
         /* Copy name over */
         ast_copy_string(user->username, cat, sizeof(user->username));
         /* Insert into list */
         AST_LIST_INSERT_TAIL(&users, user, list);
      }

      /* Make sure we keep this user and don't destroy it during cleanup */
      user->keep = 1;

      var = ast_variable_browse(cfg, cat);
      while (var) {
         if (!strcasecmp(var->name, "secret")) {
            if (user->secret)
               free(user->secret);
            user->secret = ast_strdup(var->value);
         } else if (!strcasecmp(var->name, "deny") ) {
            if (user->deny)
               free(user->deny);
            user->deny = ast_strdup(var->value);
         } else if (!strcasecmp(var->name, "permit") ) {
            if (user->permit)
               free(user->permit);
            user->permit = ast_strdup(var->value);
         }  else if (!strcasecmp(var->name, "read") ) {
            if (user->read)
               free(user->read);
            user->read = ast_strdup(var->value);
         }  else if (!strcasecmp(var->name, "write") ) {
            if (user->write)
               free(user->write);
            user->write = ast_strdup(var->value);
         }  else if (!strcasecmp(var->name, "displayconnects") )
            user->displayconnects = ast_true(var->value);
         else
            ast_log(LOG_DEBUG, "%s is an unknown option.\n", var->name);
         var = var->next;
      }
   }

   /* Perform cleanup - essentially prune out old users that no longer exist */
   AST_LIST_TRAVERSE_SAFE_BEGIN(&users, user, list) {
      if (user->keep) {
         user->keep = 0;
         continue;
      }
      /* We do not need to keep this user so take them out of the list */
      AST_LIST_REMOVE_CURRENT(&users, list);
      /* Free their memory now */
      if (user->secret)
         free(user->secret);
      if (user->deny)
         free(user->deny);
      if (user->permit)
         free(user->permit);
      if (user->read)
         free(user->read);
      if (user->write)
         free(user->write);
      free(user);
   }
   AST_LIST_TRAVERSE_SAFE_END

   AST_LIST_UNLOCK(&users);

   ast_config_destroy(cfg);
   
   if (webenabled && enabled) {
      if (!webregged) {
         ast_http_uri_link(&rawmanuri);
         ast_http_uri_link(&manageruri);
         ast_http_uri_link(&managerxmluri);
         webregged = 1;
      }
   } else {
      if (webregged) {
         ast_http_uri_unlink(&rawmanuri);
         ast_http_uri_unlink(&manageruri);
         ast_http_uri_unlink(&managerxmluri);
         webregged = 0;
      }
   }

   if (newhttptimeout > 0)
      httptimeout = newhttptimeout;

   /* If not enabled, do nothing */
   if (!enabled)
      return 0;

   if (asock < 0) {
      asock = socket(AF_INET, SOCK_STREAM, 0);
      if (asock < 0) {
         ast_log(LOG_WARNING, "Unable to create socket: %s\n", strerror(errno));
         return -1;
      }
      setsockopt(asock, SOL_SOCKET, SO_REUSEADDR, &x, sizeof(x));
      if (bind(asock, (struct sockaddr *)&ba, sizeof(ba))) {
         ast_log(LOG_WARNING, "Unable to bind socket: %s\n", strerror(errno));
         close(asock);
         asock = -1;
         return -1;
      }
      if (listen(asock, 2)) {
         ast_log(LOG_WARNING, "Unable to listen on socket: %s\n", strerror(errno));
         close(asock);
         asock = -1;
         return -1;
      }
      flags = fcntl(asock, F_GETFL);
      fcntl(asock, F_SETFL, flags | O_NONBLOCK);
      if (option_verbose)
         ast_verbose("Asterisk Management interface listening on port %d\n", portno);
      ast_pthread_create_background(&t, NULL, accept_thread, NULL);
   }
   return 0;
}

int reload_manager

(

void

)

Definition at line 3452 of file manager.c.

References EVENT_FLAG_SYSTEM, init_manager(), and manager_event().

{
   manager_event(EVENT_FLAG_SYSTEM, "Reload", "Message: Reload Requested\r\n");
   return init_manager();
}