doc/realtime.txt

   1 The Asterisk Realtime Architecture
   2 ----------------------------------
   3
   4 The Asterisk Realtime Architecture is a new set of drivers and
   5 functions implemented in Asterisk.
   6
   7 The benefits of this architecture are many, both from a code management
   8 standpoint and from an installation perspective.
   9
  10 Additional information on the configuration of Realtime with Asterisk
  11 can be found in doc/extconfig.txt
  12
  13 The ARA is designed to be independent of storage. Currently, most
  14 drivers are based on SQL, but the architecture should be able to handle
  15 other storage methods in the future, like LDAP.
  16
  17 The main benefit comes in the database support. In Asterisk v1.0 some
  18 functions supported MySQL database, some PostgreSQL and other ODBC.
  19 With the ARA, we have a unified database interface internally in Asterisk,
  20 so if one function supports database integration, all databases that has a
  21 realtime driver will be supported in that function.
  22
  23 Currently there are three realtime database drivers:
  24
  25 * ODBC: Support for UnixODBC, integrated into Asterisk
  26   The UnixODBC subsystem supports many different databases,
  27   please check www.unixodbc.org for more information.
  28 * MySQL: Found in the asterisk-addons subversion repository on svn.digium.com
  29 * PostgreSQL: Native support for Postgres, integrated into Asterisk
  30
  31 * Two modes: Static and Realtime
  32 --------------------------------
  33 The ARA realtime mode is used to dynamically load and update objects.
  34 This mode is used in the SIP and IAX2 channels, as well as in the voicemail
  35 system. For SIP and IAX2 this is similar to the v1.0 MYSQL_FRIENDS
  36 functionality. With the ARA, we now support many more databases for
  37 dynamic configuration of phones.
  38
  39 The ARA static mode is used to load configuration files. For the Asterisk
  40 modules that read configurations, there's no difference between a static
  41 file in the file system, like extensions.conf, and a configuration loaded
  42 from a database.
  43
  44 You just have to always make sure the var_metric values are properly set and
  45 ordered as you expect in your database server if you're using the static mode
  46 with ARA (either sequentially or with the same var_metric value for everybody).
  47
  48 If you have an option that depends on another one in a given configuration
  49 file (i.e, 'musiconhold' depending on 'agent' from agents.conf) but their
  50 var_metric are not sequential you'll probably get default values being assigned for
  51 those options instead of the desired ones. You can still use the same
  52 var_metric for all entries in your DB, just make sure the entries
  53 are recorded in an order that does not break the option dependency.
  54
  55 That doesn't happen when you use a static file in the file system. Although
  56 this might be interpreted as a bug or limitation, it is not.
  57
  58 * Realtime SIP friends
  59 ----------------------
  60 The SIP realtime objects are users and peers that are loaded in memory
  61 when needed, then deleted. This means that Asterisk currently can't handle
  62 voicemail notification and NAT keepalives for these peers. Other than that,
  63 most of the functionality works the same way for realtime friends as for
  64 the ones in static configuration.
  65
  66 With caching, the device stays in memory for a specified time. More
  67 information about this is to be found in the sip.conf sample file.
  68
  69 * Realtime H.323 friends
  70 ------------------------
  71 Like SIP realtime friends, H.323 friends also can be configured using
  72 dynamic realtime objects.
  73
  74 * New function in the dial plan: The Realtime Switch
  75 ----------------------------------------------------
  76 The realtime switch is more than a port of functionality in v1.0 to the
  77 new architecture, this is a new feature of Asterisk based on the
  78 ARA. The realtime switch lets your Asterisk server do database lookups
  79 of extensions in realtime from your dial plan. You can have many Asterisk
  80 servers sharing a dynamically updated dial plan in real time with this
  81 solution.
  82
  83 Note that this switch does _NOT_ support Caller ID matching, only
  84 extension name/pattern matching.
  85
  86 * So what can you do?
  87 ---------------------
  88 The realtime Architecture lets you store all of your configuration in
  89 databases and reload it whenever you want. You can force a reload over
  90 the AMI, Asterisk Manager Interface or by calling Asterisk from a
  91 shell script with
  92         asterisk -rx "reload"
  93
  94 You may also dynamically add SIP and IAX devices and extensions
  95 and making them available without a reload, by using the realtime
  96 objects and the realtime switch.
  97
  98
  99 * Configuration in extconfig.conf
 100 ---------------------------------
 101 You configure the ARA in extconfig.conf (yes, it's a strange name, but
 102 is was defined in the early days of the realtime architecture and kind
 103 of stuck). Please see doc/extconfig.txt for database schemas.
 104
 105 The part of Asterisk that connects to the ARA use a well defined family
 106 name to find the proper database driver. The syntax is easy:
 107    <family> => <realtime driver>,<db name>[,<table>]
 108
 109 The options following the realtime driver identified depends on the
 110 driver.
 111
 112 Defined well-known family names are:
 113
 114 * sippeers, sipusers    SIP peers and users
 115 * iaxpeers, iaxusers    IAX2 peers and users
 116 * voicemail             Voicemail accounts
 117 * queues                Queues
 118 * queue_members         Queue members
 119 * extensions            Realtime extensions (switch)
 120
 121 There is documentation of the SQL database in the file
 122 doc/extconfig.txt in your Asterisk source code tree.
 123
 124 For voicemail storage with the support of ODBC, there is a
 125 doc/odbcstorage.txt documentation file.
 126
 127
 128 * Limitations
 129 -------------
 130 Currently, realtime extensions do not support realtime hints.
 131
 132
 133 * FreeTDS supported with connection pooling
 134 -------------------------------------------
 135 In order to use a FreeTDS-based database with realtime, you need to turn
 136 connection pooling on in res_odbc.conf.  This is due to a limitation within
 137 the FreeTDS protocol itself.  Please note that this includes databases such
 138 as MS SQL Server and Sybase.  This support is new in the current release.