Thu Oct 11 06:44:30 2012

Asterisk developer's documentation


ARA - The Asterisk Realtime Interface

ARA - a generic API to storage and retrieval

Implemented in config.c Implemented in pbx_realtime.c
The Asterisk Realtime Architecture
----------------------------------

The Asterisk Realtime Architecture is a new set of drivers and 
functions implemented in Asterisk.

The benefits of this architecture are many, both from a code management
standpoint and from an installation perspective. 

Additional information on the configuration of Realtime with Asterisk 
can be found in doc/extconfig.txt

The ARA is designed to be independent of storage. Currently, most
drivers are based on SQL, but the architecture should be able to handle
other storage methods in the future, like LDAP.

The main benefit comes in the database support. In Asterisk v1.0 some 
functions supported MySQL database, some PostgreSQL and other ODBC.
With the ARA, we have a unified database interface internally in Asterisk,
so if one function supports database integration, all databases that has a 
realtime driver will be supported in that function.

Currently there are three realtime database drivers:

* ODBC: Support for UnixODBC, integrated into Asterisk
  The UnixODBC subsystem supports many different databases,
  please check www.unixodbc.org for more information.
* MySQL: Found in the asterisk-addons subversion repository on svn.digium.com
* PostgreSQL: Native support for Postgres, integrated into Asterisk

* Two modes: Static and Realtime
--------------------------------
The ARA realtime mode is used to dynamically load and update objects.
This mode is used in the SIP and IAX2 channels, as well as in the voicemail
system. For SIP and IAX2 this is similar to the v1.0 MYSQL_FRIENDS 
functionality. With the ARA, we now support many more databases for
dynamic configuration of phones.

The ARA static mode is used to load configuration files. For the Asterisk
modules that read configurations, there's no difference between a static
file in the file system, like extensions.conf, and a configuration loaded
from a database.

You just have to always make sure the var_metric values are properly set and
ordered as you expect in your database server if you're using the static mode
with ARA (either sequentially or with the same var_metric value for everybody).

If you have an option that depends on another one in a given configuration
file (i.e, 'musiconhold' depending on 'agent' from agents.conf) but their
var_metric are not sequential you'll probably get default values being assigned for
those options instead of the desired ones. You can still use the same
var_metric for all entries in your DB, just make sure the entries
are recorded in an order that does not break the option dependency.

That doesn't happen when you use a static file in the file system. Although
this might be interpreted as a bug or limitation, it is not.

* Realtime SIP friends
----------------------
The SIP realtime objects are users and peers that are loaded in memory 
when needed, then deleted. This means that Asterisk currently can't handle
voicemail notification and NAT keepalives for these peers. Other than that,
most of the functionality works the same way for realtime friends as for
the ones in static configuration.

With caching, the device stays in memory for a specified time. More 
information about this is to be found in the sip.conf sample file.

* Realtime H.323 friends
------------------------
Like SIP realtime friends, H.323 friends also can be configured using
dynamic realtime objects.

* New function in the dial plan: The Realtime Switch
----------------------------------------------------
The realtime switch is more than a port of functionality in v1.0 to the
new architecture, this is a new feature of Asterisk based on the 
ARA. The realtime switch lets your Asterisk server do database lookups
of extensions in realtime from your dial plan. You can have many Asterisk
servers sharing a dynamically updated dial plan in real time with this
solution.

Note that this switch does _NOT_ support Caller ID matching, only
extension name/pattern matching.

* So what can you do?
---------------------
The realtime Architecture lets you store all of your configuration in
databases and reload it whenever you want. You can force a reload over
the AMI, Asterisk Manager Interface or by calling Asterisk from a 
shell script with 
	asterisk -rx "reload"

You may also dynamically add SIP and IAX devices and extensions 
and making them available without a reload, by using the realtime
objects and the realtime switch.


* Configuration in extconfig.conf
---------------------------------
You configure the ARA in extconfig.conf (yes, it's a strange name, but
is was defined in the early days of the realtime architecture and kind
of stuck). Please see doc/extconfig.txt for database schemas.

The part of Asterisk that connects to the ARA use a well defined family
name to find the proper database driver. The syntax is easy:
   <family> => <realtime driver>,<db name>[,<table>]

The options following the realtime driver identified depends on the
driver.

Defined well-known family names are:

* sippeers, sipusers	SIP peers and users
* iaxpeers, iaxusers	IAX2 peers and users
* voicemail		Voicemail accounts 
* queues		Queues
* queue_members		Queue members
* extensions		Realtime extensions (switch)

There is documentation of the SQL database in the file
doc/extconfig.txt in your Asterisk source code tree.

For voicemail storage with the support of ODBC, there is a 
doc/odbcstorage.txt documentation file.


* Limitations
-------------
Currently, realtime extensions do not support realtime hints.


* FreeTDS supported with connection pooling
-------------------------------------------
In order to use a FreeTDS-based database with realtime, you need to turn
connection pooling on in res_odbc.conf.  This is due to a limitation within
the FreeTDS protocol itself.  Please note that this includes databases such
as MS SQL Server and Sybase.  This support is new in the current release.
Asterisk external configuration
===============================

The Asterisk external configuration engine is the result of work by
Anthony Minessale II, Mark Spencer and Constantine Filin.

It is designed to provide a flexible, seamless integration between
Asterisk's internal configuration structure and external SQL other other
databases (maybe even LDAP one day).

The external configuration engine is the basis for the ARA, the
Asterisk Realtime Architecture (see doc/realtime.txt for more 
information).

* Configuration

External configuration is configured in /etc/asterisk/extconfig.conf
allowing you to map any configuration file (static mappings) to
be pulled from the database, or to map special runtime entries which
permit the dynamic creation of objects, entities, peers, etc. without
the necessity of a reload.

Generally speaking, the columns in your tables should line up with the
fields you would specify in the given entity declaration.  If an entry
would appear more than once, in the column it should be separated by a
semicolon. For example, an entity that looks like:

[foo]
host=dynamic
secret=bar
context=default
context=local

could be stored in a table like this:

+------+--------+-------+--------------+----------+-----+-----------+
| name | host   | secret| context      | ipaddr   | port| regseconds|
+------+--------+-------+--------------+----------+-----+-----------+
| foo  | dynamic|  bar  | default;local| 127.0.0.1| 4569| 1096954152|
+------+--------+-------+--------------+----------+-----+-----------+

Note that for use with IAX or SIP, the table will also need the "name", 
"ipaddr", "port", "regseconds" columns.  If you wanted to be able to 
configure the callerid, you could just add a callerid column to the 
table, for example.

A SIP table would look more like this:

+------+--------+-------+----------+-----+------------+----------+
| name | host   | secret| ipaddr   | port| regseconds | username |
+------+--------+-------+----------+-----+------------+----------+
| foo  | dynamic|  bar  | 127.0.0.1| 4569| 1096954152 |   1234   |
+------+--------+-------+----------+-----+------------+----------+

in order to store appropriate parameters required for SIP.

In addition to this, if you add a field named "regserver" to the
SIP peers table and have the system name set in asterisk.conf, 
Asterisk will store the system name that the user registered on in 
the database. This can be used to direct calls to go through the server 
that holds the registration (for NAT traversal purposes).

A Voicemail table would look more like this:

+----------+---------+----------+----------+-----------+---------------+
| uniqueid | mailbox | context  | password |email      |   fullname    | 
+----------+---------+----------+----------+-----------+---------------+
|        1 |   1234  | default  |  4242    | a@b.com   | Joe Schmoe    | 
+----------+---------+----------+----------+-----------+---------------+

The uniqueid should be unique to each voicemail user and can be 
autoincrement.  It need not have any relation to the mailbox or context.

An extension table would look more like this:

+----------+---------+----------+-------+-----------+
| context  |  exten  | priority |  app  |  appdata  |
+----------+---------+----------+-------+-----------+
|  default |    1234 |        1 |  Dial |     Zap/1 |
+----------+---------+----------+-------+-----------+

In the dialplan you just use the Realtime switch:

[foo]
switch => Realtime

or:

[bar]
switch => Realtime/bar@extensions


Generated on Thu Oct 11 06:44:30 2012 for Asterisk - the Open Source PBX by  doxygen 1.5.6