<html>
<head>
<base href="https://wiki.asterisk.org/wiki">
<link rel="stylesheet" href="/wiki/s/2030/1/7/_/styles/combined.css?spaceKey=AST&forWysiwyg=true" type="text/css">
</head>
<body style="background: white;" bgcolor="white" class="email-body">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
<h2><a href="https://wiki.asterisk.org/wiki/display/AST/Distributed+Device+State+with+AIS">Distributed Device State with AIS</a></h2>
<h4>Page <b>edited</b> by <a href="https://wiki.asterisk.org/wiki/display/~russell">Russell Bryant</a>
</h4>
<br/>
<h4>Changes (25)</h4>
<div id="page-diffs">
<table class="diff" cellpadding="0" cellspacing="0">
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">h1. Distributed Device State <br>Copyright (C) 2007-2008, Digium, Inc. <br>Russell Bryant <russell@digium.com> <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">{numberedheadings} <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">{note:Important Note} <br>This document includes some information about using the res_ais module for distributed events. However, it is important to note that res_ais is still considered experimental, as the module exposes the binary format of events over the network between servers. This format is still subject to change between releases. <br></td></tr>
<tr><td class="diff-changed-lines" ><span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">{note}</span> <span class="diff-added-words"style="background-color: #dfd;">{toc}</span> <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-changed-lines" ><span class="diff-changed-words">h<span class="diff-deleted-chars"style="color:#999;background-color:#fdd;text-decoration:line-through;">5</span><span class="diff-added-chars"style="background-color: #dfd;">1</span>.</span> Introduction <br></td></tr>
<tr><td class="diff-unchanged" > <br>Various changes have been made related to "event handling" in Asterisk. One of the most important things included in these changes is the ability to share certain events between servers. The two types of events that can currently be shared between servers are: <br> <br># 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. <br></td></tr>
<tr><td class="diff-unchanged" ># 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. <br> <br></td></tr>
<tr><td class="diff-changed-lines" ><span class="diff-changed-words">h<span class="diff-deleted-chars"style="color:#999;background-color:#fdd;text-decoration:line-through;">5</span><span class="diff-added-chars"style="background-color: #dfd;">1</span>.</span> OpenAIS Installation <br></td></tr>
<tr><td class="diff-unchanged" > <br>*Description* <br></td></tr>
<tr><td class="diff-snipped" >...<br></td></tr>
<tr><td class="diff-unchanged" >*Download* <br> <br></td></tr>
<tr><td class="diff-changed-lines" >Download the latest <span class="diff-changed-words">version<span class="diff-added-chars"style="background-color: #dfd;">s</span></span> of <span class="diff-added-words"style="background-color: #dfd;">Corosync and</span> OpenAIS from <span class="diff-added-words"style="background-color: #dfd;">[http://www.corosync.org/] and</span> [http://www.openais.org/]. <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">*Compile* <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">*Compile and Install* <br></td></tr>
<tr><td class="diff-unchanged" > <br>{noformat} <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">$ tar xvzf corosync-1.2.8.tar.gz <br></td></tr>
<tr><td class="diff-changed-lines" >$ cd <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">openais-trunk</span> <span class="diff-added-words"style="background-color: #dfd;">corosync-1.2.8</span> <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">$ ./configure <br></td></tr>
<tr><td class="diff-changed-lines" >$ make <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">PREFIX=/usr</span> <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">$ sudo make install <br></td></tr>
<tr><td class="diff-unchanged" >{noformat} <br> <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">*Install* <br> <br>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/. <br> <br></td></tr>
<tr><td class="diff-unchanged" >{noformat} <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">$ tar xvzf openais-1.1.4.tar.gz <br>$ cd openais-1.1.4 <br>$ ./configure <br>$ make <br></td></tr>
<tr><td class="diff-changed-lines" >$ sudo make install <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">PREFIX=/usr</span> <br></td></tr>
<tr><td class="diff-unchanged" >{noformat} <br> <br></td></tr>
<tr><td class="diff-changed-lines" ><span class="diff-changed-words">h<span class="diff-deleted-chars"style="color:#999;background-color:#fdd;text-decoration:line-through;">5</span><span class="diff-added-chars"style="background-color: #dfd;">1</span>.</span> OpenAIS Configuration <br></td></tr>
<tr><td class="diff-unchanged" > <br>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/. <br></td></tr>
<tr><td class="diff-snipped" >...<br></td></tr>
<tr><td class="diff-unchanged" > <br> <br></td></tr>
<tr><td class="diff-changed-lines" ><span class="diff-changed-words">h<span class="diff-deleted-chars"style="color:#999;background-color:#fdd;text-decoration:line-through;">5</span><span class="diff-added-chars"style="background-color: #dfd;">1</span>.</span> Running OpenAIS <br></td></tr>
<tr><td class="diff-unchanged" > <br>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. <br></td></tr>
<tr><td class="diff-snipped" >...<br></td></tr>
<tr><td class="diff-unchanged" >{noformat} <br> <br></td></tr>
<tr><td class="diff-changed-lines" ><span class="diff-changed-words">h<span class="diff-deleted-chars"style="color:#999;background-color:#fdd;text-decoration:line-through;">5</span><span class="diff-added-chars"style="background-color: #dfd;">1</span>.</span> Configuring Asterisk <br></td></tr>
<tr><td class="diff-unchanged" > <br>First, ensure that you have a unique "entity ID" set for each server. <br></td></tr>
<tr><td class="diff-snipped" >...<br></td></tr>
<tr><td class="diff-unchanged" >{noformat} <br> <br></td></tr>
<tr><td class="diff-changed-lines" ><span class="diff-changed-words">h<span class="diff-deleted-chars"style="color:#999;background-color:#fdd;text-decoration:line-through;">5</span><span class="diff-added-chars"style="background-color: #dfd;">1</span>.</span> Basic Testing of Asterisk with OpenAIS <br></td></tr>
<tr><td class="diff-unchanged" > <br>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. <br></td></tr>
<tr><td class="diff-snipped" >...<br></td></tr>
<tr><td class="diff-unchanged" > <br> <br></td></tr>
<tr><td class="diff-changed-lines" ><span class="diff-changed-words">h<span class="diff-deleted-chars"style="color:#999;background-color:#fdd;text-decoration:line-through;">5</span><span class="diff-added-chars"style="background-color: #dfd;">1</span>.</span> Testing Distributed Device State <br></td></tr>
<tr><td class="diff-unchanged" > <br>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: <br></td></tr>
<tr><td class="diff-snipped" >...<br></td></tr>
<tr><td class="diff-unchanged" >state. <br> <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">h5. Question, Comments, and Bug Reports <br></td></tr>
<tr><td class="diff-changed-lines" ><span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;"> </span> <span class="diff-added-words"style="background-color: #dfd;">{numberedheadings}</span> <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">For now, please direct all feedback to Russell Bryant <russell@digium.com>. <br></td></tr>
</table>
</div> <h4>Full Content</h4>
<div class="notificationGreySide">
<div>
<ul>
<li><a href='#DistributedDeviceStatewithAIS-Introduction'>1. Introduction</a></li>
<li><a href='#DistributedDeviceStatewithAIS-OpenAISInstallation'>2. OpenAIS Installation</a></li>
<li><a href='#DistributedDeviceStatewithAIS-OpenAISConfiguration'>3. OpenAIS Configuration</a></li>
<li><a href='#DistributedDeviceStatewithAIS-RunningOpenAIS'>4. Running OpenAIS</a></li>
<ul>
<li><a href='#DistributedDeviceStatewithAIS-InstallingAsterisk'>Installing Asterisk</a></li>
</ul>
<li><a href='#DistributedDeviceStatewithAIS-ConfiguringAsterisk'>5. Configuring Asterisk</a></li>
<li><a href='#DistributedDeviceStatewithAIS-BasicTestingofAsteriskwithOpenAIS'>6. Basic Testing of Asterisk with OpenAIS</a></li>
<li><a href='#DistributedDeviceStatewithAIS-TestingDistributedDeviceState'>7. Testing Distributed Device State</a></li>
</ul></div>
<h1><a name="DistributedDeviceStatewithAIS-Introduction"></a>1. Introduction</h1>
<p>Various changes have been made related to "event handling" in Asterisk. One of the most important things included in these changes is the ability to share certain events between servers. The two types of events that can currently be shared between servers are:</p>
<ol>
<li>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.</li>
<li>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.</li>
</ol>
<h1><a name="DistributedDeviceStatewithAIS-OpenAISInstallation"></a>2. OpenAIS Installation</h1>
<p><b>Description</b></p>
<p>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.</p>
<p>For more information about OpenAIS, visit their web site <a href="http://www.openais.org/" class="external-link" rel="nofollow">http://www.openais.org/</a>.</p>
<p><b>Download</b></p>
<p>Download the latest versions of Corosync and OpenAIS from <a href="http://www.corosync.org/" class="external-link" rel="nofollow">http://www.corosync.org/</a> and <a href="http://www.openais.org/" class="external-link" rel="nofollow">http://www.openais.org/</a>.</p>
<p><b>Compile and Install</b></p>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>$ tar xvzf corosync-1.2.8.tar.gz
$ cd corosync-1.2.8
$ ./configure
$ make
$ sudo make install
</pre>
</div></div>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>$ tar xvzf openais-1.1.4.tar.gz
$ cd openais-1.1.4
$ ./configure
$ make
$ sudo make install
</pre>
</div></div>
<h1><a name="DistributedDeviceStatewithAIS-OpenAISConfiguration"></a>3. OpenAIS Configuration</h1>
<p>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/.</p>
<p>Edit openais.conf ...</p>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>$ ${EDITOR:-vim} /etc/ais/openais.conf
</pre>
</div></div>
<p>The only section that you should need to change is the totem - interface section.</p>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>totem {
...
interface {
interface {
ringnumber: 0
bindnetaddr: 10.19.0.0
mcastaddr: 226.94.1.1
mcastport: 5405
}
}
</pre>
</div></div>
<p>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.</p>
<p>The one other thing that you need to do is create a user called "ais".</p>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>$ sudo adduser ais
</pre>
</div></div>
<p>See the OpenAIS QUICKSTART file for more information on installing, configuring, and testing OpenAIS.</p>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>$ cd openais-trunk
$ less QUICKSTART
</pre>
</div></div>
<h1><a name="DistributedDeviceStatewithAIS-RunningOpenAIS"></a>4. Running OpenAIS</h1>
<p>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.</p>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>$ sudo aisexec -f
</pre>
</div></div>
<h5><a name="DistributedDeviceStatewithAIS-InstallingAsterisk"></a>Installing Asterisk</h5>
<p>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.</p>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>$ cd asterisk-source
$ ./configure
$ make menuselect
---> Resource Modules
</pre>
</div></div>
<p>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.</p>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>$ sudo cp configs/ais.conf.sample /etc/asterisk/ais.conf
</pre>
</div></div>
<h1><a name="DistributedDeviceStatewithAIS-ConfiguringAsterisk"></a>5. Configuring Asterisk</h1>
<p>First, ensure that you have a unique "entity ID" set for each server.</p>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>*CLI> core show settings
...
Entity ID: 01:23:45:67:89:ab
</pre>
</div></div>
<p>The code will attempt to generate a unique entity ID for you by reading MAC addresses off of a network interface. However, you can also set it manually in the [options] section of asterisk.conf.</p>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>$ sudo ${EDITOR:-vim} /etc/asterisk/asterisk.conf
[options]
...
entity_id=01:23:45:67:89:ab
</pre>
</div></div>
<p>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:</p>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>$ sudo ${EDITOR:-vim} /etc/asterisk/ais.conf
[device_state]
type=event_channel
publish_event=device_state
subscribe_event=device_state
</pre>
</div></div>
<p>For more information on the contents and available options in this configuration file, please see the sample configuration file:</p>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>$ cd asterisk-source
$ less configs/ais.conf.sample
</pre>
</div></div>
<h1><a name="DistributedDeviceStatewithAIS-BasicTestingofAsteriskwithOpenAIS"></a>6. Basic Testing of Asterisk with OpenAIS</h1>
<p>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.</p>
<p>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<br/>
(CLM).</p>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>*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
=== ---------------------------------------------------------
===
=============================================================
</pre>
</div></div>
<p>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: <tt>ais <service name> <command></tt>.</p>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>*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
=== ---------------------------------------------------------
===
=============================================================
</pre>
</div></div>
<h1><a name="DistributedDeviceStatewithAIS-TestingDistributedDeviceState"></a>7. Testing Distributed Device State</h1>
<p>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:</p>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>[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)})
</pre>
</div></div>
<p>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.</p>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>server1*CLI> console dial set_inuse@devstate_test
...
server2*CLI> console dial check@devstate_test
-- Executing [check@devstate_test:1] NoOp("OSS/dsp", "Custom:mystate is INUSE") in new stack
</pre>
</div></div>
<p>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<br/>
state change with distributed device state:</p>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>server2*CLI> core show hints
-= Registered Asterisk Dial Plan Hints =-
1234@devstate_test : Custom:mystate State:InUse Watchers 0
</pre>
</div></div>
<p>One other helpful thing here during testing and debugging is to enable debug logging. To do so, enable debug on the console in /etc/asterisk/logger.conf. Also, enable debug at the Asterisk CLI.</p>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>*CLI> core set debug 1
</pre>
</div></div>
<p>When you have this debug enabled, you will see output during the processing of every device state change. The important thing to look for is where the known state of the device for each server is added together to determine the overall<br/>
state.</p>
</div>
<div id="commentsSection" class="wiki-content pageSection">
<div style="float: right;">
<a href="https://wiki.asterisk.org/wiki/users/viewnotifications.action" class="grey">Change Notification Preferences</a>
</div>
<a href="https://wiki.asterisk.org/wiki/display/AST/Distributed+Device+State+with+AIS">View Online</a>
|
<a href="https://wiki.asterisk.org/wiki/pages/diffpagesbyversion.action?pageId=4259996&revisedVersion=9&originalVersion=8">View Changes</a>
|
<a href="https://wiki.asterisk.org/wiki/display/AST/Distributed+Device+State+with+AIS?showComments=true&showCommentArea=true#addcomment">Add Comment</a>
</div>
</div>
</div>
</div>
</div>
</body>
</html>