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