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