Making these documentation changes in the 1.4 branch upset various people, so

these chanes will only be done in the trunk.


git-svn-id: http://svn.digium.com/svn/asterisk/branches/1.4@58955 f38db490-d61c-443f-a65b-d21fe96a405b

1 files changed, 91 insertions, 0 deletions

diff --git a/doc/extconfig.txt b/doc/extconfig.txt
new file mode 100644
index 000000000..0a95997ce
--- /dev/null
+++ b/doc/extconfig.txt
@@ -0,0 +1,91 @@
+Asterisk external configuration
+===============================
+
+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 other
+databases (maybe even LDAP one day).
+
+The external configuration engine is the basis for the ARA, the
+Asterisk Realtime Architecture (see doc/realtime.txt for more 
+information).
+
+* Configuration
+
+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.
+
+Generally speaking, the columns in your tables should line up with the
+fields you would specify in the given entity declaration.  If an entry
+would appear more than once, in the column it should be separated by a
+semicolon. For example, an entity that looks like:
+
+[foo]
+host=dynamic
+secret=bar
+context=default
+context=local
+
+could be stored in a table like this:
+
++------+--------+-------+--------------+----------+-----+-----------+
+| name | host   | secret| context      | ipaddr   | port| regseconds|
++------+--------+-------+--------------+----------+-----+-----------+
+| foo  | dynamic|  bar  | default;local| 127.0.0.1| 4569| 1096954152|
++------+--------+-------+--------------+----------+-----+-----------+
+
+Note that for use with IAX or SIP, the table will also need the "name", 
+"ipaddr", "port", "regseconds" columns.  If you wanted to be able to 
+configure the callerid, you could just add a callerid column to the 
+table, for example.
+
+A SIP table would look more like this:
+
++------+--------+-------+----------+-----+------------+----------+
+| name | host   | secret| ipaddr   | port| regseconds | username |
++------+--------+-------+----------+-----+------------+----------+
+| foo  | dynamic|  bar  | 127.0.0.1| 4569| 1096954152 |   1234   |
++------+--------+-------+----------+-----+------------+----------+
+
+in order to store appropriate parameters required for SIP.
+
+In addition to this, if you add a field named "regserver" to the
+SIP peers table and have the system name set in asterisk.conf, 
+Asterisk will store the system name that the user registered on in 
+the database. This can be used to direct calls to go through the server 
+that holds the registration (for NAT traversal purposes).
+
+A Voicemail table would look more like this:
+
++----------+---------+----------+----------+-----------+---------------+
+| uniqueid | mailbox | context  | password |email      |   fullname    | 
++----------+---------+----------+----------+-----------+---------------+
+|        1 |   1234  | default  |  4242    | a@b.com   | Joe Schmoe    | 
++----------+---------+----------+----------+-----------+---------------+
+
+The uniqueid should be unique to each voicemail user and can be 
+autoincrement.  It need not have any relation to the mailbox or context.
+
+An extension table would look more like this:
+
++----------+---------+----------+-------+-----------+
+| context  |  exten  | priority |  app  |  appdata  |
++----------+---------+----------+-------+-----------+
+|  default |    1234 |        1 |  Dial |     Zap/1 |
++----------+---------+----------+-------+-----------+
+
+In the dialplan you just use the Realtime switch:
+
+[foo]
+switch => Realtime
+
+or:
+
+[bar]
+switch => Realtime/bar@extensions
+