doc/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}