[asterisk-commits] russell: branch russell/events r103692 - /team/russell/events/doc/

SVN commits to the Asterisk project asterisk-commits at lists.digium.com
Thu Feb 14 15:14:38 CST 2008


Author: russell
Date: Thu Feb 14 15:14:37 2008
New Revision: 103692

URL: http://svn.digium.com/view/asterisk?view=rev&rev=103692
Log:
Add a pretty hefty document on setting up and testing distributed events, and
distributed device state, specifically

Added:
    team/russell/events/doc/distributed_devstate.txt   (with props)

Added: team/russell/events/doc/distributed_devstate.txt
URL: http://svn.digium.com/view/asterisk/team/russell/events/doc/distributed_devstate.txt?view=auto&rev=103692
==============================================================================
--- team/russell/events/doc/distributed_devstate.txt (added)
+++ team/russell/events/doc/distributed_devstate.txt Thu Feb 14 15:14:37 2008
@@ -1,0 +1,281 @@
+===============================================================================
+===
+=== Distributed Device State
+===
+=== Copyright (C) 2007-2008, Digium, Inc.
+=== Russell Bryant <russell at digium.com>
+===
+===============================================================================
+
+-------------------------------------------------------------------------------
+--- INTRODUCTION
+-------------------------------------------------------------------------------
+
+The code in this branch does a lot of things related to "event handling" in
+Asterisk.  One of the most important things that this branch currently provides
+is the ability to share certain events between servers.  The two types of
+events that can current be shared between servers are:
+
+   1) MWI - Message Waiting Indication
+      - This gives you a high performance option for letting servers in a
+        cluster be aware of changes in the state of a mailbox.  Instead of
+        having each server have to poll an ODBC database, this lets the server
+        that actually made the change to the mailbox generate an event which
+        will get distributed to the other servers that have subscribed to this
+        information.
+
+   2) Device State
+      - This lets servers in a local cluster inform each other about changes in
+        the state of a device on that particular server.  When the state of a
+        device changes on any server, the overall state of that device across
+        the cluster will get recalculated.  So, any subscriptions to the state
+        of a device, such as hints in the dialplan or an application like
+        Queue() which reads device state, will then reflect the state of a
+        device across a cluster.
+
+-------------------------------------------------------------------------------
+
+-------------------------------------------------------------------------------
+--- OpenAIS Installation
+-------------------------------------------------------------------------------
+
+--- Description ---
+
+The current solution for providing distributed events with Asterisk is done by
+using the AIS (Application Interface Specification), which provides an API for
+a distributed event service.  While this API is standardized, this code has
+been developed exclusively against the open source implementation of AIS called
+OpenAIS.
+
+For more information about OpenAIS, visit their web site:
+
+    http://www.openais.org/
+
+--- Download ---
+
+To quickly downlaod OpenAIS, just check it out of svn:
+
+$ svn co http://svn.osdl.org/openais/trunk openais-trunk
+
+--- Compile ---
+
+$ cd openais-trunk
+$ make PREFIX=/usr
+
+--- Install ---
+
+By default, the current Makefile installs the libraries into /usr/lib/openais/,
+which is a little bit inconvenient.  So, open up the Makefile, find the lines
+that start with "LIBDIR=" to define the lib installation directory, and remove
+the trailing "openais" so it just gets installed in /usr/lib/.
+
+$ sudo make install PREFIX=/usr
+
+-------------------------------------------------------------------------------
+
+-------------------------------------------------------------------------------
+--- OpenAIS Configuration
+-------------------------------------------------------------------------------
+
+Basic OpenAIS configuration to get this working is actually pretty easy.  When
+you install it, it will put some default configuration files into /etc/ais/.
+Edit openais.conf ...
+
+$ ${EDITOR:-vim} /etc/ais/openais.conf
+
+The only section that you should need to change is the totem - interface
+section.
+
+totem {
+    ...
+    interface {
+    interface {
+        ringnumber: 0
+        bindnetaddr: 10.19.0.0
+        mcastaddr: 226.94.1.1
+        mcastport: 5405
+    }
+}
+
+The default mcastaddr and mcastport is probably fine.  But, you need to change
+the bindnetaddr to match the network address that the nodes of your cluster
+will communicate on.
+
+The one other thing that you need to do is create a user called "ais".
+
+$ sudo adduser ais
+
+See the OpenAIS QUICKSTART file for more information on installing,
+configuring, and testing OpenAIS.
+
+$ cd openais-trunk
+$ less QUICKSTART
+
+-------------------------------------------------------------------------------
+
+-------------------------------------------------------------------------------
+--- Running OpenAIS
+-------------------------------------------------------------------------------
+
+While testing, I would recommend starting the aisexec application in the
+foreground so that you can see debug messages that verify that the nodes have
+discovered each other and joined the cluster.
+
+$ sudo aisexec -f
+
+-------------------------------------------------------------------------------
+
+-------------------------------------------------------------------------------
+--- Installing Asterisk
+-------------------------------------------------------------------------------
+
+Install Asterisk as usual.  Just make sure that you run the configure script
+after OpenAIS gets installed.  That way, it will find the AIS header files and
+will let you build the res_ais module.  Check menuselect to make sure that
+res_ais is going to get compiled and installed.
+
+$ cd asterisk-events
+$ ./configure
+
+$ make menuselect
+  ---> Resource Modules
+
+If you have existing configuration on the system being used for testing, just
+be sure to install the addition configuration file needed for res_ais.
+
+$ sudo cp configs/ais.conf.sample /etc/asterisk/ais.conf
+
+-------------------------------------------------------------------------------
+
+-------------------------------------------------------------------------------
+--- Configuring Asterisk
+-------------------------------------------------------------------------------
+
+Edit the Asterisk ais.conf to enable distributed events.  For example, if you
+would like to enable distributed device state, you should add the following
+section to the file:
+
+$ sudo ${EDITOR:-vim} /etc/asterisk/ais.conf
+
+[device_state]
+type=event_channel
+publish_event=device_state
+subscribe_event=device_state
+
+For more information on the contents and available options in this configuration
+file, please see the sample configuration file:
+
+$ cd asterisk-events
+$ less configs/ais.conf.sample
+
+-------------------------------------------------------------------------------
+
+-------------------------------------------------------------------------------
+--- Basic Testing of Asterisk with OpenAIS
+-------------------------------------------------------------------------------
+
+If you have OpenAIS successfully installed and running, as well as Asterisk
+with OpenAIS support successfully installed, configured, and running, then you
+are ready to test out some of the AIS functionality in Asterisk.
+
+The first thing to test is to verify that all of the nodes that you think should
+be in your cluster are actually there.  There is an Asterisk CLI command which
+will list the current cluster members using the AIS Cluster Membership Service
+(CLM).
+
+*CLI> ais clm show members
+
+=============================================================
+=== Cluster Members =========================================
+=============================================================
+===
+=== ---------------------------------------------------------
+=== Node Name: 10.19.2.255
+=== ==> ID: 0xa1302ff
+=== ==> Address: 10.19.2.255
+=== ==> Member: Yes
+=== ---------------------------------------------------------
+===
+=== ---------------------------------------------------------
+=== Node Name: 10.19.6.187
+=== ==> ID: 0xa1306bb
+=== ==> Address: 10.19.6.187
+=== ==> Member: Yes
+=== ---------------------------------------------------------
+===
+=============================================================
+
+
+The next thing to do is to verify that you have successfully configured some
+event channels in the Asterisk ais.conf file.  This command is related to the
+event service (EVT), so like the previous command, uses the syntax:
+"ais <service name> <command>".
+
+*CLI> ais evt show event channels 
+
+=============================================================
+=== Event Channels ==========================================
+=============================================================
+===
+=== ---------------------------------------------------------
+=== Event Channel Name: mwi
+=== ==> Publishing Event Type: mwi
+=== ==> Subscribing to Event Type: mwi
+=== ---------------------------------------------------------
+===
+=== ---------------------------------------------------------
+=== Event Channel Name: device_state
+=== ==> Publishing Event Type: device_state
+=== ==> Subscribing to Event Type: device_state
+=== ---------------------------------------------------------
+===
+=============================================================
+
+-------------------------------------------------------------------------------
+
+-------------------------------------------------------------------------------
+--- Testing Distributed Device State
+-------------------------------------------------------------------------------
+
+The easiest way to test distributed device state is to use the DEVICE_STATE()
+diaplan function.  For example, you could have the following piece of dialplan
+on every server:
+
+[devstate_test]
+
+exten => 1234,hint,Custom:mystate
+
+exten => set_inuse,1,Set(DEVICE_STATE(Custom:mystate)=INUSE)
+exten => set_not_inuse,1,Set(DEVICE_STATE(Custom:mystate)=NOT_INUSE)
+
+exten => check,1,NoOp(Custom:mystate is ${DEVICE_STATE(Custom:mystate)})
+
+
+Now, you can test that the cluster-wide state of "Custom:mystate" is what
+you would expect after going to the CLI of each server and adjusting the state.
+
+server1*CLI> console dial set_inuse at devstate_test
+   ...
+
+server2*CLI> console dial check at devstate_test
+    -- Executing [check at devstate_test:1] NoOp("OSS/dsp", "Custom:mystate is INUSE") in new stack
+
+Various combinations of setting and checking the state on different servers can
+be used to verify that it works as expected.  Also, you can see the status of
+the hint on each server, as well, to see how extension state would reflect the
+state change with distributed device state:
+
+server2*CLI> core show hints
+    -= Registered Asterisk Dial Plan Hints =-
+                   1234 at devstate_test       : Custom:mystate        State:InUse           Watchers  0
+
+-------------------------------------------------------------------------------
+
+
+-------------------------------------------------------------------------------
+--- Question, Comments, and Bug Reports
+-------------------------------------------------------------------------------
+
+For now, please direct all feedback to Russell Bryant <russell at digium.com>.
+
+-------------------------------------------------------------------------------

Propchange: team/russell/events/doc/distributed_devstate.txt
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: team/russell/events/doc/distributed_devstate.txt
------------------------------------------------------------------------------
    svn:keywords = Author Date Id Revision

Propchange: team/russell/events/doc/distributed_devstate.txt
------------------------------------------------------------------------------
    svn:mime-type = text/plain




More information about the asterisk-commits mailing list