document var_metric usage to prevent bugreports that are actually configuration issues

[asterisk/asterisk.git] / doc / tex / realtime.tex

diff --git a/doc/tex/realtime.tex b/doc/tex/realtime.tex
index 406cc98..26f937e 100644 (file)
--- a/doc/tex/realtime.tex
+++ b/doc/tex/realtime.tex
@@ -1,19 +1,19 @@
 \subsubsection{Introduction}
 
 \subsubsection{Introduction}
 

-The Asterisk Realtime Architecture is a new set of drivers and 
+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
 functions implemented in Asterisk.
 
 The benefits of this architecture are many, both from a code management

-standpoint and from an installation perspective. 
+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 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 
+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,
 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 
+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:
 realtime driver will be supported in that function.
 
 Currently there are three realtime database drivers:

@@ -22,7 +22,7 @@ Currently there are three realtime database drivers:
   \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 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 svn.digium.com
+  \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}
 
   \item PostgreSQL: Native support for Postgres, integrated into Asterisk
 \end{itemize}
 

@@ -30,7 +30,7 @@ Currently there are three realtime database drivers:
 
 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
 
 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 
+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.
 
 functionality. With the ARA, we now support many more databases for
 dynamic configuration of phones.
 

@@ -39,17 +39,34 @@ 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.
 
 file in the file system, like extensions.conf, and a configuration loaded
 from a database.
 

+You just have to always make sure the var\_metric values are properly set and
+ordered as you expect in your database server if you're using the static mode
+with ARA (either sequentially or with the same var\_metric value for everybody).
+
+If you have an option that depends on another one in a given configuration
+file (i.e, 'musiconhold' depending on 'agent' from agents.conf) but their
+var\_metric are not sequential you'll probably get default values being assigned for
+those options instead of the desired ones. You can still use the same
+var\_metric for all entries in your DB, just make sure the entries
+are recorded in an order that does not break the option dependency.
+
+That doesn't happen when you use a static file in the file system. Although
+this might be interpreted as a bug or limitation, it is not.
+

 \subsubsection{Realtime SIP friends}
 
 \subsubsection{Realtime SIP friends}
 

-The SIP realtime objects are users and peers that are loaded in memory 
+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.
 
 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 
+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.
 
 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
 \subsubsection{Realtime H.323 friends}
 
 Like SIP realtime friends, H.323 friends also can be configured using

@@ -58,7 +75,7 @@ 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
 \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 
+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
 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

@@ -71,12 +88,12 @@ extension name or pattern matching.
 
 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 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 
+the AMI, Asterisk Manager Interface or by calling Asterisk from a
+shell script with

 
   asterisk -rx "reload"
 
 
   asterisk -rx "reload"
 

-You may also dynamically add SIP and IAX devices and extensions 
+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.
 
 and making them available without a reload, by using the realtime
 objects and the realtime switch.
 

@@ -101,14 +118,14 @@ Defined well-known family names are:
 \begin{itemize}
   \item sippeers, sipusers - SIP peers and users
   \item iaxpeers, iaxusers - IAX2 peers and users
 \begin{itemize}
   \item sippeers, sipusers - SIP peers and users
   \item iaxpeers, iaxusers - IAX2 peers and users

-  \item voicemail - Voicemail accounts 
+  \item voicemail - Voicemail accounts

   \item queues - Queues
   \item queue\_members - Queue members
   \item extensions - Realtime extensions (switch)
 \end{itemize}
 
   \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 
-docs/odbcstorage.tex (\ref{odbcstorage}).
+Voicemail storage with the support of ODBC described in file
+\path{docs/odbcstorage.tex} (\ref{odbcstorage}).

 
 \subsubsection{Limitations}
 
 
 \subsubsection{Limitations}