1 files changed, 127 insertions, 0 deletions
diff --git a/trunk/doc/tex/realtime.tex b/trunk/doc/tex/realtime.tex
new file mode 100644
index 000000000..62349f60c
--- /dev/null
+++ b/trunk/doc/tex/realtime.tex
@@ -0,0 +1,127 @@
+\subsubsection{Introduction}
+
+The Asterisk Realtime Architecture is a new set of drivers and
+functions implemented in Asterisk.
+
+The benefits of this architecture are many, both from a code management
+standpoint and from an installation perspective.
+
+The ARA is designed to be independent of storage. Currently, most
+drivers are based on SQL, but the architecture should be able to handle
+other storage methods in the future, like LDAP.
+
+The main benefit comes in the database support. In Asterisk v1.0 some
+functions supported MySQL database, some PostgreSQL and other ODBC.
+With the ARA, we have a unified database interface internally in Asterisk,
+so if one function supports database integration, all databases that has a
+realtime driver will be supported in that function.
+
+Currently there are three realtime database drivers:
+
+\begin{itemize}
+  \item ODBC: Support for UnixODBC, integrated into Asterisk
+        The UnixODBC subsystem supports many different databases,
+        please check \url{www.unixodbc.org} for more information.
+  \item MySQL: Found in the asterisk-addons subversion repository on \url{svn.digium.com}
+  \item PostgreSQL: Native support for Postgres, integrated into Asterisk
+\end{itemize}
+
+\subsubsection{Two modes: Static and Realtime}
+
+The ARA realtime mode is used to dynamically load and update objects.
+This mode is used in the SIP and IAX2 channels, as well as in the voicemail
+system. For SIP and IAX2 this is similar to the v1.0 MYSQL\_FRIENDS
+functionality. With the ARA, we now support many more databases for
+dynamic configuration of phones.
+
+The ARA static mode is used to load configuration files. For the Asterisk
+modules that read configurations, there's no difference between a static
+file in the file system, like extensions.conf, and a configuration loaded
+from a database.
+
+\subsubsection{Realtime SIP friends}
+
+The SIP realtime objects are users and peers that are loaded in memory
+when needed, then deleted. This means that Asterisk currently can't handle
+voicemail notification and NAT keepalives for these peers. Other than that,
+most of the functionality works the same way for realtime friends as for
+the ones in static configuration.
+
+With caching, the device stays in memory for a specified time. More
+information about this is to be found in the sip.conf sample file.
+
+If you specify a separate family called "sipregs" SIP registration
+data will be stored in that table and not in the "sippeers" table.
+
+\subsubsection{Realtime H.323 friends}
+
+Like SIP realtime friends, H.323 friends also can be configured using
+dynamic realtime objects.
+
+\subsubsection{New function in the dial plan: The Realtime Switch}
+
+The realtime switch is more than a port of functionality in v1.0 to the
+new architecture, this is a new feature of Asterisk based on the
+ARA. The realtime switch lets your Asterisk server do database lookups
+of extensions in realtime from your dial plan. You can have many Asterisk
+servers sharing a dynamically updated dial plan in real time with this
+solution.
+
+Note that this switch does NOT support Caller ID matching, only
+extension name or pattern matching.
+
+\subsubsection{Capabilities}
+
+The realtime Architecture lets you store all of your configuration in
+databases and reload it whenever you want. You can force a reload over
+the AMI, Asterisk Manager Interface or by calling Asterisk from a
+shell script with
+
+  asterisk -rx "reload"
+
+You may also dynamically add SIP and IAX devices and extensions
+and making them available without a reload, by using the realtime
+objects and the realtime switch.
+
+\subsubsection{Configuration in extconfig.conf}
+
+You configure the ARA in extconfig.conf (yes, it's a strange name, but
+is was defined in the early days of the realtime architecture and kind
+of stuck).
+
+The part of Asterisk that connects to the ARA use a well defined family
+name to find the proper database driver. The syntax is easy:
+
+\begin{verbatim}
+    <family> => <realtime driver>,<db name>[,<table>]
+\end{verbatim}
+
+The options following the realtime driver identified depends on the
+driver.
+
+Defined well-known family names are:
+
+\begin{itemize}
+  \item sippeers, sipusers - SIP peers and users
+  \item iaxpeers, iaxusers - IAX2 peers and users
+  \item voicemail - Voicemail accounts
+  \item queues - Queues
+  \item queue\_members - Queue members
+  \item extensions - Realtime extensions (switch)
+\end{itemize}
+
+Voicemail storage with the support of ODBC described in file
+\path{docs/odbcstorage.tex} (\ref{odbcstorage}).
+
+\subsubsection{Limitations}
+
+Currently, realtime extensions do not support realtime hints.  There is
+a workaround available by using func\_odbc.  See the sample func\_odbc.conf
+for more information.
+
+\subsubsection{FreeTDS supported with connection pooling}
+
+In order to use a FreeTDS-based database with realtime, you need to turn
+connection pooling on in res\_odbc.conf.  This is due to a limitation within
+the FreeTDS protocol itself.  Please note that this includes databases such
+as MS SQL Server and Sybase.  This support is new in the current release.