[svn-commits] russell: branch russell/events r103692 - /team/russell/events/doc/
SVN commits to the Digium repositories
svn-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 svn-commits
mailing list