Replacing the Asterisk Manager Interface and CLI
Telephony Software Architecture Document
The two papers presented here introduce a three-tier remote control architecture to replace both the Asterisk Manager Interface and the Asterisk CLI with a client-agent-server model.
Remote Control Architecture for Asterisk derived Telephony Servers
A Remote Control Architecture for Asterisk derived Telephony Servers
Document version: 1.01
Author: Benjamin Kowarsch
Copyright (c) 2006 Sunrise Telephone Systems Ltd., Tokyo, Japan
Permission is hereby granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, GFDL Version 1.2.
This Document is provided "as is" without any warranty of any kind.
1) Objectives
The prime objective of the remote control architecture is to free the telephony
server from any tasks which are related to handling remote interfaces so that
it has all its resource available to providing telephony services.
Both the presence of an embedded CLI and the embedded network socket interface
for remote control, such as the Asterisk Manager Interface are in violation of
this objective and consequently they should be removed from the telephony
server altogether.
The remote control architecture is to provide a replacement mechanism for both
the embedded CLI and the Manager Interface. It will also provide a mechanism
for additional remote monitoring and control services utilising SOAP, XML-RPC
and IM protocol based interfaces.
2) Local CLI via UNIX domain socket based client/server architecture
As a replacement for the embedded CLI, the new architecture introduces a
separate standalone CLI utility which will connect via UNIX domain sockets
to the telephony server.
+----------------+ +----------------+
| telephony | <---------- client requests ----------- | server |
| server | ----------- server responses ---------> | CLI utility |
+----------------+ +----------------+
Under the new architecture, the telephony server will no longer load any
information about command syntax and command help of loadable modules, nor
will it have any information about command syntax and command help of any
built-in features. Command syntax and command help will be entirely removed
from the codebase. Instead, syntax and help descriptions will be stored in
property lists, one for each loadable module and one for built-in features.
The telephony server will maintain a list of currently loaded modules on disk
and it will inform connecting clients about the location of this list. When
a client in need of this information connects to the server, it will obtain
the location from the server and load it into its own loaded module cache.
Whenever the server loads or unloads one or more modules, it will notify all
connected clients that a change has occurred and the clients will then update
their local caches accordingly.
In addition, the telephony server will also provide the location of the
property lists containing the descriptions of command syntax and command help.
Again, when a client in need of this information connects to the server, it
will obtain the location from the server and load the relevant property lists
into its own local cache.
As a result, the telephony server is entirely relieved of the task to evaluate
command syntax and provide command help. Instead, command evaluation and help
can be done entirely in the CLI client without any involvement by the server.
+----------------+ +----------------+
| telephony | <---- loaded module info request ------ | server |
| server | ---- module info location response ---> | CLI utility |
+----------------+ +----------------+
| ^
| +----------------+ |
+-----------------> | list of | --- obtain list ----+
| loaded modules | |
+----------------+ |
|
+----------------+ +----------------+ |
| loadable | --------> | command syntax | --- obtain plists --+
| modules | | and help |
+----------------+ | property lists |
+----------------+
3) Remote CLI via network socket based client/agent/server architecture
As a replacement for the Manager Interface, the new architecture introduces a
separate standalone agent which will connect via UNIX domain sockets to the
telephony server and accept connections from clients via network sockets.
+-------------+ +-------------+ +-------------+
| telephony | <- requests -- | proxy | <- requests -- | remote |
| server | - responses -> | agent | - responses -> | client |
+-------------+ +-------------+ +-------------+
UNIX domain TCP/IP
socket socket
For each protocol to be supported, a specific agent can be provided which acts
as a proxy between clients and the telephony server. A SOAP/http agent would
provide a SOAP interface for remote SOAP based clients while an XML-RPC/http
agent would provide an XML-RPC interface for remote XML-RPC based clients.
+-------------+ +-------------+ SOAP +-------------+
| telephony | <- requests -- | SOAP | <- requests -- | SOAP |
| server | - responses -> | http agent | - responses -> | client |
+-------------+ +-------------+ +-------------+
UNIX domain TCP/IP
socket socket
+-------------+ +-------------+ XML-RPC +-------------+
| telephony | <- requests -- | XML-RPC | <- requests -- | XML-RPC |
| server | - responses -> | http agent | - responses -> | client |
+-------------+ +-------------+ +-------------+
UNIX domain TCP/IP
socket socket
Further agents could be provided for IM based protocols, such as Jabber.
+-------------+ +-------------+ Jabber +-------------+
| telephony | <- requests -- | Jabber | <- requests -- | Jabber |
| server | - responses -> | agent | - responses -> | client |
+-------------+ +-------------+ +-------------+
UNIX domain TCP/IP
socket socket
4) Security
UNIX domain socket based connections between the telephony server and local
CLI utilities or agents can take advantage of the local filesystem's built-in
access control system such as file permissions and ACLs. In addition to the
filesystem's access control, the telephony server can maintain a list of
names of executables which should be permitted to connect. The UNIX domain
socket system also allows the server to obtain information about the
processes and users running the executables which are trying to connect.
The server can use this information for more advanced access control.
For TCP/IP socket based connections between remote clients and agents, a
system of user authentication is to be used. Passwords should never be sent
in clear between clients and agents. Either an MD5 challenge-response or a
PKI based scheme is to be used to authenticate clients. A role based access
system is to be used to grant different levels of access to different types
of clients.
// END OF DOCUMENT
Click here to download this document.
Telephony Server CLI Utility Specification
Telephony Server CLI utility - Specification
Document version: 1.0
Author: Benjamin Kowarsch
Copyright (c) 2006 Sunrise Telephone Systems Ltd., Tokyo, Japan
Permission is hereby granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, GFDL Version 1.2.
This Document is provided "as is" without any warranty of any kind.
1) Objective
The objective of this subproject is to remove the embedded command line
interface (CLI) from Asterisk derived telephony servers and to provide a
replacement facility in form of a standalone command line utility that acts
as a client front-end.
2) Command line options
The CLI utility shall provide the following command line options:
-h and --help, to print a brief online help
-v and --version, to print the utility's version number
-c and --command, to execute a single command and exit
-i and --interactive, to invoke the utility in interactive mode
The default behaviour to exhibit when the utility is called without any
arguments shall be determined by a setting in the utility's property list
configuration file. If no configuration file is present and the utility is
called without any arguments, the help option shall be the default.
3) Configuration file settings
The CLI utility shall have its own configuration file which shall be in
property list format. The utility should not use Windows INI format or
the Windows derived Asterisk INI format for its configuration.
The utility shall read the following settings from its configuration file:
o default mode, mode to use when the utility is called without arguments
o server socket, full path to the server's UNIX domain socket
o inactivity timeout, duration of inactivity after which to disconnect
o timestamp flag, whether or not to print output with time stamps
o prompt, CLI prompt to display when in interactive mode
An example property list configuration is shown below:
CLIconfig = {
DefaultMode = interactive; /* interactive or command */
ServerSocket = "/foo/bar/baz/srvctl";
InactivityTimeout = 0;
PrintTimestamps = yes;
Prompt = "CLI>";
};
4) Startup sequence
The CLI utility shall use the following startup sequence when it is
launched ...
First it shall evaluate any command line arguments, then proceed as follows:
o when invoked with the help option it shall print a brief online help,
then exit.
o when invoked with the version option it shall print the name of the
utility followed by its version number, then exit.
o when invoked with the single command option it shall read its configuration
file to obtain the path to the server socket, connect to the server and
request a list of loaded modules and their property lists. It shall then
read the list and property lists to obtain the syntax of the command
provided in the argument string. It shall then proceed to evaluate the
command accordingly and submit the command if it is valid. Finally it
shall read and print the server's response, then exit.
o when invoked with the interactive mode option, it shall print the name and
version of the utility, followed by the copyright and license notice. It
shall then proceed to read its configuration file to obtain and apply the
settings stored therein. It shall then connect to the server and request
a list of loaded modules and their property lists. It shall then read the
list of loaded modules and all property lists in order to obtain the
syntax and online help of all available commands. Finally it shall print
a CLI prompt and notify the user that it is ready for user input.
o when invoked without any command line arguments, it shall read its
configuration file to obtain the default mode setting, then proceed
accordingly. If the default mode cannot be obtained, it shall proceed
as if it had been invoked with the help option.
5) Obtaining information about command syntax and help
The CLI utility shall obtain information about loaded modules, their
commands, syntax and help by sending a request to the server which will
respond with a path to a loaded modules cache which contains the paths
to property lists describing the command syntax and help, one for each
loaded module. The CLI utility shall then read the loeaded module cache
and the property lists for all loaded modules and thereby obtain this
information directly. The server will only provide the location, but
not the information itself.
The CLI utility shall update the module cache whenever it receives
an update notification from the server. The server will provide an update
notification to each connected client whenever a reload has been executed.
/// to be specified: property list format for module command syntax and help
// END OF FILE
Click here to download this document.
