Add realtime README (programmer docs)
[asterisk/asterisk.git] / doc / README.realtime
1 The Asterisk Realtime Architecture
2 ----------------------------------
3
4 The Asterisk Realtime Architecture is a new set of drivers and 
5 functions implemented in Asterisk 1.1dev (and the following v1.2 stable).
6 The benefits of this architecture are many, both from a code management
7 standpoint and from an installation perspective. 
8
9 Additional information on the configuration of Realtime with Asterisk 
10 can be found in README.extconfig
11
12 The ARA is designed to be independent of storage. Currently, most
13 drivers are based on SQL, but the architecture should be able to handle
14 other storage methods in the future, like LDAP.
15
16 The main benefit comes in the database support. In Asterisk v1.0 some 
17 functions supported MySQL database, some PostgreSQL and other ODBC.
18 With the ARA, we have a unified database interface internally in Asterisk,
19 so if one function supports database integration, all databases that has a 
20 realtime driver will be supported in that function.
21
22 Currently there are three realtime database drivers:
23
24 * ODBC: Support for UnixODBC, integrated into Asterisk
25   The UnixODBC subsystem supports many different databases,
26   please check www.unixodbc.org for more information.
27 * MySQL: Found in the asterisk-addons cvs archive on cvs.digium.com
28 * Res_perl: Found in the asterisk-addons cvs archive on cvs.digium.com
29
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 There is some work to create a solution for Realtime SIP devices that
53 loads from database and stays in memory for the duration of a call or
54 a registration, but that work is not integrated into Asterisk yet.
55
56 * New function in the dial plan: The Realtime Switch
57 ----------------------------------------------------
58 The realtime switch is more than a port of functionality in v1.0 to the
59 new architecture, this is a new feature of Asterisk based on the 
60 ARA. The realtime switch let's your Asterisk server do database lookups
61 of extensions in realtime from your dial plan. You can have many Asterisk
62 servers sharing a dynamically updated dial plan in real time with this
63 solution.
64
65 * So what can you do?
66 ---------------------
67 The realtime Architecture lets you store all of your configuration in
68 databases and reload it whenever you want. You can force a reload over
69 the AMI, Asterisk Manager Interface or by calling Asterisk from a 
70 shell script with 
71         asterisk -rx "reload"
72
73 You may also dynamically add SIP and IAX devices and extensions 
74 and making them available without a reload, by using the realtime
75 objects and the realtime switch.
76
77
78 * Configuration in extconfig.conf
79 ---------------------------------
80 You configure the ARA in extconfig.conf (yes, it's a strange name, but
81 is was defined in the early days of the realtime architecture and kind
82 of stuck).
83
84 The part of Asterisk that connects to the ARA use a well defined family
85 name to find the proper database driver. The syntax is easy:
86    <family> => <realtime driver>,<db name>[,<table>]
87
88 The options following the realtime driver identified depends on the
89 driver.
90
91 Defined well-known family names are:
92
93 * sippeers, sipusers    SIP peers and users
94 * iaxfriends            IAX2 peers
95 * voicemail             Voicemail accounts 
96
97 There is documentation of the SQL database in the file
98 README.extconfig in your Asterisk source code tree, the /doc
99 directory.
100
101 For voicemail storage with the support of ODBC, there is a 
102 README.odbcstorage documentation file.
103
104 * Please test this architecture in order to make it stable
105 -----------------------------------------------------------
106 The Asterisk CVS head, v1.1 dev, is there for you to test. In order
107 to move it forward to a stable release (v1.2) we need more tests, 
108 more bug reports and more fixes.
109
110 You will find download instructions for Asterisk CVS head on
111 the www.asterisk.org web site. As usual, do not install a
112 development version on a production server. 
113
114 If you have any questions, the developer team is available almost
115 around the clock on the #asterisk-dev channel on irc.freenode.net.
116
117
118
119
120