Merged revisions 53715 via svnmerge from
[asterisk/asterisk.git] / doc / extconfig.txt
1 Asterisk external configuration
2 ===============================
3
4 The Asterisk external configuration engine is the result of work by
5 Anthony Minessale II, Mark Spencer and Constantine Filin.
6
7 It is designed to provide a flexible, seamless integration between
8 Asterisk's internal configuration structure and external SQL other other
9 databases (maybe even LDAP one day).
10
11 The external configuration engine is the basis for the ARA, the
12 Asterisk Realtime Architecture (see doc/realtime.txt for more 
13 information).
14
15 * Configuration
16
17 External configuration is configured in /etc/asterisk/extconfig.conf
18 allowing you to map any configuration file (static mappings) to
19 be pulled from the database, or to map special runtime entries which
20 permit the dynamic creation of objects, entities, peers, etc. without
21 the necessity of a reload.
22
23 Generally speaking, the columns in your tables should line up with the
24 fields you would specify in the given entity declaration.  If an entry
25 would appear more than once, in the column it should be separated by a
26 semicolon. For example, an entity that looks like:
27
28 [foo]
29 host=dynamic
30 secret=bar
31 context=default
32 context=local
33
34 could be stored in a table like this:
35
36 +------+--------+-------+--------------+----------+-----+-----------+
37 | name | host   | secret| context      | ipaddr   | port| regseconds|
38 +------+--------+-------+--------------+----------+-----+-----------+
39 | foo  | dynamic|  bar  | default;local| 127.0.0.1| 4569| 1096954152|
40 +------+--------+-------+--------------+----------+-----+-----------+
41
42 Note that for use with IAX or SIP, the table will also need the "name", 
43 "ipaddr", "port", "regseconds" columns.  If you wanted to be able to 
44 configure the callerid, you could just add a callerid column to the 
45 table, for example.
46
47 A SIP table would look more like this:
48
49 +------+--------+-------+----------+-----+------------+----------+
50 | name | host   | secret| ipaddr   | port| regseconds | username |
51 +------+--------+-------+----------+-----+------------+----------+
52 | foo  | dynamic|  bar  | 127.0.0.1| 4569| 1096954152 |   1234   |
53 +------+--------+-------+----------+-----+------------+----------+
54
55 in order to store appropriate parameters required for SIP.
56
57 In addition to this, if you add a field named "regserver" to the
58 SIP peers table and have the system name set in asterisk.conf, 
59 Asterisk will store the system name that the user registered on in 
60 the database. This can be used to direct calls to go through the server 
61 that holds the registration (for NAT traversal purposes).
62
63 A Voicemail table would look more like this:
64
65 +----------+---------+----------+----------+-----------+---------------+
66 | uniqueid | mailbox | context  | password |email      |   fullname    | 
67 +----------+---------+----------+----------+-----------+---------------+
68 |        1 |   1234  | default  |  4242    | a@b.com   | Joe Schmoe    | 
69 +----------+---------+----------+----------+-----------+---------------+
70
71 The uniqueid should be unique to each voicemail user and can be 
72 autoincrement.  It need not have any relation to the mailbox or context.
73
74 An extension table would look more like this:
75
76 +----------+---------+----------+-------+-----------+
77 | context  |  exten  | priority |  app  |  appdata  |
78 +----------+---------+----------+-------+-----------+
79 |  default |    1234 |        1 |  Dial |     Zap/1 |
80 +----------+---------+----------+-------+-----------+
81
82 In the dialplan you just use the Realtime switch:
83
84 [foo]
85 switch => Realtime
86
87 or:
88
89 [bar]
90 switch => Realtime/bar@extensions
91