Merged revisions 77424,77429 via svnmerge from
[asterisk/asterisk.git] / doc / tex / sla.tex
1 %\documentclass[12pt,a4]{article}
2 %\usepackage{hyperref}
3
4 %\author{Russell Bryant \\ Software Engineer \\  Digium, Inc.}
5 %\title{Shared Line Appearances}
6
7 %\begin{document}
8 %\maketitle
9
10 %\tableofcontents
11
12 \section{Introduction}
13
14 The "SLA" functionality in Asterisk is intended to allow a setup that emulates
15 a simple key system.  It uses the various abstraction layers already built into
16 Asterisk to emulate key system functionality across various devices, including
17 IP channels.
18
19 \section{Configuration}
20
21 \subsection{Summary}
22
23 An SLA system is built up of virtual trunks and stations mapped to real
24 Asterisk devices.  The configuration for all of this is done in three
25 different files: extensions.conf, sla.conf, and the channel specific
26 configuration file such as sip.conf or zapata.conf.
27
28 \subsection{Dialplan}
29
30 The SLA implementation can automatically generate the dialplan necessary for
31 basic operation if the "autocontext" option is set for trunks and stations in
32 sla.conf.  However, for reference, here is an automatically generated dialplan
33 to help with custom building of the dialplan to include other features, such as
34 voicemail (\ref{voicemail}).
35
36 However, note that there is a little bit of additional configuration needed if
37 the trunk is an IP channel.  This is discussed in the section on trunks (\ref{trunks}).
38
39 There are extensions for incoming calls on a specific trunk, which execute the SLATrunk
40 application, as well as incoming calls from a station, which execute SLAStation.
41 Note that there are multiple extensions for incoming calls from a station.  This is
42 because the SLA system has to know whether the phone just went off hook, or if the
43 user pressed a specific line button.
44
45 Also note that there is a hint for every line on every station.  This lets the SLA
46 system control each individual light on every phone to ensure that it shows the
47 correct state of the line.  The phones must subscribe to the state of each of their
48 line appearances.
49
50 Please refer to the examples section for full dialplan samples for SLA.
51
52 \subsection{Trunks}
53 \label{trunks}
54
55 An SLA trunk is a mapping between a virtual trunk and a real Asterisk device.
56 This device may be an analog FXO line, or something like a SIP trunk.  A trunk
57 must be configured in two places.  First, configure the device itself in the
58 channel specific configuration file such as zapata.conf or sip.conf.  Once the
59 trunk is configured, then map it to an SLA trunk in sla.conf.  
60
61 \begin{verbatim}
62 [line1]
63 type=trunk
64 device=Zap/1
65 \end{verbatim}
66
67 Be sure to configure the trunk's context to be the same one that is set for the
68 "autocontext" option in sla.conf if automatic dialplan configuration is used.
69 This would be done in the regular device entry in zapata.conf, sip.conf, etc.
70 Note that the automatic dialplan generation creates the SLATrunk() extension
71 at extension 's'.  This is perfect for Zap channels that are FXO trunks, for
72 example.  However, it may not be good enough for an IP trunk, since the call
73 coming in over the trunk may specify an actual number.
74
75 If the dialplan is being built manually, ensure that calls coming in on a trunk
76 execute the SLATrunk() application with an argument of the trunk name, as shown
77 in the dialplan example before.
78
79 IP trunks can be used, but they require some additional configuration to work.
80
81 For this example, let's say we have a SIP trunk called "mytrunk" that is going
82 to be used as line4.  Furthermore, when calls come in on this trunk, they are
83 going to say that they are calling the number "12564286000".  Also, let's say
84 that the numbers that are valid for calling out this trunk are NANP numbers,
85 of the form \_1NXXNXXXXXX.
86
87 In sip.conf,  there would be an entry for [mytrunk].  For [mytrunk], 
88 set context=line4.
89
90
91 \begin{verbatim}
92 [line4]
93 type=trunk
94 device=Local/disa@line4_outbound
95 \end{verbatim}
96
97
98 \begin{verbatim}
99 [line4]
100 exten => 12564286000,1,SLATrunk(line4)
101
102 [line4_outbound]
103 exten => disa,1,Disa(no-password|line4_outbound)
104 exten => _1NXXNXXXXXX,1,Dial(SIP/\${EXTEN}@mytrunk)
105 \end{verbatim}
106
107
108 So, when a station picks up their phone and connects to line 4, they are
109 connected to the local dialplan.  The Disa application plays dialtone to the
110 phone and collects digits until it matches an extension.  In this case, once
111 the phone dials a number like 12565551212, the call will proceed out the
112 SIP trunk.
113
114 \subsection{Stations}
115
116 An SLA station is a mapping between a virtual station and a real Asterisk device.
117 Currently, the only channel driver that has all of the features necessary to
118 support an SLA environment is chan\_sip.  So, to configure a SIP phone to use
119 as a station, you must configure sla.conf and sip.conf.  
120
121 \begin{verbatim}
122 [station1]
123 type=station
124 device=SIP/station1
125 trunk=line1
126 trunk=line2
127 \end{verbatim}
128
129 Here are some hints on configuring a SIP phone for use with SLA:
130
131 \begin{enumerate}
132 \item Add the SIP channel as a [station] in sla.conf.
133
134 \item Configure the phone in sip.conf.  If automatic dialplan configuration was
135    used by enabling the "autocontext" option in sla.conf, then this entry in
136    sip.conf should have the same context setting.
137
138 \item On the phone itself, there are various things that must be configured to
139    make everything work correctly:
140
141    Let's say this phone is called "station1" in sla.conf, and it uses trunks
142    named "line1" and line2".
143    \begin{enumerate}
144   
145    \item Two line buttons must be configured to subscribe to the state of the
146       following extensions:
147         - station1\_line1
148         - station1\_line2
149
150    \item The line appearance buttons should be configured to dial the extensions
151       that they are subscribed to when they are pressed.
152
153    \item If you would like the phone to automatically connect to a trunk when it
154       is taken off hook, then the phone should be automatically configured to
155       dial "station1" when it is taken off hook.
156         
157    \end{enumerate}      
158 \end{enumerate}
159
160
161 \section{Configuration Examples}
162 \subsection{Basic SLA}
163
164 This is an example of the most basic SLA setup.  It uses the automatic
165 dialplan generation so the configuration is minimal.
166
167 sla.conf:
168 \begin{verbatim}
169 [line1]
170 type=trunk
171 device=Zap/1
172 autocontext=line1
173
174 [line2]
175 type=trunk
176 device=Zap/2
177 autocontext=line2
178
179 [station](!)
180 type=station
181 trunk=line1
182 trunk=line2
183 autocontext=sla_stations
184
185 [station1](station)
186 device=SIP/station1
187
188 [station2](station)
189 device=SIP/station2
190
191 [station3](station)
192 device=SIP/station3
193         
194 \end{verbatim}
195
196 With this configuration, the dialplan is generated automatically.  The first
197 zap channel should have its context set to "line1" and the second should be
198 set to "line2" in zapata.conf.  In sip.conf, station1, station2, and station3
199 should all have their context set to "sla\_stations".
200
201 For reference, here is the automatically generated dialplan for this situation:
202 \begin{verbatim}
203 [line1]
204 exten => s,1,SLATrunk(line1)
205
206 [line2]
207 exten => s,2,SLATrunk(line2)
208
209 [sla_stations]
210 exten => station1,1,SLAStation(station1)
211 exten => station1_line1,hint,SLA:station1_line1
212 exten => station1_line1,1,SLAStation(station1_line1)
213 exten => station1_line2,hint,SLA:station1_line2
214 exten => station1_line2,1,SLAStation(station1_line2)
215
216 exten => station2,1,SLAStation(station2)
217 exten => station2_line1,hint,SLA:station2_line1
218 exten => station2_line1,1,SLAStation(station2_line1)
219 exten => station2_line2,hint,SLA:station2_line2
220 exten => station2_line2,1,SLAStation(station2_line2)
221
222 exten => station3,1,SLAStation(station3)
223 exten => station3_line1,hint,SLA:station3_line1
224 exten => station3_line1,1,SLAStation(station3_line1)
225 exten => station3_line2,hint,SLA:station3_line2
226 exten => station3_line2,1,SLAStation(station3_line2)    
227 \end{verbatim}
228
229
230 \subsection{SLA and Voicemail}
231 \label{voicemail}
232
233 This is an example of how you could set up a single voicemail box for the
234 phone system.  The voicemail box number used in this example is 1234, which
235 would be configured in voicemail.conf.
236
237 For this example, assume that there are 2 trunks and 3 stations.  The trunks
238 are Zap/1 and Zap/2.  The stations are SIP/station1, SIP/station2, and
239 SIP/station3.
240
241 In zapata.conf, channel 1 has context=line1 and channel 2 has context=line2.
242
243 In sip.conf, all three stations are configured with context=sla\_stations.
244
245 When the stations pick up their phones to dial, they are allowed to dial
246 NANP numbers for outbound calls, or 8500 for checking voicemail.
247
248
249 sla.conf:
250 \begin{verbatim}
251 [line1]
252 type=trunk
253 device=Local/disa@line1_outbound
254
255 [line2]
256 type=trunk
257 device=Local/disa@line2_outbound
258
259 [station](!)
260 type=station
261 trunk=line1
262 trunk=line2
263
264 [station1](station)
265 device=SIP/station1
266
267 [station2](station)
268 device=SIP/station2
269
270 [station3](station)
271 device=SIP/station3
272         
273 \end{verbatim}
274
275
276 extensions.conf:
277 \begin{verbatim}
278 [macro-slaline]
279 exten => s,1,SLATrunk(${ARG1})
280 exten => s,n,Goto(s-${SLATRUNK_STATUS}|1)
281 exten => s-FAILURE,1,Voicemail(1234|u)
282 exten => s-UNANSWERED,1,Voicemail(1234|u)
283
284 [line1]
285 exten => s,1,Macro(slaline|line1)
286
287 [line2]
288 exten => s,2,Macro(slaline|line2)
289
290 [line1_outbound]
291 exten => disa,1,Disa(no-password|line1_outbound)
292 exten => _1NXXNXXXXXX,1,Dial(Zap/1/${EXTEN})
293 exten => 8500,1,VoicemailMain(1234)
294
295 [line2_outbound]
296 exten => disa,1,Disa(no-password|line2_outbound)
297 exten => _1NXXNXXXXXX,1,Dial(Zap/2/${EXTEN})
298 exten => 8500,1,VoicemailMain(1234)
299
300 [sla_stations]
301
302 exten => station1,1,SLAStation(station1)
303 exten => station1_line1,hint,SLA:station1_line1
304 exten => station1_line1,1,SLAStation(station1_line1)
305 exten => station1_line2,hint,SLA:station1_line2
306 exten => station1_line2,1,SLAStation(station1_line2)
307
308 exten => station2,1,SLAStation(station2)
309 exten => station2_line1,hint,SLA:station2_line1
310 exten => station2_line1,1,SLAStation(station2_line1)
311 exten => station2_line2,hint,SLA:station2_line2
312 exten => station2_line2,1,SLAStation(station2_line2)
313
314 exten => station3,1,SLAStation(station3)
315 exten => station3_line1,hint,SLA:station3_line1
316 exten => station3_line1,1,SLAStation(station3_line1)
317 exten => station3_line2,hint,SLA:station3_line2
318 exten => station3_line2,1,SLAStation(station3_line2)
319         
320 \end{verbatim}
321
322 \section{Call Handling}
323 \subsection{Summary}
324
325 This section is intended to describe how Asterisk handles calls inside of the
326 SLA system so that it is clear what behavior is expected.
327
328 \subsection{Station goes off hook (not ringing)}
329
330 When a station goes off hook, it should initiate a call to Asterisk with the
331 extension that indicates that the phone went off hook without specifying a
332 specific line.  In the examples in this document, for the station named
333 "station1", this extension is simply named, "station1".
334
335 Asterisk will attempt to connect this station to the first available trunk
336 that is not in use.  Asterisk will check the trunks in the order that they
337 were specified in the station entry in sla.conf.  If all trunks are in use,
338 the call will be denied.
339
340 If Asterisk is able to acquire an idle trunk for this station, then trunk
341 is connected to the station and the station will hear dialtone.  The station
342 can then proceed to dial a number to call.  As soon as a trunk is acquired,
343 all appearances of this line on stations will show that the line is in use.
344
345 \subsection{Station goes off hook (ringing)}
346
347 When a station goes off hook while it is ringing, it should simply answer
348 the call that had been initiated to it to make it ring.  Once the station
349 has answered, Asterisk will figure out which trunk to connect it to.  It
350 will connect it to the highest priority trunk that is currently ringing.
351 Trunk priority is determined by the order that the trunks are listed in
352 the station entry in sla.conf.
353
354 \subsection{Line button on a station is pressed}
355
356 When a line button is pressed on a station, the station should initiate a
357 call to Asterisk with the extension that indicates which line button was
358 pressed.  In the examples given in this document, for a station named
359 "station1" and a trunk named "line1", the extension would be "station1\_line1".
360
361 If the specified trunk is not in use, then the station will be connected to it and
362 will hear dialtone.  All appearances of this trunk will then show that it
363 is now in use.
364
365 If the specified trunk is on hold by this station, then this station will be
366 reconnected to the trunk.  The line appearance for this trunk on this station
367 will now show in use.  If this was the only station that had the call on hold,
368 then all appearances of this trunk will now show that it is in use.  Otherwise,
369 all stations that are not currently connected to this trunk will show it
370 on hold.
371
372 If the specified trunk is on hold by a different station, then this station
373 will be connected to the trunk only if the trunk itself and the station(s) that
374 have it on hold do not have private hold enabled.  If connected, the appeareance
375 of this trunk on this station will then show in use.  All stations that are not
376 currently connected to this trunk will show it on hold.
377
378 %\end{document}