doc/tex/realtime.tex

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