Asterisk Overview and Interfacing with APAN Server Pujan Srivastava: pujan@ait.asia interlab Asian Institute of Technology February 14, 2012 1
o Asterisk Introduction o Asterisk Dialplan o Asterisk CLI o Audio Codecs o Conferencing o Interfacing with APAN o Debugging Agenda 2
Asterisk Introduction
Asterisk Asterisk: Open Source and Free PBX all features create a great framework for innovative telephony related applications. Asterisk Features: o o o o o o o o o o o o Automated Attendant Call Detail Records Call Forwarding Call Recording Call Routing Call Monitoring Conference Bridging Interactive Voice Response(IVR) Music on Hold Voicemail Text- to- Speech Fax Transmit and Receive 4
Asterisk ConCiguration Files 5
Asterisk Dial Plan
Dialplan The heart of Asterisk system How to handle inbound and outbound calls Fully customizable If you familiar with programming logic, you can do Dialplan easily. Asterisk Dialplan is located in: /etc/asterisk/extensions.conf Dialplan is made up of 4 concepts: Contexts Extensions Priorities Applications 7
Dialplan Fundamentals è Dialplan \ile components è Contexts, which consist of è Extensions, which have è Number/Extension which is being called è Priority for Application(s) Starting from 1 till N è Applications(with,some,arguments,optionally) EXTENSION SYNTAX exten => extension, Priority, Application(Arg1,Arg2..ArgN) Static Any String Number Asterisk application 8
Contexts The Asterisk dialplan is divided into sections. Each section is called a context, de\ined as [context_name] Contexts are mutually exclusive exten 123 may exist in context1 and context2. Contexts may include other contexts (recursively) using: include => name_of_the_other_context Example: [default] exten => 2,1,BackGround(hello-world) exten => 2,2,Hangup() exten => 201,1,Dial(SIP/test1) [201] type=friend host=dynamic secret=mysecret disallow=all allow=gsm 9
Context extensions.conf is the main \ile for the dialplan. Other.conf \iles also plays an important role. There are a handful of reserved context names that have special meaning to Asterisk. Other context are arbitrarily de\ined by *. [default] and [local] are for special purpose. [default] include => internal [local] exten => 3000,1,Dial(SIP/3000) exten => 3001,1,Dial(SIP/3001) [outbound] exten => _[66]XXX,1,Dial(SIP/to-10.1.101.1/${EXTRN}) [internal] include => outbound include => local [from-10.1.101.1] include => local This context is accessed when a call arrives from IP 10.1.101.1 over SIP 10
Extensions In Asterisk an extension is the name of a grouping of instructions in the dialplan. Think extension as a script name. Within each context, we de\ine one or more extensions. Extensions specify decisions for calls. Extensions de\ine a unique series of steps for Asterisk to handle a call Syntax: exten => number,priority,application() name: number of extension to be dialed priority: the step number application(): performs action/command. Ex playing a music. Example: exten => 999,1,Answer() 11
Special Extensions The s extension: The \irst entry in any extension is always the name or number dialed by the caller. When a call comes in from the PSTN, however, Asterisk doesn't know what was dialed or whom the caller is trying to reach. For any scenario in which we cannot determine the number dialed, we use the s extension. exten => s,1,answer() exten => s,2,wait(1) exten => s,3,play(tt-monkeys) exten => s,4,wait(1) exten => s,5,hangup() 12
Special Extensions The i extension: (i invalid) which handles all dialed numbers which are not explicitly handled within the context. To get the dialed number while in i extension, use ${INVALID_EXTEN}. Example: Employees in department B can only dial extensions 100 to 199. Callers dialing any other numbers hear the message, "I'm sorry. That is not a valid extension. Please try again. [department-b] exten => _1XX,1,Dial(${EXTEN}) exten => i,1,noop(an invalid number ${INVALID_EXTEN} was dialed.) exten => i,2,answer() exten => i,3,playback(invalid.gsm) exten => i,4,hangup() 13
EXTEN ${EXTEN}. Using patterns and variables, it is often possible to dramatically compress a long dialplan. exten => 100,1,Dial(SIP/100) exten => 101,1,Dial(SIP/101) exten => 102,1,Dial(SIP/102) exten => 103,1,Dial(SIP/103) exten => 104,1,Dial(SIP/104) exten => 105,1,Dial(SIP/105) exten => 106,1,Dial(SIP/106) exten => 107,1,Dial(SIP/107) exten => 108,1,Dial(SIP/108) exten => 109,1,Dial(SIP/109) exten => _10X,1,Dial(SIP/${EXTEN}) 14
Unnumbered priorities We can use n which stands for next without using a numeric character Example: exten => 501,1,Wait(2) exten => 501,2,Record(abc.gsm) exten => 501,3,Wait(2) exten => 501,4,Playback(abc.gsm) exten => 501,5,Hangup() exten => 501,1,Wait(2) exten => 501,n,Record(abc.gsm) exten => 501,n,Wait(2) exten => 501,n,Playback(abc.gsm) exten => 501,n,Hangup() 15
Polishing Extension If dialed digits do not match in current context, Asterisk goes to the 'i' extension (in the current context) If no dialed digits after timeout, Asterisk goes to the 't' extension. If these extensions do not exist, then hung up. exten => i,1,background(invalid&extension) exten => i,n,goto(s,1) exten => t,1,background(please-try-again) exten => t,n,goto(s,1) 16
Relationships # cat extensions.conf [default] exten => 2,1,BackGround(hello-world) exten => 2,2,Hangup() exten => 201,1,Dial(SIP/test1) exten => 202,1,Dial(SIP/test2) # cat sip.conf [test1] type=friend host=dynamic secret=mysecret1 disallow=all allow=gsm [test2] type=friend host=dynamic secret=mysecret2 disallow=all allow=gsm 17
Relationships Asterisk SIP Server (202.29.192.142) 3030 18
Pattern Matching 19
Building an interactive Dialplan Background(): Same as Playback(), but it can be interrupted when a user press any keys exten => 123,1,Answer() exten => 123,n,Background(main-menu) WaitExten(): Wait for a user to enter DTMF digits exten => 123,1,Answer() exten => 123,n,Background(main-menu) exten => 123,n,WaitExten(10) 20
Goto() Goto() application is used to send the call to another context/ extension Goto() application makes it easy to programmatically move a call between different parts of the dialplan. Goto(context,extension,priority) [incoming] exten => 123,1,Answer() exten => 123,n,Background(main-menu) exten => 123,n,WaitExten() exten => 1,1,Playback(digits/1) exten => 1,n,Goto(incoming,123,1) exten => 2,1,Playback(digits/2) exten => 2,n,Goto(incoming,123,1) 21
Dial() application Dial() tells * to call to a destination (different network/devices). Dial() takes up to 4 arguments. Dial(dest,timeout,Options,URI) Timeout: Dial() will attempt to call to dest for this # of sec. Options: Dial(DAHDI/1,10,m) calling party will hear music instead of ringing. URI: rarely used argument. Passing to callee. exten => 123,1,Dial(DAHDI/1) ; Dial(transport/dest). Transport=DAHDI, SIP or IAX. exten => 124,1,Dial(DAHDI/1&DAHDI/2&SIP/Jane) ; dialing multiple destination/channels Note: DAHDI/1 means analog telephone channel 1 FXS connected to it. The Dial() application also allows to connect a remote VoIP endpoints. Dial(technology/user[:pass]@remotehost[:port][/remote_extension]) 22
Variables Variables in dialplan are used to reduce typing and add clarity. Variables CHANNEL and EXTEN are reserved by asterisk. CHANNEL is used for getting current channel name. EXTEN is used in pattern matching. Asterisk checks which number is actually dialed. exten => _1256428XXXX,1,Dial(DAHDI/G2/${EXTEN:7}) ; here * check the value of XXXX and dials XXXX. #extensions.conf john=sip/john [incoming] exten => 999,1,Dial( ${john} ) 23
System Reserved Variables ${ANSWEREDTIME}: The total elapsed time for the active connection in seconds. ${BLINDTRANSFER}: The name of the channel on the other side of a blind transfer. ${CHANNEL}: Name of the current channel. ${CONTEXT}: Name of the current context. ${EPOCH}: Current Unix time (# of sec elapsed since midnight UTC, Jan 1, 1970) ${EXTEN}: Currently dialed extension. ${ENV(VARIABLENAME)}: Environment variable VARIABLENAME ${HANGUPCAUSE}: Cause of connection hang- up. ${INVALID_EXTEN}: Used in the i extension and contains the dialed extension. ${PRIORITY}: Current priority in the current extension. ${TRANSFER_CONTEXT}: Context of a transferred call. ${UNIQUEID}: The unique ID for the current connection. ${SYSTEMNAME}: System name as de\ined as in /etc/asterisk/asterisk.conf. 24
Global variables Global variables are visible to all extensions in all contexts. Global variables should be declared in the [globals] context at the beginning of the extensions.conf \ile. #extensions.conf [globals] john=dahdi/1 [incoming] exten => 999,1,Dial( ${john} ) Example 1 [globals] pujan1=sip/pujan1 pujan2=sip/pujan2@203.159.31.xxx, [incoming] exten => 2,1,Dial(${pujan1},10) exten => 2,n,Playback(vm-nobodyavail) exten => 2,n,Hangup() exten => 3,1,Dial(${pujan2}) exten => 3,n,Playback(vm-nobodyavail) exten => 3,n,Hangup() Example 2 25
Asterisk CLI
CLI (Command Line Interface) root@localhost #asterisk r asterisk CLI > core show help sip show channels: Show active SIP channels sip show channel: Show detailed SIP channel info sip show inuse: List all inuse/limit sip show peers: Show de\ined SIP peers 27
Audio Codecs
g.711 (variants ulaw and ulaw) Waveform,64kbps, MOS=4.2 Adaptive PCM (g.721, g.726) Waveform, various bitrates and MOS g.729 Hybrid, proprietary, 8kbps, MOS=4.0 ilbc (Internet Low Bandwidth Codec) Hybrid, ~ 13-15kbps, > 4.0 MOS Freely- licensed version of proprietary Designed to withstand packet loss Audio Codecs Various Codecs available on Asterisk gsm Derived from classic cellphone technology Hybrid Various low (5-8kbs) rates Various (3.5-4.0) MOS values Speex Speex is an open source patent- free codec. is designed to work with sampling rates of 8 khz, 16 khz, and 32 khz and can compress audio signal to bitrates between 2 and 44 kbps. For use in VoIP telephony, the most usual choice is the 8 khz (narrow band) variant. Dynamically adaptive bitrates and so High- medium- low MOS variants. ConYigurable by Asterisk. (codecs.conf) MOS = Mean Opinion Score 1=Bad, 2=Poor, 3=Avg 4=v good, 5=Excellent 29
Audio Codecs In order to use various audio codecs, various important \iles: /etc/asterisk/sip_*.conf disallow=all allow=ulaw allow=alaw allow=gsm allow=speex ;allow=all ; turns on all installed codecs Note: see order of disallow and allow. 30
Codec in Twinkle Application 31
List of supported codec Audio Codecs asterisk*cli> core show codecs audio Disclaimer: this command is for informational purposes only. It does not indicate anything about your con\iguration. INT BINARY HEX TYPE NAME DESC -------------------------------------------------------------------------------- 1 (1 << 0) (0x1) audio g723 (G.723.1) 2 (1 << 1) (0x2) audio gsm (GSM) 4 (1 << 2) (0x4) audio ulaw (G.711 u-law) 8 (1 << 3) (0x8) audio alaw (G.711 A-law) 16 (1 << 4) (0x10) audio g726aal2 (G.726 AAL2) 32 (1 << 5) (0x20) audio adpcm (ADPCM) 64 (1 << 6) (0x40) audio slin (16 bit Signed Linear PCM) 128 (1 << 7) (0x80) audio lpc10 (LPC10) 256 (1 << 8) (0x100) audio g729 (G.729A) 512 (1 << 9) (0x200) audio speex (SpeeX) 1024 (1 << 10) (0x400) audio ilbc (ilbc) 2048 (1 << 11) (0x800) audio g726 (G.726 RFC3551) 4096 (1 << 12) (0x1000) audio g722 (G722) 32
Audio Codecs Modules root@host:# asterisk r asterisk*cli> module show like codec Module Count Description Use codec_ulaw.so mu-law Coder/Decoder 0 codec_adpcm.so Adaptive Differential PCM Coder/Decoder 0 codec_alaw.so A-law Coder/Decoder 0 codec_g726.so ITU G.726-32kbps G726 Transcoder 0 codec_dahdi.so Generic DAHDI Transcoder Codec Translato 0 codec_gsm.so GSM Coder/Decoder 0 codec_speex.so Speex Coder/Decoder 0 codec_g722.so ITU G.722-64kbps G722 Transcoder 0 codec_a_mu.so A-law and Mulaw direct Coder/Decoder 0 codec_lpc10.so LPC10 2.4kbps Coder/Decoder 0 10 modules loaded 33
Conferencing
Scheduling the Conference Why do you need to schedule a conference? o To manage multiple conferences simultaneously. o Different conferencing room, different requirement. There are 3 ways of schedule a conference in asterisk: 1. Write your own PHP code using free PHPAGI (asterisk supports) 2. Linux Scripting with crontab 3. Web- MeetMe (free and open- source) 35
MeetMe MeetMe is a conference bridge. It provides a simple but sophisticated conferencing functionality. This enables multiple callers to meet in a virtual conference room and converse with all other callers in the conference. It works with any kind of channel. (Softphone, Hardphone etc) If you dial 8000, it would add you to a conference room 8000. You can hang up to leave a conference. Others may come and go as they choose. 36
MeetMe root@host # asterisk - r asterisk*cli> core show applications like meetme - = Matching Asterisk Applications =- MeetMe: MeetMe conference bridge. MeetMeAdmin: MeetMe conference administration. MeetMeChannelAdmin: MeetMe conference Administration (channel speciyic). MeetMeCount: MeetMe participant count. - = 4 Applications Matching =- 37
MeetMe root@host # asterisk - r asterisk*cli> core show applications - = Registered Asterisk Applications =- AddQueueMember: Dynamically adds queue members ADSIProg: Load Asterisk ADSI Scripts into phone AgentLogin: Call agent login - - - - - MeetMe: MeetMe conference bridge - - - - - - = 173 Applications Registered =- 38
MeetMe Features 1. Mute/Unmute 2. Lock/Unlock conferences 3. Eject last user to join conference 4. increase conference volume 5. decrease conference volume 6. increase own volume 7. decrease own volume 8. Kick users 9. Limit the number of participants. 39
Meetme meetme : List all conferences. meetme list conference : List the participants in the speci\ied conference. meetme kick conference participant : Kicks a participant out of the conference. meetme kickall conference : Kicks all participants out of the conference. meetme lock conference : Locks a conference to new participants. meetme unlock conference : Unlocks a previous lock (see above). meetme mute conference participant : meetme unmute conference participant : Mute a conference participant. Unmute a conference participant 40
Conference Monitoring Problems in conferencing Many participants means many audio sources (mute/ unmute) Audio looping 3 Options to make a conference better Mute Unmute Drop the troubling participant out Encrypted (password or pin) 41
MeetMe ConCigurations You need to edit 2 \iles in order to create a conference (1) /etc/asterisk/meetme_additional.conf [rooms] ; conf => conference- number[,pin] conf => 100070, conf => 100080,123456 (2) /etc/asterisk/extensions_additional.conf 42
/etc/asterisk/extensions_additional.conf MeetMe ConCigurations [ext- meetme] include => ext- meetme- custom exten => STARTMEETME,1,ExecIf($["${MEETME_MUSIC}"!= ""]?SetMusicOnHold(${MEETME_MUSIC})) exten => STARTMEETME,n,Set(GROUP(meetme)=${MEETME_ROOMNUM}) exten => STARTMEETME,n,GotoIf($[${MAX_PARTICIPANTS} > 0 && ${GROUP_COUNT(${MEETME_ROOMNUM}@meetme)}>$ {MAX_PARTICIPANTS}]?MEETMEFULL,1) exten => STARTMEETME,n,MeetMe(${MEETME_ROOMNUM},${MEETME_OPTS},${PIN}) exten => STARTMEETME,n,Hangup exten => MEETMEFULL,1,Playback(im- sorry&conf- full&goodbye) exten => MEETMEFULL,n,Hangup exten => h,1,hangup exten => 100070,1,Macro(user- callerid,) exten => 100070,n,Set(MEETME_ROOMNUM=100070) exten => 100070,n,Set(MAX_PARTICIPANTS=0) exten => 100070,n,Set(MEETME_MUSIC=default) exten => 100070,n,GotoIf($["${DIALSTATUS}" = "ANSWER"]?USER) exten => 100070,n,Answer exten => 100070,n,Wait(1) exten => 100070,n(USER),Set(MEETME_OPTS=oTcM) exten => 100070,n,Playback(custom/Test1) exten => 100070,n,Goto(STARTMEETME,1) ; end of [ext- meetme] 43
MeetMe ConCigurations m - - set monitor only mode (Listen only, no talking) t - - set talk only mode. (Talk only, no listening) p - - allow user to exit the conference by pressing # d - - dynamically add conference D - - dynamically add conference, prompting for a PIN e - - select an empty conference E - - select an empty pinless conference v - - video mode q - - quiet mode (don t play enter/leave sounds) M - - enable music on hold when the conference has a single caller x - - exit the conference if the last marked user left b - - run AGI script speci\ied in ${MEETME_AGI_BACKGROUND} s - - Present menu (user or admin) when * is received ( send to menu) a - - set admin mode w[(<secs>)] - - waits until the marked user enters the conference 44
Recording a Conference extensions_additional.conf [ext- meetme]... exten => 100080,n,Set(MEETME_RECORDINGFILE=${ASTSPOOLDIR}/ monitor/meetme- conf- rec- ${MEETME_ROOMNUM}- ${UNIQUEID})... ;[end- ext- meetme] Directory of Recorded file: /var/spool/asterisk/monitor Name of file: meetme- conf- rec- 100080- xxxxxxxx.wav Note: It will not record music- on- hold (moh). 45
extensions_additional.conf No. of Participants [ext- meetme]... exten => 100070,n,Set(MAX_PARTICIPANTS=0)... ;[end- ext- meetme] Unlimited = 0 Limited = Integer value. 46
Interfacing with APAN
Interfacing with APAN 48
Digium Card Has 4 slots. 2 each for: FXO (Foreign exchange Of\ice): connect to an analog line(pstn) FXS (Foreign exchange Station): connect to an analog phone FXS line can be connected to local PBX. Careful Do not connect PSTN line with FXS! 49
Kamailio(OpenSER) SIP Server ConCig #!ifdef WITH_PSTN pstn.gw_ip = "212.X.X.X" desc "PSTN GW Address... #!ifdef WITH_PSTN xlog("l_info","pujan's Call is routed: $rm from $fu $ru (IP:$si:$sp) \n\n\n"); if (strempty($sel(cfg_get.pstn.gw_ip))) { # checks if PSTN GW IP is defined xlog("script: PSTN routing enabled but pstn.gw_ip not defined\n"); return; } if( $ru=~"^(\+ 00)[6][6][2][5][2][4][6][6][1][9]$" ){ $ru = "sip:pujan@x.x.x.asia"; } if( $ru=~"^(\+ 00)[6][6][2][5][2][4][6][6][2][1]$" ){ $ru = "sip:1000700@ + $sel(cfg_get.pstn.gw_ip); } else if( $ru=~"^(\+)[9][4][8][1][2][0-9][0-9][0-9][0-9][0-9][0-9]$" ){ $ru = "sip:" + $ru + "@APAN_SIP_IP" ; # To APAN Server xlog("l_info","routing ALERT to APAN: ru=$ru \n"); } 50
Dahdi Now check your server can see the card with lspci [root@localhost ~]# lscpi 00:0d.0 Communication controller: Tiger Jet Net Inc. Tiger3XX Modem/ISDN interface. Create your trunk and extensions in FreePBX Now you can go on the admin interface of FreePBX and create your extension and trunks. To know which channel number is an FXO or an FXS, edit the \ile /etc/asterisk/dahdi- channels.conf. The section with context [from- internal] are for extensions. 51
Dahdi Scan run dahdi_scan and connect analog phone to port 3 or 4. (FXS)(from- internal) elastix*cli> dahdi show channels Chan Extension Context Language MOH Interpret Blocked State pseudo default default In Service 1 from-pstn default In Service 2 from-pstn default In Service 3 from-internal default In Service 4 from-internal default In Service elastix*cli> dahdi show status Description Alarms IRQ bpviol CRC4 Fra Codi Options LBO Wildcard TDM410P Board 1 OK 0 0 0 CAS Unk YEL 0 db (CSU)/0-133 feet (DSX-1) 52
Dahdi Scaning [root@elastix asterisk]# dahdi_scan [1] active=yes alarms=ok description=wildcard TDM410P Board 1 name=wctdm/0 manufacturer=digium devicetype=wildcard TDM410P (VPM100M) location=pci Bus 02 Slot 10 basechan=1 totchans=4 irq=177 type=analog port=1,fxo port=2,fxo port=3,fxs port=4,fxs 53
Debugging
Debugging o Check IP Connectivity Using ping command o Verify SIP listening port Using command netstat - na. root@interlab-77:~# netstat -na grep 5060 tcp 0 0 212.18.15.7:5060 0.0.0.0:* LISTEN udp 0 0 212.18.15.7:5060 0.0.0.0:* udp 0 0 0.0.0.0:5060 0.0.0.0:* o SIP Interaction check Asterisk console sip debug. It shows each sip packets \lowing through asterisk box. 55
Two ways of full debugging Full Debugging (1) Command Line # tail f /var/log/asterisk/full (2) FreePBX GUI (Colored Output) FreePBX > Menu > Tools > Asterisk LogYiles [Dec 12 09:47:06] WARNING[6782] pbx.c: Context 'app- fax' tries to include nonexistent context 'app- fax- custom' [Dec 12 09:47:06] WARNING[6782] pbx.c: Context 'ext- fax' tries to include nonexistent context 'ext- fax- custom' [Dec 12 09:47:06] NOTICE[6782] pbx_ael.c: AEL load process: veri\ied con\ig \ile name '/etc/asterisk/extensions.ael'. [Dec 12 09:47:06] NOTICE[6782] app_queue.c: queuerules.conf has not changed since it was last loaded. Not taking any action. [Dec 12 09:48:27] ERROR[6576] res_jabber.c: JABBER ERROR: No Connection [Dec 12 09:48:34] ERROR[6576] res_jabber.c: JABBER ERROR: No Connection [Dec 12 09:48:35] NOTICE[6598] chan_sip.c: Peer '300' is now Reachable. (47ms / 2000ms) Red Blue Yellow = ERROR = NOTICE = WARNING 56
Trunk Setup using FreePBX
Trunk Setup using FreePBX To send outgoing calls to another entity e.g. Kamailio (OpenSER) server, there are two steps: 1. Create a Trunk 2. Create an Outbound Route 58
Trunk Setup using FreePBX Scroll down to Outgoing Settings section and add the following trunk name and peer details: TRUNK NAME: to- bkk PEER DETAILS: Host=202.x.x.x Port=9060 Type=peer Qualify=no Insecure=port Disallow=all Allow=alaw&ulaw&gsm&g729 59
Trunk Setup using FreePBX Scroll down at the end of the page and add the registration string according to the following syntax in the Registration section. Leave the incoming setting blank here. Registration Setting username:password@202.x.x.x:9060 Add this setting as shown below and click submit button to save changes in the screen shot: 60
Trunk Setup using FreePBX Do not apply changes to make the changes permanent yet. You will see on the right side of the screen that your trunk has been saved. 61
Outbound Route In the Add Route page give the following details as shown in the screen shot: Route Name: to- bkk Dial Pattern: NXXXXXX NXXXXXXXXX 1NXXXXXXXXX 011. 9000 9001 911 62
63