Realtime Database Configuration

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.

Asterisk RealTime

ARA, the Asterisk Realtime Architecture is one of the major new features in Asterisk version 1.2.
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 databases (maybe even LDAP one day).

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.

In the new RealTime architecture, all database specific code is moved to database specific drivers. The channel just calls a generic routine to do database lookup. Much cleaner, simpler and manageable from a coding standpoint.

The database is accessed with three functions:
STATIC: This is used to load static configuration when a module is loaded REALTIME: This is used to lookup objects during a call (or another event) UPDATE: This is used to update objects
The database support in the channel is not changed. There are "normal" static peers/users and database peers/users. The static ones, regardless if these are loaded from a text file or a database configuration, are kept in-memory and in the SIP channel we provide them with NAT traversal support and message waiting indication if needed.

The database peers/users are not kept in memory. These are only loaded when we have a call and then deleted, so there's no support for NAT keep-alives (qualify=) or voicemail indications for these peers.
NOTE: If you enable RealTime caching in your sip.conf, Voicemail MWI works and so does 'sip show peers' - see rtcachefriends=yes. The downside to this is that if you change anything in the database, you need to do a 'sip reload' (for major changes) or 'sip prune realtime PEERNAME' (for single peer changes) before they become active.

In the Stable 1.0.X branch of Asterisk, database storage of configuration files and parameters was done mostly by hardcoding connection and query code directly into the application. The best example of this is in app_voicemail, where you can see MySQL code and PostgreSQL code all meshed with the app_voicemail code.

This method of database retrevial proves to be ugly as all the asterisk code is now crammed with database specific code that is irrelevant to the function of the application at hand. Thus RealTime was developed as a means to remove the code and replace it with a unified (abstracted) database retrevial method.

There are 2 methods of using RealTime: ODBC and MySQL. Yes, you can use ODBC to connect to MySQL and many other ODBC supported databases. (Being an avid MySQL user and advocate, I didn't want to bother with ODBC so I wrote the RealTime MySQL driver over the weekend.) (This paragraph assumes you have ODBC already running and installed on your box.)
When you start to compile Asterisk, the Makefile inside res/ should detect if you have ODBC properly installed and if so compile the res_config_odbc.so module for you (as long as you have the unixODBC-dev libraries installed - http://sourceforge.net/project/showfiles.php?group_id=1544&package_id=122072).
Go into /etc/asterisk/res_odbc.conf and configure your ODBC connections. Some sample configs are supplied in asterisk/configs/res_odbc.conf.sample NOTE: res_config_odbc.conf is deprecated and will not be loaded.

Skip to 'Extconfig'

(This page assumes you have the MySQL client libraries/headers installed on your box.)
Check out asterisk-addons from CVS:

cd /usr/src/
svn co http://svn.digium.com/svn/asterisk-addons/trunk asterisk-addons
Go into asterisk-addons and run the following commands
configure
make
make install (This will also compile and install the other stuff in addons so if you don't want/need it, just run 'make' and manually copy res_config_mysql.so to your modules directory.)

Copy asterisk-addons/configs/res_mysql.conf.sample to /etc/asterisk/res_mysql.conf
Edit this file to your liking. At this time, the MySQL drivers supports multiple databases on only one server.

Now edit /etc/asterisk/extconfig.conf

Static configuration is where you can store regular *.conf files into the database. These configurations are read at Asterisk startup/reload. Some modules may also re-read this info upon their own reload (Ex. sip reload).
Here is the format for a static config: [settings]

=> ,[,table_name]
queues.conf => odbc,asterisk,ast_config
sip.conf => mysql,asterisk
iax.conf => ldap,MyBaseDN,iax

Above we have 3 examples. The first example will bind 'queues.conf' to the table 'ast_config' located in the database context 'asterisk' using the ODBC driver. — NOTE (LN): this is NOT the database you specified in /etc/odbc.ini, rather it's the context in /etc/asterisk/res_odbc.conf that you are using to connect to the ODBC driver!
The second example will bind 'sip.conf' to the table 'sip.conf' (because we ommited the table name, it defaults to the file name) in the database 'asterisk' using the MySQL driver.
The 3rd one will bind iax.conf to the 'table' iax.conf in the ldap database using LDAP driver; MyBaseDN is the base DN for the query.
Using the above examples, now, when app_queue.so loads, the RealTime ODBC driver will execute a query and get the information it needs. The same is true for chan_sip.so, but with MySQL and chan_iax.so with LDAP.

RealTime configuration is where configuration values are read/updated in real time.

Example: Lets say you have 2 SIP users defined in your sip.conf and you want to add a 3rd. You add them to the file then execute the command 'sip reload'. This re-reads your sip.conf and allows the 3rd to register.
With RealTime, all you do is add 1 new record to the table that sipusers has been bound to. No reloading necessary.

RealTime maps take the following fomat:

[settings]

=> ,[,table_name]
sippeers => mysql,asterisk,sip_peers
sipusers => mysql,asterisk,sip_users
queues => mysql,asterisk,queue_table
queue_members => mysql,asterisk,queue_member_table
meetme => mysql,asterisk,meetme_table
voicemail => mysql,asterisk

Above we have four examples. The first example will bind the family name "sippeers" to the table "sip_peers" in the database "asterisk" using the MySQL driver. The last example will bind the family name "voicemail" to the table "voicemail" (because we ommited the table name, it defaults to the family name) in the database "test" using the MySQL driver.

It is worth noting that sipusers and sippeers may both refer to the same table, if you wish.

NOTE: extconfig.conf is parsed each time you connect to the asterisk CLI.

RealTime is great. With a nice web interface you can allow customers limited ability to edit their own dialplan without needing a reload.

RealTime support is currently available for the following families:
sippeers sipusers iaxpeers iaxusers voicemail musiconhold queues and queue_members (used together for the Queue application). extensions NOTE: The family name for RealTime extensions can be whatever you want. Please read Asterisk RealTime Extensions for more info.
More information will be posted as more apps become RealTime enabled. Q: Does anyone know how to send * a semi-colon from a realtime database. I know that * uses the semi-colon as a 'seperator' - but I need to be able to use one in a command. I know I can use \; in the non-realtime configs, but this doesn't work in realtime.

A:
> in /etc/asterisk/extensions.conf
>
> globals
> SEMICOLON=\;
>
> Then use ${SEMICOLON} in realitime.... Hacky, but it's what I'm using at
> the moment..

If you use SVN (upcoming 1.4.37, 1.6.2.14, or 1.8.0), you can encode semicolons in the database as the literal string "^3B".

Go back to Asterisk