2a685159e3c90faab039aa3c71c0d192660eec0b
[asterisk/asterisk.git] / doc / distributed_devstate.txt
1 ===============================================================================
2 ===
3 === Distributed Device State
4 ===
5 === Copyright (C) 2007-2008, Digium, Inc.
6 === Russell Bryant <russell@digium.com>
7 ===
8 ===============================================================================
9
10 -------------------------------------------------------------------------------
11 --- INTRODUCTION
12 -------------------------------------------------------------------------------
13
14 Various changes have been made related to "event handling" in Asterisk.
15 One of the most important things included in these changes is the ability
16 to share certain events between servers.  The two types of events that can
17 currently be shared between servers are:
18
19    1) MWI - Message Waiting Indication
20       - This gives you a high performance option for letting servers in a
21         cluster be aware of changes in the state of a mailbox.  Instead of
22         having each server have to poll an ODBC database, this lets the server
23         that actually made the change to the mailbox generate an event which
24         will get distributed to the other servers that have subscribed to this
25         information.
26
27    2) Device State
28       - This lets servers in a local cluster inform each other about changes in
29         the state of a device on that particular server.  When the state of a
30         device changes on any server, the overall state of that device across
31         the cluster will get recalculated.  So, any subscriptions to the state
32         of a device, such as hints in the dialplan or an application like
33         Queue() which reads device state, will then reflect the state of a
34         device across a cluster.
35
36 -------------------------------------------------------------------------------
37
38 -------------------------------------------------------------------------------
39 --- OpenAIS Installation
40 -------------------------------------------------------------------------------
41
42 --- Description ---
43
44 The current solution for providing distributed events with Asterisk is done by
45 using the AIS (Application Interface Specification), which provides an API for
46 a distributed event service.  While this API is standardized, this code has
47 been developed exclusively against the open source implementation of AIS called
48 OpenAIS.
49
50 For more information about OpenAIS, visit their web site:
51
52     http://www.openais.org/
53
54 --- Download ---
55
56 To quickly downlaod OpenAIS, just check it out of svn:
57
58 $ svn co http://svn.osdl.org/openais/trunk openais-trunk
59
60 --- Compile ---
61
62 $ cd openais-trunk
63 $ make PREFIX=/usr
64
65 --- Install ---
66
67 By default, the current Makefile installs the libraries into /usr/lib/openais/,
68 which is a little bit inconvenient.  So, open up the Makefile, find the lines
69 that start with "LIBDIR=" to define the lib installation directory, and remove
70 the trailing "openais" so it just gets installed in /usr/lib/.
71
72 $ sudo make install PREFIX=/usr
73
74 -------------------------------------------------------------------------------
75
76 -------------------------------------------------------------------------------
77 --- OpenAIS Configuration
78 -------------------------------------------------------------------------------
79
80 Basic OpenAIS configuration to get this working is actually pretty easy.  When
81 you install it, it will put some default configuration files into /etc/ais/.
82 Edit openais.conf ...
83
84 $ ${EDITOR:-vim} /etc/ais/openais.conf
85
86 The only section that you should need to change is the totem - interface
87 section.
88
89 totem {
90     ...
91     interface {
92     interface {
93         ringnumber: 0
94         bindnetaddr: 10.19.0.0
95         mcastaddr: 226.94.1.1
96         mcastport: 5405
97     }
98 }
99
100 The default mcastaddr and mcastport is probably fine.  But, you need to change
101 the bindnetaddr to match the network address that the nodes of your cluster
102 will communicate on.
103
104 The one other thing that you need to do is create a user called "ais".
105
106 $ sudo adduser ais
107
108 See the OpenAIS QUICKSTART file for more information on installing,
109 configuring, and testing OpenAIS.
110
111 $ cd openais-trunk
112 $ less QUICKSTART
113
114 -------------------------------------------------------------------------------
115
116 -------------------------------------------------------------------------------
117 --- Running OpenAIS
118 -------------------------------------------------------------------------------
119
120 While testing, I would recommend starting the aisexec application in the
121 foreground so that you can see debug messages that verify that the nodes have
122 discovered each other and joined the cluster.
123
124 $ sudo aisexec -f
125
126 -------------------------------------------------------------------------------
127
128 -------------------------------------------------------------------------------
129 --- Installing Asterisk
130 -------------------------------------------------------------------------------
131
132 Install Asterisk as usual.  Just make sure that you run the configure script
133 after OpenAIS gets installed.  That way, it will find the AIS header files and
134 will let you build the res_ais module.  Check menuselect to make sure that
135 res_ais is going to get compiled and installed.
136
137 $ cd asterisk-events
138 $ ./configure
139
140 $ make menuselect
141   ---> Resource Modules
142
143 If you have existing configuration on the system being used for testing, just
144 be sure to install the addition configuration file needed for res_ais.
145
146 $ sudo cp configs/ais.conf.sample /etc/asterisk/ais.conf
147
148 -------------------------------------------------------------------------------
149
150 -------------------------------------------------------------------------------
151 --- Configuring Asterisk
152 -------------------------------------------------------------------------------
153
154 First, ensure that you have a unique "entity ID" set for each server.
155
156 *CLI> core show settings
157    ...
158    Entity ID:                   01:23:45:67:89:ab
159
160 The code will attempt to generate a unique entity ID for you by reading
161 MAC addresses off of a network interface.  However, you can also set it
162 manually in the [options] section of asterisk.conf.
163
164 $ sudo ${EDITOR:-vim} /etc/asterisk/asterisk.conf
165
166 [options]
167 ...
168 entity_id=01:23:45:67:89:ab
169
170
171 Edit the Asterisk ais.conf to enable distributed events.  For example, if you
172 would like to enable distributed device state, you should add the following
173 section to the file:
174
175 $ sudo ${EDITOR:-vim} /etc/asterisk/ais.conf
176
177 [device_state]
178 type=event_channel
179 publish_event=device_state
180 subscribe_event=device_state
181
182 For more information on the contents and available options in this configuration
183 file, please see the sample configuration file:
184
185 $ cd asterisk-events
186 $ less configs/ais.conf.sample
187
188 -------------------------------------------------------------------------------
189
190 -------------------------------------------------------------------------------
191 --- Basic Testing of Asterisk with OpenAIS
192 -------------------------------------------------------------------------------
193
194 If you have OpenAIS successfully installed and running, as well as Asterisk
195 with OpenAIS support successfully installed, configured, and running, then you
196 are ready to test out some of the AIS functionality in Asterisk.
197
198 The first thing to test is to verify that all of the nodes that you think should
199 be in your cluster are actually there.  There is an Asterisk CLI command which
200 will list the current cluster members using the AIS Cluster Membership Service
201 (CLM).
202
203 *CLI> ais clm show members
204
205 =============================================================
206 === Cluster Members =========================================
207 =============================================================
208 ===
209 === ---------------------------------------------------------
210 === Node Name: 10.19.2.255
211 === ==> ID: 0xa1302ff
212 === ==> Address: 10.19.2.255
213 === ==> Member: Yes
214 === ---------------------------------------------------------
215 ===
216 === ---------------------------------------------------------
217 === Node Name: 10.19.6.187
218 === ==> ID: 0xa1306bb
219 === ==> Address: 10.19.6.187
220 === ==> Member: Yes
221 === ---------------------------------------------------------
222 ===
223 =============================================================
224
225
226 The next thing to do is to verify that you have successfully configured some
227 event channels in the Asterisk ais.conf file.  This command is related to the
228 event service (EVT), so like the previous command, uses the syntax:
229 "ais <service name> <command>".
230
231 *CLI> ais evt show event channels 
232
233 =============================================================
234 === Event Channels ==========================================
235 =============================================================
236 ===
237 === ---------------------------------------------------------
238 === Event Channel Name: mwi
239 === ==> Publishing Event Type: mwi
240 === ==> Subscribing to Event Type: mwi
241 === ---------------------------------------------------------
242 ===
243 === ---------------------------------------------------------
244 === Event Channel Name: device_state
245 === ==> Publishing Event Type: device_state
246 === ==> Subscribing to Event Type: device_state
247 === ---------------------------------------------------------
248 ===
249 =============================================================
250
251 -------------------------------------------------------------------------------
252
253 -------------------------------------------------------------------------------
254 --- Testing Distributed Device State
255 -------------------------------------------------------------------------------
256
257 The easiest way to test distributed device state is to use the DEVICE_STATE()
258 diaplan function.  For example, you could have the following piece of dialplan
259 on every server:
260
261 [devstate_test]
262
263 exten => 1234,hint,Custom:mystate
264
265 exten => set_inuse,1,Set(DEVICE_STATE(Custom:mystate)=INUSE)
266 exten => set_not_inuse,1,Set(DEVICE_STATE(Custom:mystate)=NOT_INUSE)
267
268 exten => check,1,NoOp(Custom:mystate is ${DEVICE_STATE(Custom:mystate)})
269
270
271 Now, you can test that the cluster-wide state of "Custom:mystate" is what
272 you would expect after going to the CLI of each server and adjusting the state.
273
274 server1*CLI> console dial set_inuse@devstate_test
275    ...
276
277 server2*CLI> console dial check@devstate_test
278     -- Executing [check@devstate_test:1] NoOp("OSS/dsp", "Custom:mystate is INUSE") in new stack
279
280 Various combinations of setting and checking the state on different servers can
281 be used to verify that it works as expected.  Also, you can see the status of
282 the hint on each server, as well, to see how extension state would reflect the
283 state change with distributed device state:
284
285 server2*CLI> core show hints
286     -= Registered Asterisk Dial Plan Hints =-
287                    1234@devstate_test       : Custom:mystate        State:InUse           Watchers  0
288
289
290 One other helpful thing here during testing and debugging is to enable debug
291 logging.  To do so, enable debug on the console in /etc/asterisk/logger.conf.
292 Also, enable debug at the Asterisk CLI.
293
294 *CLI> core set debug 1
295
296 When you have this debug enabled, you will see output during the processing of
297 every device state change.  The important thing to look for is where the known
298 state of the device for each server is added together to determine the overall
299 state.
300
301 -------------------------------------------------------------------------------
302
303
304 -------------------------------------------------------------------------------
305 --- Question, Comments, and Bug Reports
306 -------------------------------------------------------------------------------
307
308 For now, please direct all feedback to Russell Bryant <russell@digium.com>.
309
310 -------------------------------------------------------------------------------