Merged revisions 56569 via svnmerge from
[asterisk/asterisk.git] / 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 * Realtime SIP friends
45 ----------------------
46 The SIP realtime objects are users and peers that are loaded in memory 
47 when needed, then deleted. This means that Asterisk currently can't handle
48 voicemail notification and NAT keepalives for these peers. Other than that,
49 most of the functionality works the same way for realtime friends as for
50 the ones in static configuration.
51
52 With caching, the device stays in memory for a specified time. More 
53 information about this is to be found in the sip.conf sample file.
54
55 If you specify a separate family called "sipregs" SIP registration
56 data will be stored in that table and not in the "sippeers" table.
57
58 * Realtime H.323 friends
59 ------------------------
60 Like SIP realtime friends, H.323 friends also can be configured using
61 dynamic realtime objects.
62
63 * New function in the dial plan: The Realtime Switch
64 ----------------------------------------------------
65 The realtime switch is more than a port of functionality in v1.0 to the
66 new architecture, this is a new feature of Asterisk based on the 
67 ARA. The realtime switch lets your Asterisk server do database lookups
68 of extensions in realtime from your dial plan. You can have many Asterisk
69 servers sharing a dynamically updated dial plan in real time with this
70 solution.
71
72 Note that this switch does _NOT_ support Caller ID matching, only
73 extension name/pattern matching.
74
75 * So what can you do?
76 ---------------------
77 The realtime Architecture lets you store all of your configuration in
78 databases and reload it whenever you want. You can force a reload over
79 the AMI, Asterisk Manager Interface or by calling Asterisk from a 
80 shell script with 
81         asterisk -rx "reload"
82
83 You may also dynamically add SIP and IAX devices and extensions 
84 and making them available without a reload, by using the realtime
85 objects and the realtime switch.
86
87
88 * Configuration in extconfig.conf
89 ---------------------------------
90 You configure the ARA in extconfig.conf (yes, it's a strange name, but
91 is was defined in the early days of the realtime architecture and kind
92 of stuck). Please see doc/extconfig.txt for database schemas.
93
94 The part of Asterisk that connects to the ARA use a well defined family
95 name to find the proper database driver. The syntax is easy:
96    <family> => <realtime driver>,<db name>[,<table>]
97
98 The options following the realtime driver identified depends on the
99 driver.
100
101 Defined well-known family names are:
102
103 * sippeers, sipusers    SIP peers and users
104 * iaxpeers, iaxusers    IAX2 peers and users
105 * voicemail             Voicemail accounts 
106 * queues                Queues
107 * queue_members         Queue members
108 * extensions            Realtime extensions (switch)
109
110 There is documentation of the SQL database in the file
111 doc/extconfig.txt in your Asterisk source code tree.
112
113 For voicemail storage with the support of ODBC, there is a 
114 doc/odbcstorage.txt documentation file.
115
116
117 * Limitations
118 -------------
119 Currently, realtime extensions do not support realtime hints.  There is
120 a workaround available by using func_odbc.  See the sample func_odbc.conf
121 for more information.
122
123
124 * FreeTDS supported with connection pooling
125 -------------------------------------------
126 In order to use a FreeTDS-based database with realtime, you need to turn
127 connection pooling on in res_odbc.conf.  This is due to a limitation within
128 the FreeTDS protocol itself.  Please note that this includes databases such
129 as MS SQL Server and Sybase.  This support is new in the current release.