SIP ( Session Initiation Protocol )

Update : At the time of writing this article on SIP and related VOIP technologies I was newbie in VOIP domain, probably just out college. However over the past decade, looking at the steady traffic to these articles, I have tried updating the same with new RFC standards and market trends. This is an updated version (2019).


The Session Initiation Protocol (SIP) is a multimedia signalling protocol that has evolved the defacto communication standard for IP telephony. Today it forms the primary protocol for many Real Time Communication platforms which are integrated with telecom carriers and provide Cloud and IP based Services for applications such as robo/mass calls for advertising, API based calls like OTP generator, IVR announcements with DTMF input like customer care centre etc. Infact it would be not far from truth to say that converged platform we find today are a result of SIP integrating with the IP world.

Converged platforms integrates audio, video, data, presence, instant messaging, voicemails and conference services into a single network . SIP is the key component to build an advanced converged IP communication platform or rich multimedia Real time communication service.

SIP can be used to create programmable APIs and complex call routing VoIP scripts such as PBX , SBC etc.

Bears the support of many high quality open source and freeware SIP client , servers , proxies , tool such as Kamailio, Astersk, Freeswitch, Sipp, JAINSIP etc. Also supported on most standardised VoIP hardware and network such as Cisco, Microsoft, Avaya, and Radvision.

It is standardized by Internet Engineering Task Force (IETF) such as RFC 3261 which describes SIP v2 . Architecturally SIP request response (404 , 301) format is very similar to HTTP and its addressing schemes have a resemblance to SMTP (sip:altanai@company.com).

SIP – Application layer protocol

We know the ISO OSI layers  which servers as a standard model for data communications .

  1. Physical Layer : Ethernet , USB , IEEE 802.11  WiFi, Bluetooth  , BLE
  2. Data Link Layer : ARP ( Address Resolution Protocol ) ,  PPP ( point to point protocol ) , MAC ( Media Access control ) , ATM , Frame Relay
  3. Network Layer :  IP (IPv4 / IPv6), ICMP, IPsec
  4. Transport : TCP , UDP , SCTP
  5. Session : PPTP ( Point to point tunnelling protocol) , NFS, SOCKS
  6. Presentation : Codecs such as JPEG , GIFF , SSL
  7. Application : Application level like Call -manager/ softphone  as HTTP , FTP , DNS , SIP  , RTSP , RTP , DNS

SIP is an application layer protocol

SIP and SDP as Application layer protocols

SIP ( Session Initiation Protocol) negotiates session between 2 parties. It primarily exchanges headers that are used for making a call session such as example of outgoing telephone call from SIP session invite.

Session Initiation Protocol (INVITE)
Request-Line: INVITE sip:altanai@telecomcompany.com;transport=tcp SIP/2.0
Method: INVITE
Request-URI: altanai@telecomcompany.com;transport=tcp
        Request-URI User Part: altanai
        Request-URI Host Part: telecomcompany.com
        [Resent Packet: False]

Message Header

Via: SIP/2.0/TCP 1.2.3.4:5080;rport;branch=z9hG4bKceX7a2H2866cN
        Transport: TCP
        Sent-by Address: 1.2.3.4
        Sent-by port: 5080
        RPort: rport
        Branch: z9hG4bKceX7a2H2866cN

Max-Forwards: 41

From: "+16014801797" <sip:+16014801797@1.2.3.4>;tag=7HKgjNQ6y2FSj
        SIP Display info: "+16014801797"
        SIP from address: sip:+16014801797@1.2.3.4
                SIP from address User Part: +16014801797
                E.164 number (MSISDN): 16014801797
                        Country Code: Americas (1)
                SIP from address Host Part: 1.2.3.4
        SIP from tag: 7HKgjNQ6y2FSj

To: <sip:altanai@telecomcompany.com;transport=tcp>
        SIP to address: sip:altanai@telecomcompany.com;transport=tcp
        SIP to address User Part: altanai
        SIP to address Host Part: telecomcompany.com
        SIP To URI parameter: transport=tcp

Call-ID: e10306be-0cfd-4b38-af3c-b2ada0827cef
CSeq: 126144925 INVITE
Contact: <sip:mod_sofia@1.2.3.4:5080;transport=tcp>
User-Agent: phone1
Allow: INVITE, ACK, BYE, CANCEL, OPTIONS, MESSAGE, INFO, UPDATE, REFER, NOTIFY
Supported: path, replaces
Allow-Events: talk, hold, conference, refer
Privacy: none
Content-Type: application/sdp
Content-Disposition: session
Content-Length: 249
SIP Display info: "+16014801797"
SIP PAI Address: sip:+16014801797@1.2.3.4

The SIP philosophy :

  • reuse Internet addressing (URLs, DNS, proxies)
  • utilize rich Internet feature set
  • reuse HTTP coding
  • text based
  • makes no assumptions about underlying protocol: TCP, UDP, X.25, frame, ATM, etc
  • support of multicast

SIP URI can either be in format of sip:altanai@telecomcompnay.com (RFC 2543 ) or sips:altanai@telecomcompany.com ( secure with TLS over TCP RFX 3261) . Additionally SIP URI resolution can either be

  • DNS SRV based such as altanai@telecomcompnay.com with SIP servers locating record for domain “telecomcompnay.com ” or
  • FQDN ( Fully qualified domain name ) / contact / ip address based such as altanai@2.2.2.2 or altanai@us-west1-prod-server . Both of which do not need any resolution for routing.

Tags are pseudo-random numbers inserted in To or From headers to uniquely identify a call leg

Max forwards  is a count decremented by each proxy
that forwards the request.When count goes to zero, request is discarded and 483 Too Many Hops response is sent.Used for stateless loop detection.

Content-Type indicates the type of message body attachment. In this case application /SDP but  others could be text/plain, application/cpl+xml, etc.)

Content-Length indicates the octet (byte) count of the message body

Contact direct route to contact the sender, composed of SIPURI with a user name and IP or FQDN. USed for later requests to directly reach the destination such as ACK after INVITE

via gives the last SIP hop as IP, transport, and transaction-specific parameters along with branch that identifies the transaction
each proxy adds an additional via header. fianlly via header is used to route back the responses . This ensures the user agents after the initial request dont have to rely on DNS and location tables to route the messages.

Firewalls can sometimes block SIP packets, change TCP to UDP or change IP address of the packets. Record-Route can be used, ensures Firewall proxy stays in path. Clients and Servers copy Record-Route and put in Route header for all messages.

Message body is separated from SIP header fields by a blank line (CRLF).

sip arch
SIP Message Body

SIP Request methods

  • INVITE : Initiates negotiation to establish a session ( dialog). Usually contains SDP payload.
  • Another invite during an existing session ( dialog) is called an RE-INVITE.  RE-INVITE can be used for hold / resume a call and change session parameters and codecs in mid of a call
  • ACK : Acknowledge an INVITE request by completing the 3 way handshake.
  • If an INVITE did not contain media contain then ACK must contain it .
  • BYE : Ends a session ( dialog).
  • CANCEL : Cancels a session( dialog)  before it establishes  .
  • REGISTER : Registers a user location (host name, IP) on a registrar SIP server.
  • OPTIONS : Communicates information about the capabilities of the calling and receiving SIP phones ( methods , extensions , codecs etc )
  • PRACK : Provisional Acknowledgement for provisional response as 183 ( session in progress). PRACK only application to 101- 199 responses .
  • SUBSCRIBE : Subscribes for Notification from the notifier. Can use Expire=0 to unsubscribe.
  • NOTIFY : Notifies the subscriber of a new event.
  • PUBLISH : Publishes an event to the Server.
  • INFO : Sends mid session information.
  • REFER : Asks the recipient to issue call transfer.
  • MESSAGE : Transports Instant Messages.
  • UPDATE : Modifies the state of a session ( dialog).

SIP responses :

  • 1xx = Informational SIP Responses

100 Trying
180 Ringing
183 Session Progress

  • 2xx = Success Responses

200 OK – Shows that the request was successful

  • 3xx = Redirection Responses
  • 4xx = Request Failures

401 Unauthorized
404 Not Found
405 Method Not Allowed
407 Proxy Authentication Required
408 Request Timeout
480 Temporarily Unavailable
481 Call/Transaction Does Not Exist
486 Busy Here
487 Request Terminated
488 Not Acceptable Here
482 Loop Detected
483 Too Many Hops

  • 5xx = Server Errors

500 Server Internal Error
503 Service Unavailable

  • 6xx = Global Failures

600 Busy Everywhere
603 Decline
604 Does Not Exist Anywhere
606 Not Acceptable

SIP callflow diagram for a Call Setup and termination using RTP for media and RTCP for control.

Read about SIP messages indepth here 

SDP ( Session Description Protocol)

SIP can bear many kinds of MIME attachments , one such is SDP. SDP contains session metadata used for establishing the session. It defines media information and capabilities such as codecs and formats , timestamps , termination points like address , ports. Additionally it can also convey other details like bandwidth and contact for the node acting as proxy for the session.

Read Indepth about SIP messages and SDP https://telecom.altanai.com/2014/01/03/sip-in-depth/(opens in a new tab)

Sample SDP payload for Invite SIP above :

Session Description Protocol Version (v): 0
Owner/Creator, Session Id (o): FreeSWITCH 1532932581 1532932582 IN IP4 1.2.3.4
        Owner Username: FreeSWITCH
        Session ID: 1532932581
        Session Version: 1532932582
        Owner Network Type: IN
        Owner Address Type: IP4
        Owner Address: 1.2.3.4
Session Name (s): FreeSWITCH
Connection Information (c): IN IP4 1.2.3.4
        Connection Network Type: IN
        Connection Address Type: IP4
        Connection Address: 1.2.3.4
Time Description, active time (t): 0 0
        Session Start Time: 0
        Session Stop Time: 0
Media Description, name and address (m): audio 29398 RTP/AVP 0 101
        Media Type: audio
        Media Port: 29398
        Media Protocol: RTP/AVP
        Media Format: ITU-T G.711 PCMU
        Media Format: DynamicRTP-Type-101
Media Attribute (a): rtpmap:0 PCMU/8000
        Media Attribute Fieldname: rtpmap
        Media Format: 0
        MIME Type: PCMU
        Sample Rate: 8000
Media Attribute (a): rtpmap:101 telephone-event/8000
        Media Attribute Fieldname: rtpmap
        Media Format: 101
        MIME Type: telephone-event
        Sample Rate: 8000
Media Attribute (a): fmtp:101 0-16
        Media Attribute Fieldname: fmtp
        Media Format: 101 [telephone-event]
        Media format specific parameters: 0-16
Media Attribute (a): silenceSupp:off - - - -
        Media Attribute Fieldname: silenceSupp
        Media Attribute Value: off - - - -
Media Attribute (a): ptime:20
        Media Attribute Fieldname: ptime
        Media Attribute Value: 20

v=0  indicates the start of the SDP content.

o=FreeSWITCH 1532932581 1532932582 IN IP4 1.2.3.4 , is session origin and owner’s name

c=IN IP4 1.2.3.4 is connection data specifing the IP address of session.  

m= is Media type – audio, port – 29398, RTP/AVP Profile – 0 and 101

Attribute profile – 0, codec – PCMU, sampling rate – 8000 Hz and Attribute profile – 101, telephone-event

SIP transaction

A SIP transaction occurs between a UAC and a UAS in form of 1 request , its provisional and final response.

All transactions are independent of each other. Each transaction are uniquely identified by the branch id on the via header and the cseq.

Via: SIP/2.0/UDP <server ip>:5060;branch=z9hG4bKcb16.c47db56d6d8eb62677a0f0dc733cd73d.0
...
CSeq: 1 INVITE

SIP transaction consists of a single request and any responses to that request, which include zero or more provisional responses and one or more final responses.

A transaction consists of a Request, any non-final (1xx) Responses received, and a final Response (2xx, 3xx, 4xx, 5xx, or 6xx).
ACK is not considered part of this transaction and is a new transaction.
Request whose responses to that are non succesfull such as INVITE response with 100, 405 then,
ACK is part of the transaction.
Hence , ror positive replies (2XX), a new transaction is created for ACK with new CONTACT header and it can be sent straight to the UAS bypassing the proxy. For negative replies, ACK stays part of INVITE transaction hence request is sent to the same proxy as INVITE.

Examples

for ACK given below , tid=-d8754z-deea18278a05ce16-1—d8754z-

T 2017/06/06 06:56:03.656614 :37126 -> :5060 [AP]
 ACK sip:9876543210@:5080;transport=tcp SIP/2.0.
 Via: SIP/2.0/TCP :38834;branch=z9hG4bK-d8754z-deea18278a05ce16-1---d8754z-;rport.
 Max-Forwards: 70.
 To: :5080>;tag=fdc0b562c1d44395f53d16b622397a3f-589d.
 From: >;tag=b5327b03.
 Call-ID: MTllYjkyZjczMjhjM2I5OGE4MTgzZDUxODVjYmM0YzY.
 CSeq: 1 ACK.
 Content-Length: 0.

For CANCEL given below , tid=-d8754z-04665556a3f8c928-1—d8754z-

T 2017/06/06 06:53:09.643301 :37126 -> :5060 [AP]
 CANCEL sip:9876543210@:5080;transport=tcp SIP/2.0.
 Via: SIP/2.0/TCP :38834;branch=z9hG4bK-d8754z-04665556a3f8c928-1---d8754z-;rport.
 Max-Forwards: 70.
 To: :5080>.
 From: >;tag=c0869612.
 Call-ID: NTJhMGU1ZTA1NTAyZTYzZmUzMWQ0NjQ2MjIwYTE0MmI.
 CSeq: 1 CANCEL.
 User-Agent: Bria 3 release 3.5.5 stamp 71243.
 Content-Length: 0.

SIP entities that have notion of transactions are called stateful.

Branch

The branch parameter is a transaction identifier. Responses relating a request can be correlated because they will contain the same transaction identifier.

Dialog

The p2p relationship between 2 sip endpoints , containing sequence of transactions, is called the dialog . The initiator of the session that generates the establishing INVITE generates the unique Call-ID and From tag. In the response to the INVITE, the user agent answering the request will generate the To tag. The combination of the local tag (contained in the From header field), remote tag (contained in the To header field), and the Call-ID uniquely identifies the established session, known as a dialog. This dialog identifier is used by both parties to identify this call because there could be multiple calls set up between them.

  • A dialog is uniquely identified by: Call-ID header , remote-tag and local-tag.
  • DialogId is different for both ends since local and remote for both ends are different.

Example : Notice the to and from tag ids in INVITE and its 200 ok. The dialog id for invite is , 97576NjQ5MTBlNjVjNDQ0MzFmOTEyZGEzYWJjZjQxYjcyYzc70edc66c. Since it is the first INVITE, it doesnt bear the To tag.

INVITE sip:1234567890@ SIP/2.0
   Via: SIP/2.0/UDP :59583;branch=z9hG4bK-524287-1---22728813bce01a15;rport
   Max-Forwards: 70
   Contact: :59583>
   To: >
   From: >;tag=70edc66c
   Call-ID: 97576NjQ5MTBlNjVjNDQ0MzFmOTEyZGEzYWJjZjQxYjcyYzc
   CSeq: 1 INVITE
   Allow: OPTIONS, SUBSCRIBE, NOTIFY, INVITE, ACK, CANCEL, BYE, REFER, INFO
   Content-Type: application/sdp
   Supported: replaces
   User-Agent: X-Lite release 5.5.0 stamp 97576
   Content-Length: 210

   v=0
   o=- 1559804173873191 1 IN IP4 
   s=X-Lite release 5.5.0 stamp 97576
   c=IN IP4 
   t=0 0
   m=audio 49750 RTP/AVP 8 101
   a=rtpmap:101 telephone-event/8000
   a=fmtp:101 0-15
   a=sendrecv

The dialog id, with reversed to and from tag in 200 ok response 97576NjQ5MTBlNjVjNDQ0MzFmOTEyZGEzYWJjZjQxYjcyYzcStNBKgjjXS84r70edc66c

SIP/2.0 200 OK
   Via: SIP/2.0/UDP :59583;branch=z9hG4bK-524287-1---22728813bce01a15;rport=10973;received=
   From: >;tag=70edc66c
   To: >;tag=StNBKgjjXS84r
   Call-ID: 97576NjQ5MTBlNjVjNDQ0MzFmOTEyZGEzYWJjZjQxYjcyYzc
   CSeq: 1 INVITE
   Contact: :5060;transport=udp>
   User-Agent: FreeSWITCH-mod_sofia/1.9.0-742-8f1b7e0~64bit
   Accept: application/sdp
   Allow: INVITE, ACK, BYE, CANCEL, OPTIONS, MESSAGE, INFO, UPDATE, REGISTER, REFER, NOTIFY, PUBLISH, SUBSCRIBE
   Supported: timer, path, replaces
   Allow-Events: talk, hold, conference, presence, as-feature-event, dialog, line-seize, call-info, sla, include-session-description, presence.winfo, message-summary, refer
   Session-Expires: 120;refresher=uas
   Content-Type: application/sdp
   Content-Disposition: session
   Content-Length: 222
   Remote-Party-ID: "1234567890" >;party=calling;privacy=off;screen=no

   v=0
   o=FreeSWITCH 1559778909 1559778910 IN IP4 
   s=FreeSWITCH
   c=IN IP4 
   t=0 0
   m=audio 25266 RTP/AVP 8 101
   a=rtpmap:8 PCMA/8000
   a=rtpmap:101 telephone-event/8000
   a=fmtp:101 0-16
   a=ptime:20

Matching in-dialog transactions/requests

The combination of the To tag, From tag, and Call-ID completely defines a peer-to-peer SIP relationship between endpoints and is referred to as a dialog.

Record Routing

All requests sent within a dialog are by default sent directly from one user agent to the other. Only requests outside a dialog traverse SIP proxies. This approach makes SIP network more scalable because only a small number of SIP messages hit the proxies.

However few request need to explicitly state that they need to stay on path of proxies such as for accounting during termination of when NAT process is being carried out then. For these we need to insert a Record-Route header field into SIP messages which contain address of the proxy. Messages sent within a dialog will then traverse all SIP proxies that put a Record-Route header field into the message.

The server copies the Record-Route header field unchanged into the response. (Record-Route is only relevant for 2xx responses) i.e. the end point recipient will also mirror the proxies for the response.

record routingwithout Record Routingrecord routing (1)with record routing

Strict Routing

Rewrite the Request-URI ie Request-URI always contained URI of the next hop so it is necessary to save the original Request-URI as the last Route header field.  Defined in RFC2543.

Loose routing

Request-URI is no more overwritten, it always contains URI of the destination user agent, therby keeping target seprated from route. ( ;lr). If there are any Route header field in a message, then the message is sent to the URI from the topmost Route header field. Defined in RFC 326.

SIP Authorization

Authentication , security , confidentiality and integrity form the basic requirement for any communication system . To protect against hacking a user account and Denial of service attacks , SIP uses HTTP digest authentication mechanism with nonces and challenges along with 407 Proxy Authorization required and 401 unauthorised .  The sender has to resend the request with MD5 hash of nonce and password ( password id never send in clear ). Thus preventing man-in-middle attacks.

Challenge / Response Scheme :

  • Sends REGISTER   and receives 401 / 407 Challenge + nonce 
  • Again sends REGISTER + MD-5 hash (pw + nonce) get a 200 OK

REGISTER using HTTP Digest for authentication using TLS transport, challenge is in form

CSeq: 1 REGISTER
WWW-Authenticate: Digest realm="atlanta.example.com", qop="auth",
nonce="ea9c8e88df84f1cec4341ae6cbe5a359", opaque="", stale=FALSE, algorithm=MD5

Here qop is Quality Of Protection param indicating quality of protection that the client has applied to the message. qop=1 (enabled) will help you to avoid replay attacks.

Here qop is Quality Of Protection param indicating

challenge response by UA to UAS

Authorization: Digest username="bob", realm="atlanta.example.com"
nonce="ea9c8e88df84f1cec4341ae6cbe5a359", opaque="",
uri="sips:ss2.biloxi.example.com",
response="dfe56131d1958046689d83306477ecc"

Cancellation of Registration – UA sends REGISTER request with Expires: 0 Contact: * , to apply to all . Since user is already authenticated , it is not challenged again .

To prevent spoofing ie impersonating as server , SIP provides server authentication too. Required by ITSP’s  ( Internet telephony service providers ) .

End to end encryption is achieved thorough TS and SRTP.

More on SIP Security here .

Mobility and Location Service

According to RFC 3263 Session Initiation Protocol (SIP): Locating SIP Servers , if the proxy finds that the request is for an outside domain , it will take help of a DNS server to resolve to IP address of target domain and forward the request. Then target domain proxy used REGISTRAR’s discovery services to find if user is present in the host via location table entry . If found then request reaches the user .

To provide session mobility SIP endpoints send Register request to their respective registrar as they move and update their location. As User changes terminals , they registers themselves to the appropriate server
– Location server tracks the location of user
– Redirect servers prioritise the possible locations of the user
– Users keep same services as located at home server, while mobile
Call is processed by home servers using RECORD-ROUTE

NAT ( Network Address Translator)

Network Address Translator, defined by RFC 3022 to conserve network space as most packets are exchanged inside a private network itself.

All internet users whether they are using Wifi , 3G/LTE,  home AP, any other telecom data packet network  by TSP or ISP , are assigned a private IP address , which is unreachable from out side world .Addresses are assigned by Internet Assigned Numbers Authority (IANA). Private address blocks are in format of 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16.

Therefore when they access the Internet , this address is converted into a  globally unique public IP address through a NAT for external communication

Screen Shot 2018-08-18 at 4.33.06 PM

SIP Issues around NAT

NATs modify IP addresses (Layer 3)- SIP/SDP are Layer 7 protocols – transparent to NAT

SIP Via:, From: and Contact: headers use not-routable private addresses
SDP states that originator wishes to receive media at not-routable private addresses
If destination on the public internet tries to send SIP or RTP traffic to those private address
Traffic will be dumped by first router

Solution are to use  either Application level gateway (ALG) or STUN or Universal Plug and Pray (UPnP)

To rewrite all SIP/SDP source addresses

  • SIP Via:, From: and Contact: headers use public NAT address
  • SDP addresses use NAT public address
  • Use SIP over TCP

Use draft-ietf-sip-symmetric-response-00 and “Symmetric” SIP/RTP
Use same UDP port number for incoming/outgoing
Hold ports open for call duration
Send UDP packet typically every 30 seconds
SIP over UDP uses 30 second re-INVITE, REGISTER or OPTIONs
RTP sends at much higher frequency by default

NAPT ( Network Address Port Translator )Can map multiple private IP addresses and ports to one public IP address and ports

To adapt SIP to modern IP networks with inter network traversal ICE, far and near-end NAT traversal solutions are used. Network Address traversal is crtical to traffic flow between private public network and from behind firewalls and policy controlled networks

Opensource STUN / TURN prooviders : google STUN server, mySTUN , TurnServer, reStund , CoTURN , NATH (PJSIP NAT Helper), ReTURN, or ice4j

Near-end NAT traversalFar-end NAT traversal
STUN (session traversal utilities for NAT) – UA itself detect presence of a NAT and learn the public IP address and port assigned using NAting. Then it replaces device local private IP address with it in the SIP and SDP headers. Implemented va STUN, TURN, and ICE.
(-) doesnt work for symmetric NAT (single connection has a different mapping with a different/randomly generated port)
(-) doesnt work when there are multiple addresses of a end point.

TURN (traversal using relay around NAT) or STUN relay – UA learns the public IP address of the TURN server and asks it to relay incoming packets.
(-) since it handled all incoming and outgong traffic , it must scale to meet traffic requirments and should not become the bottleneck junction or single point of failure.
UA is not concerned about NAT at all and communicated using its local IP port. The border controller implies a NAT handling compoenets such as an application layer gateway (ALG) or universal plug and play (UPnP) etc which resolves the private and public network address mapping by act as a back to back user agent (B2BUA).
ICE (interactive connectivity establishment) – UA gathers “candidates of communication” with priorities offered by the remote party. After this client pairs local candidates with received peer candidates and performs offer-answer negotiating by trying connectivity of all pairs, therefore maximising success. The types of candidates
– host candidate who represents clients’ IP addresses,
– server reflexive candidate for the address that has been resolved from STUN
– relayed candidate for the address which has been allocated from a TURN relay by the client.
Far end NAT can also be enabled by deploying a public SIP server which performs media relay (RTP Proxy/Media proxy).

(-) security risks : operating in public network enabling reverse traffic from UAS to UAC behind NAT.

A keep-alive mechanism is used to keep NAT translations of communications between SIP endpoint and its serving SIP servers opened , so that this NAT translation can be reused for routing. It contains client-to-server “ping” keep-alive and corresponding server-to-client “pong” messages. The 2 keep-alive mechanisms: a CRLF keep-alive and a STUN keep-alive message exchange.

SIP Flows

Screen Shot 2018-08-16 at 10.11.14 PM
Components of SIP based VoIP Solution

Registration

Localization Server  –Used by the Proxy Server and Redirect Server to obtain the location of the called user (one or more addresses)

Registration Server- Accept registration requests from the client applications . Generally, the service is offered by the Proxy Server or Redirect Server

DNS Server – Used to locate the Proxy Server or Redirect Server using NAPTR or SRV records

The 3 types of SIP URIs,

  • address of record (AOR)
  • fully qualified domain name (FQDN)
  • globally routable user agent (UA) URI
  • SIP uniform resource identifiers (URIs) are identified based on DNS resolution since the URI after @ symbol contains hostname , port and protocol for the next hop.

Adding record route headers for locating the correct SIP server for a SIP message can be done by :
DNS service record (DNS SRV)
naming authority pointer (NAPTR) DNS resource record

Steps for SIP endpoints locating SIP server

  1. From SIP packet get the NAPTR record to get the protocl to be used
  2. Inspect SRV record to fetch port to use
  3. Inspect A/AAA record to get IPv4 or IPv6 addresses
    ref : RFC 3263 – Locating SIP Servers
    Can use BIND9 server for DNS resolution supports NAPTR/SRV, ENUM, DNSSEC, multidomains, and private trees or public trees.

Screen Shot 2018-08-18 at 12.46.14 PM

Call Redirection

Sending Call invite but as Redirect Server responded with 302 moved temporary , a new destination address is returned. The invite is forwarded to another proxy server which connects the sip endpoints again after consultation with Redirect server .

Screen Shot 2018-08-18 at 10.37.38 AM

In this stage of we see the call getting connected to sip endpoint via 2 proxy servers . The redirect server doesnt get into path once the initial sip request is send.

Screen Shot 2018-08-18 at 11.12.17 AM

After communication the endpoints send BYE to terminate the session

Screen Shot 2018-08-18 at 11.13.59 AM

Forking

This callflow deals with the use-case when a user maybe registered from multiple SIP phones ( perhaps one home phone , one car and one office desk etc ) and wants to receive a ring on all registered phone ie fork a call to multiple endpoints .

Screen Shot 2018-08-18 at 11.17.19 AM

In the above diagram we can see a forked invite going to both the sip phones . Both of them reply with 100 trying and 180 ringing, but only 1 gets answered by the user .

Screen Shot 2018-08-18 at 11.17.26 AM

After one endpoint sends 200 ok and connects with session , the other receiver a cancel from the sip server .

Screen Shot 2018-08-18 at 11.17.33 AM

Click to Dial

A web or desktop application which has HTTP can fire a API call which is interpreted by the controller or SIP server  and call is fired.

Screen Shot 2018-08-18 at 1.23.36 PM

The API can contain params for to and from sip addresses as well as any authentication  token that is required for api authentication and validation .

Source code for some of the SIP application described above are on github at https://github.com/altanai/sip-servlets

SIMPLE (SIP for Instant Messaging and Presence Leveraging Extensions )

  • several vendors who intend to implement SIMPLE
  • provides for presence and buddy lists
  • Instant Messaging in the enterprise
  • telephony enabled user lists

Using SIP based Call routing algorithms and flows , one can build carrier grade communication solution . SIP solutions can hook up with existing telecom networks and service providers to be backward compatible . Also has untapped unlimited potential to integrate with any external IP application or service to provide converged , customised control both for signalling and media planes.

References :

  1. SIP servlets samples : https://github.com/altanai/sip-servlets
  2. SIP by Henning Schulzrinne Dept. of Computer Science Columbia University New York
  3. International Institute of Telecommunications 2000-2004
  4. Introduction to SIP by Patrick Ferriter from ZULTYS
  5. Internet Draft, IETF, RFC 2543
  6. NTU – Internet Telephony based on SIP

RFC 3665 – Session Initiation Protocol (SIP) Basic Call Flow Examples

It contains SIP implementation examples such as

  • SIP Registration – Successful New Registration, Update of Contact List, Request for Current Contact List, Cancellation of Registration, Unsuccessful Registration
  • SIP Session Establishment
  • Session Establishment Through Two Proxies,
  • Session with Multiple Proxy Authentication,
  • Successful Session with Proxy Failure,
  • Session Through a SIP ALG,
  • Session via Redirect and Proxy Servers with SDP in ACK,
  • Session with re-INVITE (IP Address Change),
  • Unsuccessful No Answer, Unsuccessful Busy, Unsuccessful No Response from User Agent, Unsuccessful Temporarily Unavailable,
  • Security Considerations

RFC 5359 – Session Initiation Protocol Service Examples

It contains the description for services like

  • Call Hold, Consultation Hold, Music on Hold,
  • Transfer – Unattended, Transfer – Attended, Transfer – Instant Messaging,
  • Call Forwarding Unconditional, Call Forwarding – Busy, Call Forwarding – No Answer,
  • 3-Way Conference – Third Party Is Added, 3-Way Conference – Third Party Joins, Find-Me ,
  • Call Management (Incoming Call Screening) , Call Management (Outgoing Call Screening) ,
  • Call Park , Call Pickup , Automatic Redial , Click to Dial.

UC(Unified Communications) and Unified Communications and Collaborations ( UC&C )


The rapidly changing scene of telecoms operations brings to light many challenges faced by telcos and service providers as they cater to the end-users, with swift and innovative services, while at the same time keeping surcharge operational costs at bay. Today a customer(B2B) expects converged orchestrated harmonized applications bringing call control and customizing features, all under one roof.

What is Unified Communication ? 

Unified Communications solutions bring together voice, messaging, video, and desktop applications to enable companies to quickly adapt to market changes, increase productivity, improve competitive advantage and deliver a rich-media experience across any work space.

Unified Communications (1)
Unified Communications

Components of Unified Communications

The latest UCC solutions are based on open standards such as  SIMPLE/XMPP protocols or socket.io and REST webservices

  • Communications:                                        Voice, data, and video
  • Messaging:                                                     Voice, email, video, and IM
  • Conferencing:                                               Online, audio, and video
  • Application integration:                          Microsoft Office and CRM
  • Presence:                                                       IP phone, desktop clients, and call connectors
  • Common user experience:                     Desktop, phone, and mobility
  • Cloud / Virtualization                               Network Provisioning , Virtualized Applications

Video feature of UCC further has many aspects

  • Codecs : H323,H264,vp8/vp9 for video
  • Scalable Video Coding (SVC)
  • USecase : Call , conference , Broadcasting , Livestreaming

Audio aspects

  • Codecs like OPUS, AAC
  • Service like : voice Mail , IVR , auto attendant with Voice XML

What is Unified communication and Collaboration ?

Currently the mode of communication across various users differs such as emails , SMS, VOIP call , GSM call, message on other platform etc .These random forms of communication cannot be tracked thus hamper fast decision making .

uc

Challenges with Unified Communications

  • Adds complexity in to already complex infrastructure
  • Lack of standardization
  • Organization Infrastructure and Bandwidth Limitations
  • Integration of services from different application platforms like emails
  • migrating existing communication infrastructure like desk phones
  • Interfacing of telephony applications with Business Applications such as CRMs

Types of UCC solutions

There exists broadly two types of UC&C solution – On-premise and cloud based . The fundamental difference is the location of the backend infrastructure supporting the communication system . Some more differences are outlined in table below:

On -premiseCloud Based
Mostly in SaaS nature ( software as a service )

 

Hosted by the consumer / business unit itself
more customizability and flexibility
more investment and maintenance

Service provider offers his infrastructure to the consumer as a service  
bills monthly / yearly etc
quick setup
lower upfront payment
billing is either per user basis or on consumption .
data is synced to cloud servers for storage and can be fetched from there when required such as cloud synced Call-logs or contact-book

Device / Platform Agnostic

The UCC clients are designed keeping mobility in mind . Thus UC  Solutions are made compatible with online provisioning / portal system , native mobile apps like android /ios , Desktop app for linux, mac, windows etc .

Unified Communications

UC&C + CRM

UC&C models integrates with Enterprise and Customer Relation Management Systems (CRM). Therefore provides unified messaging across teamspace/workspace/workflow management systems . It is trackable and can be used for realtime notification and analytics .

SRS TFX service suite (2)
SRS TFX service suite
SRS TFX service suite (1)

This directly ensures boost in sales and profitability by quick communication between customers / partners / eco-system / sales-rep / developers / field agents and others part of the communication system.

SME adopt UCC solutions

SME ( Small and Medium Enterprises) are first to adopt UC&C due to absence of  already setup traditional communication infrastructure like PSTN lines , desktop phones , special handsets etc .

Factors that enable SMEs to adopt UC&C solution much faster and readily. :

  • quick setup
  • low budget of UC&C solutions
  •  BYOD ( Bring your Own Device ) to work

The advantages

  • (+) All information is stored in one place therefore easier to retrieve
  • (+) Increased Productivity
  • (+) Greater flexibility
  • (+) Faster Response and Information delivery

 Future of UCC

  1. Context Driven + Real Time Analytics
  2. Monitization by cross vertical integration
  3. Integration with IOT
  4. Automation for Billing and Operation – OSS/BSS
  5. Machine Learning
  6. Big Data Management

In conclusion UC&C is aimed at providing inter operable communications with ubiquitous coverage for applications and devices such as desktops , IP phones , smartphones, smart watches , kisosk etc. It means web , native apps and IP phones having the ability to create, share and participate in integrated multimedia ( like audio, video , desktop, files ) collaboration.


Mobicents SIP server platform

We know that SIP is in the p2p session layer of the OSI mode and used to setup voip sessions and that a SIP Servlets must be executed within a SIP Servlets Container, which implements the SIP Servlet specification. Mobicents sip servlets have been extensively used to create , deploy and manage VOIP services. Also it has a converged application server where a web application is composed of one or more HTTP Servlets and one or more SIP Servlets.

Mobicents runs atop Jboss Application server and integrates sip protocol stack. Its roles

  • Handle the communication with the client.
  • Persist the data and handle communication with the database.
  • Execute the Beans which is a server-side component that encapsulates the business logic of an application
  • Provide clustering, fail-over and load-balancing.
  • Local memory access / caching.
  • Manage transactions

The Mobicent server bears 50% resemblance to Rhino TAS .

Mobicents application routers

Mobicents Sip Servlets ships with a default application router (DAR) which selects which application to execute in a container for a request.

So far , I have successfully done the following

1. installed the Mobicent platform on Linux machine
2.set up the environment to build and deploy the applications

sip server types

1.Mobicents as registrar

registrar is aware of the IP address of the client so when UA wants to opena dialog it contacts registrar for the address of the callee

2. Back to back user agent on mobicents sip server

B2BUA acts as an endpoint for two other agents and forwards requests and responses between those two agents. Unlike proxy servers , B2nua server maintain state for dialogs and transactions.

3. proxy application using Mobicents sip servlets

A SIP proxy is an agent which stands in the path of two UA. The proxy is used only for the INVITE request and answer. The following ACK is then sent directly from one UA to another. The main purpose of the SIP proxy is to route the INVITE request between the UA’s.

4. Mobicents as sip load balancer

The Mobicents SIP load balancer acts as an entry-point for the cluster. Can handle both SIP and HTTP traffic. Distributes the SIP messages among the alive nodes ( use a attributable algorithm) after checking their heartbeat.

The load balancer appends itself to the Via header of each request. Thus, responses are sent to the SIP load balancer before they are sent to the originating SIP application

tbd : Attached are the screen shots of the same .

1. User agent client (UAC) Dialog
2. User agent server (UAS) Dialog
3. Mobicent slee management console
4. Joboss status console
5. Admin console depicting applications installed .

JSR 116 – SIP SERVLET 1.0

SIP Servlet 1.0 API

•JSR 116
•Built into the Servlet container that also hosts  portlets and HTTP Servlets.
•SIP Servlet API developed under the JCP (Java Community Process) as JSR 116 (Java Specification Request), as a set of neutral interfaces

Servlet Container

•Environment in which a servlet can exist
•Loads and initializes a servlet
•Invokes the appropriate methods when SIP messages arrive

Servlets

•Class with a service method, compiled into a Servlet Archive File  (SAR)

Deployment descriptors

•XML based file with configuration information  and message matching rules
sip msg1
—————————————————————————————–

Freeswitch Integration with Telecom Carrier

This articles is a follow up of the earlier freeswitch capability introduction and some generic usecases around dialplans and contexts. This post contains instructions on how to integrate your SIP VOIP Freeswitch server to ITSP ( Internet Telephony Service Providers) which are basically part of large telecommunications companies.

First we check the external profile via sofia status . We should’ve configured the internal ip to listen to domain address or public ip. The external profile on port 5080 is used for outgoing and incoming connections .

Screen Shot 2018-09-28 at 9.32.31 AM

Create a user profile for interacting with outside world

<include>
<user id="1001">
<params>
<param name="password" value="pass1234"/>
</params>
</user>
</include>

Next we should try and register any sip softphone with the freeswitch server . I used Xlite , screenshot below

Screen Shot 2018-09-28 at 9.30.07 AM

Configuring a SIP gateway  in sip_profiles -> external

Goto /usr/src/freeswitch-debs/freeswitch/conf/vanilla/sip_profiles/external and create a profile such as telco_profile.xml

<include>
<gateway name="telcoCompany">
<param name="realm" value="sip.2600hz.com"/>
<param name="username" value="admin"/>
<param name="password" value="123456"/>
<param name="register" value="true"/>
</gateway>
</include>

and add the bridge to dialplan under usage

<extension name="telco gateway bridge">
<condition field="destination_number" expression="^(\d{10})$">
<action application="bridge" data="sofia/gateway/telcoCompany/$1"/>
</condition>
</extension>

note $1 contains the dialled number which will be passed to bridge to telcoCompany gateway. Therefore to add prefix for USA use +1$1 or for India +91$1 (  E.164 format) or some inline variable such as ${customercode}$1

After adding reloadxml and also run sofia profile external rescan to let freeswitch find the gateways

Monitoring gateways using OPTIONS

<param name="ping" value="20"/>

Codec Negotiation 

Late negotiations reduces re-sampling and codec changes

<param name="inbound-late-negotiation" value="true"/>

Other dial plan variables can also be set such as absolute_codec_string, inherit_codec , ep_codec_string. To avoid any codec negotiation on SDP use bypass_media=true .

<param name="inbound-codec-prefs" value="${global_codec_prefs}"/>
<param name="outbound-codec-prefs" value="${outbound_codec_prefs}"/>
<param name="inbound-codec-negotiation" value="generous"/>

CDR ( Call Detail Records )

can be used with modules mod_xml_cdr , mod_csv_cdr , mod_cdr_mongodb, mod_odbc_cdr , mod_cdr_pg_csv , mod_cdr_sqlite , mod_json_cdr , mod_radius_cdr

<configuration name="cdr_csv.conf" description="CDR CSV Format">
<settings>
<!-- 'cdr-csv' will always be appended to log-base -->
<!--<param name="log-base" value="/var/log"/>-->
<param name="default-template" value="example"/>
<!-- This is like the info app but after the call is hung up -->
<!--<param name="debug" value="true"/>-->
<param name="rotate-on-hup" value="true"/>
<!-- may be a b or ab -->
<param name="legs" value="a"/>
<!-- Only log in Master.csv -->
<!-- <param name="master-file-only" value="true"/> -->
</settings>
<templates>
<template name="sql">INSERT INTO cdr VALUES ("${caller_id_name}","${caller_id_number}","${destination_number}","${context}","${start_stamp}","${answer_stamp}","${end_stamp}","${duration}","${billsec}","${hangup_cause}","${uuid}","${bleg_uuid}", "${accountcode}");</template>
...
</templates>
</configuration>

event socket library (ESL)

tbd

Freeswitch Modules

modules supported on freeswitch

This section describes some of the popular and useful freeswitch module . Although there are many more modules , I have picked a few of commonly used one and divided them into following categories :

  • Loggers
  • XML Interfaces
  • Event Handlers
  • Application
  • Language
  • ASR/TTS

Loggers

mod_console
mod_graylog2
mod_logfile
mod_syslog

mod_yaml

Multi-Faceted
mod_enum is a dialplan interface, an application interface and an api command interface
mod_enum

XML Interfaces

mod_xml_rpc
mod_xml_curl
mod_xml_cdr
mod_xml_radius
mod_xml_scgi

Event Handlers

mod_amqp

mod_cdr_csv

log call detail records (CDRs) to a text file using text generation templates as in /conf/autoload_configs/cdr_csv.conf.xml

<configuration name="cdr_csv.conf" description="CDR CSV Format">
<settings>
<param name="default-template" value="example"/>
<param name="rotate-on-hup" value="true"/>
<!-- may be a b or ab -->
<param name="legs" value="a"/>
</settings>
<templates>
<template name="sql">INSERT INTO cdr VALUES ("${caller_id_name}","${caller_id_number}","${destination_number}","${context}","${start_stamp}","${answer_stamp}","${end_stamp}","${duration}","${billsec}","${hangup_cause}","${uuid}","${bleg_uuid}", "${accountcode}");</template>
</templates>
</configuration>

mod_cdr_sqlite
mod_event_multicast
mod_event_socket
mod_event_zmq
mod_zeroconf
mod_erlang_event
mod_smpp
mod_snmp

Directory Interfaces
mod_ldap

Endpoints

When any of the endpoints are loaded , they start listening for connection using configuration file . Dialstring identifies the recipient of the channel such as sofia/external/098099999 where sofia is the dial string prefix for SIP.

mod_portaudio
mod_alsa
mod_sofia – SIP protocol support

mod_gsmopen –  Supports voice & SMS over a GSM network

mod_h323 – H.323 , ITU rich media communication protocol.

mod_opal – IAX2

mod_skypopen – Skype (discontinued )

mod_dingaling – Jingle , Google Talk, XMPP integration ( discontinued )

mod_verto

mod_rtc

mod_loopback

mod_woomera

mod_freetdm – Provides support for telephony cards from manufacturers such as Digium, Sangoma and Zaptel. Can communicate in most legacy telephony protocols such as ISDN, SS7 & analog

mod_unicall

mod_skinny

mod_khomp

mod_rtmp

RTMP protocol is primarily used by Flash for streaming audio, video, and data over the Internet.

Applications

mod_commands

mod_conference

inbound and outbound conference bridge, loaded from file  conf/autoload_configs/conference.conf.xml
mod_curl

mod_db

-tbd

mod_dptools

Dialplan tools provide the apps (commands) to process call sessions in XML dialplans.

answer

Answer the call for a channel.

<!-- a sample IVR( Interactive Voice Response ) -->
<extension name="ivr">
<condition field="destination_number" expression="^9000$">
    <action application="answer"/>
    <action application="sleep" data="1000"/>
    <action application="ivr" data="demo_ivr"/>
</condition>
</extension>

att_xfer

Attended Transfer.

bgsystem

Execute an operating system command in the background.

bind_digit_action – Bind a key sequence or regex to an action.

bind_meta_app

Respond to certain DTMF sequences on specified call leg(s) during a bridge and execute another dialplan application.

block_dtmf

Block DTMFs from being sent or received on the channel.

break

Cancel an application currently running on the channel.

bridge

Bridge a new channel to the existing one.

bridge_export

Export a channel variable across any bridge.

capture

Capture data into a channel variable.

chat

Send a text message to an IM client

check_acl

Block originating address unless it matches an ACL.Test the i.p. address that originates the call against an Access Control List or CIDR mask

  • clear_digit_action – Clear all digit bindings
  • clear_speech_cache – Clear speech handle cache.
  • cluechoo – Console-only “ConCon” choo-choo train
  • cng_plc – Packet Loss Concealment on lost packets + comfort noise generation
  • conference – Establish an inbound or outbound conference call
  • db – insert information into the database.
  • deflect – Send a call deflect/refer.
  • delay_echo – Echo audio at a specified delay.
  • detect_speech – Implements speech recognition.
  • digit_action_set_realm – Change binding realm.
  • displace_session – Displace audio on a channel.
  • early_hangup – Enable early hangup on a channel.

eavesdrop

Spy on a channel.

<extension name="eavesdrop">
<condition field="destination_number" expression="^88(\d{4})$|^\*0(.*)$">
    <action application="answer"/>
    <action application="eavesdrop" data="${hash(select/${domain_name}-spymap/$1$2)}"/>
</condition>
</extension>

echo

Echo audio and video back to the originator.

enable_heartbeat

Enable Media Heartbeat.

endless_playback

Continuously play file to caller.

enum – Perform E.164 lookup.
erlang – Handle a call using Erlang.
eval – Evaluates a string.
event – Fire an event.

execute_extension

Execute an extension from within another extension and return.

export

Export a channel variable across a bridge <varname>=<value>

fax_detect – Detect FAX CNG – may be deprecated.
fifo – Send caller to a FIFO queue.
fifo_track_call – Count a call as a FIFO call in the manual_calls queue.
flush_dtmf – Flush any queued DTMF.
gentones – Generate TGML tones.
group – Insert or delete members in a group.

hangup

Hang up the current channel.

<extension name="show_info">
<condition field="destination_number" expression="^9192$">
<action application="answer"/>
<action application="info"/>
<action application="sleep" data="250"/>
<action application="hangup"/>
</condition>
</extension>

hash – Add a hash to the db.
hold – Send a hold message.

httapi

Send call control to a Web server with the HTTAPI infrastructure

info – Display Call Info.
intercept – Lets you pickup a call and take it over if you know the uuid.

ivr

Run an IVR menu.

javascript – Run a JavaScript script from the dialplan
jitterbuffer – Send a jitter buffer message to a session
limit – Set a limit on number of calls to/from a resource
limit_execute – Set the limit on a specific application
limit_hash – Set a limit on number of calls to/from a resource
limit_hash_execute – Set the limit on a specific application
log – Logs a channel variable for the channel calling the application
loop_playback – Playback a file to the channel looply for limted times
lua – Run a Lua script from the dialplan
media_reset – Reset all bypass/proxy media flags.
mkdir – Create a directory.
multiset – Set multiple channel variables with a single action.
mutex – Block on a call flow, allowing only one at a time
page – Play an audio file as a page.
park – Park a call.
park_state – Park State.
phrase – Say a Phrase.
pickup – Pickup a call.
play_and_detect_speech – Play while doing speech recognition.
play_and_get_digits – Play and get Digits.
play_fsv – Play an FSV file. FSV – (FS Video File Format) additional description needed
playback – Play a sound file to the originator.
pre_answer – Answer a channel in early media mode.[old wiki]
preprocess – description needed
presence – Send Presence
privacy – Set caller privacy on calls.
queue_dtmf – Send DTMF digits after a successful bridge.
read – Read Digits.
record – Record a file from the channel’s input.
record_fsv – Record a FSV file. FSV – (FS Video File Format) additional description needed
record_session – Record Session.
recovery_refresh – Send a recovery refresh.
redirect – Send a redirect message to a session.
regex – Perform a regex.
remove_bugs – Remove media bugs.
rename – Rename file.
respond – Send a respond message to a session.
ring_ready – Indicate Ring_Ready on a channel.
rxfax – Receive a fax as a tif file.

say

Say time/date/ip_address/digits/etc. With pre-recorded prompts.
sched_broadcast – Enable Scheduled Broadcast.
sched_cancel – Cancel a scheduled future broadcast/transfer.
sched_hangup – Enable Scheduled Hangup.
sched_heartbeat – Enable Scheduled Heartbeat.
sched_transfer – Enable Scheduled Transfer.
send_display – Sends an info packet with a sipfrag.
send_dtmf – Send inband DTMF, 2833, or SIP Info digits from a session.
send_info – Send info to the endpoint.
session_loglevel – Override the system’s loglevel for this channel.
set – Set a channel variable for the channel calling the application.
set_audio_level – Adjust the read or write audio levels for a channel.
set_global – Set a global variable.
set_name – Name the channel.
set_profile_var – Set a caller profile variable.
set_user – Set a user.
set_zombie_exec – Sets the zombie execution flag on the current channel.
sleep – Pause a channel.
socket – Establish an outbound socket connection.
sound_test – Analyze Audio.
speak – Speaks a string or file of text to the channel using the defined TTS engine.[old wiki]
soft_hold – Put a bridged channel on hold.
start_dtmf – Start inband DTMF detection.
stop_dtmf – Stop inband DTMF detection.
start_dtmf_generate – Start inband DTMF generation.
stop_displace_session – Stop displacement audio on a channel.
stop_dtmf_generate – Stop inband DTMF generation.
stop_record_session – Stop Record Session.
stop_tone_detect – Stop detecting tones.
strftime – Returns formatted date and time.
system – Execute an operating system command.
three_way – Three way call with a UUID.
tone_detect – Detect the presence of a tone and execute a command if found.
transfer – Immediately transfer the calling channel to a new extension.[old wiki]
translate – Number translation.
unbind_meta_app – Unbind a key from an application.
unset – Unset a variable.
unhold – Send a un-hold message.
verbose_events – Make ALL Events verbose (Make all variables appear in every single event for this channel).
wait_for_silence – Pause processing while waiting for silence on the channel.
wait_for_answer – Pause processing while waiting for the call to be answered.

API

chat – Send a text message to a IM client.
presence – Send Presence.
strepoch – Returns the date/time as a UNIX epoch (seconds elapsed since midnight UTC, January 1, 1970).
strftime – Returns formatted date and time.
strftime_tz – Returns formatted date and time in the timezone specified.
mod_expr
mod_fifo
mod_hash
mod_mongo
mod_voicemail
mod_directory
mod_distributor
mod_lcr
mod_easyroute
mod_esf
mod_fsv
mod_cluechoo
mod_valet_parking
mod_fsk
mod_spy
mod_sms
mod_smpp
mod_random
mod_httapi
mod_translate

SNOM Module
mod_snom

This one only works on Linux for now
mod_ladspa

Dialplan Interfaces
mod_dialplan_directory
mod_dialplan_xml
mod_dialplan_asterisk

Codec Interfaces
mod_spandsp
mod_g723_1
mod_g729
mod_amr
mod_ilbc
mod_h26x
mod_vpx
mod_b64
mod_siren
mod_isac
mod_opus

File Format Interfaces
mod_sndfile
mod_native_file
mod_png
mod_shell_stream
For icecast/mp3 streams/files
mod_shout
For local streams (play all the files in a directory)
mod_local_stream
mod_tone_stream

Timers
mod_timerfd
mod_posix_timer

Languages

These scripting languages allow programming the call routing logic

mod_v8

FreeSWITCH has support for the Google V8 JavaScript (ECMAScript) engine. It needs to be uncommented in the modules.conf file

Screen Shot 2018-09-27 at 6.34.04 PM

mod_perl

mod_python

mod_java

mod_lua

ASR /TTS

mod_flite

mod_pocketsphinx
mod_cepstral
mod_tts_commandline
mod_rss

Say
mod_say_en
mod_say_ru
mod_say_zh
mod_say_sv

Third party modules
mod_nibblebill
mod_callcenter

FreeSwitch SIP and Media Server

FreeSWITCH is free and open source communications software licensed under Mozilla Public License. It if often the core of voice core to provider call routing and media control . Its core library, libfreeswitch, is capable of being embedded into other projects, as well as being used as a stand-alone application.

 FreeSWITCH is designed to route and interconnect popular communication protocols using audio, video, text, or any other form

of media. First released in January 2006, FreeSWITCH has grown to become the world’s premier open source soft-switch

platform. This versatile platform is used to power voice, video, and chat communications on devices ranging from single calls on

a Raspberry Pi to large server clusters handling millions of calls. FreeSWITCH powers a number of commercial products

from start-ups to Carriers.

– freeswitch.com

It can perform the functions of  ( but not limited to )

  • PBX Server (Transcoding B2BUA)
  • IVR & Announcement Server
  • Conference host
  • Voicemail
  • Session Border Controller
  • Text to Speech (TTS)
  • VOIP endpoint
  • Class 5 softswitch

Freeswitch has a modular architecture which is both scalable and customisable. The most important modules are , Endpoint , dialplan and Application .

Application is the instruction added for a particular dial plan with an extension object. Data Arguments are also passed to an application. Examples like Set: configure extension parameter , Bridge: bridge a new channel to the existing one , Answer: answer the call for a channel , Hangup: hangup a current channel , Run an IVR menu etc

Protocols set up call legs/ channels , negotiate codecs and stream media.The endpoint module helps to bridge channels between different protocol supported endpoints . SIP being the most popular protocol for voip session is implemented by mod_sofia module while RTP is inbuild into freeswitch core . SRTP ( media protocol for webrtc ) is provided by mod_verto.

Architecture and Design of Freeswitch

Freeswitch can form the basis of complicated and sophisticated communications backend framework with thousand CPS(Call per second ) . It can connect to VOIP ( voice over IP ) as well as PSTN ( Public Switched Telephone network ) and PRI ( Primary Rate Interfaces – used in enterprises communication)

Core

Data strutters are opaque and operations can be invoke by APIs with routines getting maximum reuse .

Threaded Model 

Enables parallel operation as every connection has its own thread. Event handlers push incoming events into threads .  Sub system run in background threads .

Freeswitch

Channel Variables

Channel variables are used to manipulate dialplan execution, to control call progress, and to provide options to applications. They play a pervasive role, as FreeSWITCH™ frequently consults channel variables as a way to customize processing prior to a channel’s creation, during call progress, and after the channel hangs up.

Expansion

  • $${variable} is expanded once when FreeSWITCH™ first parses the configuration on startup or after invoking reloadxml. It is suitable for variables that do not change, such as the domain of a single-tenant FreeSWITCH™ server.

<param name=”domain” value=”$${domain}”/>

  • ${variable} is expanded during each pass through the dialplan, so it is used for variables that are expected to change, such as the ${destination_number} or ${sip_to_user} fields.

Setting a channel variable :

<application="set" data="rtp_secure_media=true"/>

Reading a channel variable:

<route service="E2U+SIP" regex="sip:(.*)" replace="sofia/${use_profile}/$1;transport=udp"/>

Exporting channel variables in bridge operations

  • from one to another call leg using export_var
  • exporting to a list using export application
<action application="export" data="dialed_extension=$1"/>

Custom channel variables can be defined anytime too such as

<action application="set" data="conference_auto_outcall_caller_id_name=Mad Boss"/>

Also channel variables can be limited to scope on an extension . An example of passing some channel variable to log application .

<action application="log" data="INFO Inbound call CallUUID ${call_uuid} SIPCallID ${sip_call_id}- from ${caller_id_number} to ${destination_number}"/>

If the conditions are not met, optional anti-actions are executed.

<name="is_secure" continue="true">
<-- Only Truly consider it secure if its TLS and SRTP -->
<condition field="${sip_via_protocol}" expression="tls"/>
<condition field="${rtp_secure_media_confirmed}" expression="^true$">
    <action application="sleep" data="2000"/>
    <action application="playback" data="misc/call_secured.wav"/>
    <anti-action application="eval" data="not_secure"/>
<condition>
<extension>

Inline actions are executed during the hunting phase of dialplan

Dialplan

A Dialplan is designed to lookup list of instructions from the central XML registry within FreeSWITCH. In general dialplans are used to route a dialed call to an endpoint based on the extension and its  condition. When a matching extension is found , it executes its actions . The combination of the above can create detailed control and call flow plans . FS uses Perl-compatible regular expressions (PCRE) for pattern matching. Few formats

  • sofia/profile2/8765@1.2.3.4 , will dial out 8765 at host 1.2.3.4 using profile2
  • sofia/gateway/gateway11.com/5432 , will dial through a Gateway (SIP Provider) to user 5432
  • sofia/profile2/8765@1.2.3.4;transport=tcp , dialing with specific transport like TCP, UDP, TLS, or SCTP.
  • {absolute_codec_string=PCMU}sofia/external/sip:9106@${local_ip_v4}:5080 , to specify the codecs

Speak Time and Date on Call

when dialed number matches regular expression 9172 , then call is answered , put to sleep for 1 seconds and using say application current date and time is said , then application hangs up .

<include>
<extension name="speak_date_time" >
<condition field="destination_number" expression="^9172$">
    <action application="answer"/>
    <action application="sleep" data="1000"/>
    <action application="say" data="en CURRENT_DATE_TIME pronounced ${strepoch()}"/>
    <action application="hangup"/>
</condition>
</extension>
</include>

There may be 3 kinds of contexts  :

  1. default  : used for all internal users  such as PBX . Local_Extension can route the call between internal users .
  2. public  : used by external world users such as DID
  3. features : other custom in call features using bind_meta_app application etc

Call Routing based on destination number and forwarding to voice mail on no answer

Configure the sip driver to use the custom context while processing the call such as ,

<profile name="telco_custom_sipprofile">
    <param name="context" value="custom_sipcontext"/>
...
</profile>

When call arrives for destination 501 , the condition matches and this blocks action are executed such as in example below .
Exetnsion 501 rings , when not answered it sleeps or 1 seconds , then gets forwarded to voice mail .

If the call to 501 was answered ie handed off then further actions would not be executed

<context name="custom_sipcontext">
<extension name="501">
<condition field="destination_number" expression="^501$">
    <action application="bridge" data="user/501"/>
    <action application="answer"/>
    <action application="sleep" data="1000"/>
    <action application="bridge" data="loopback/app=voicemail:default ${domain_name} ${dialed_extension}"/>
</condition>
</extension>
</context>

Call routing based on day and time

<extension name="Time of day, day of week setup" continue="true">
<condition wday="2-6" hour="8-16 break="never">
<action application="set" data="office_status=open" inline="true"/>
<anti-action application="set" data="office_status=closed" inline="true"/>
</condition>
<condition wday="2-6" time-of-day="1:30-2:30" break="never">
<action application="set" data="office_status=lunch" inline="true"/>
</condition>
</extension>

inline= true states that channel variables will be used for later reference while break=never and continue=true tell the program to keep looking for more condition matches incase of failed or successful match respectively

Match incoming network IP address with pre configured IP

Store incoming number to $1 variable and bridge the call with custom profile . Read more about sip profiles in sections below .

<extension name="ipmatch">
<condition field="network_addr" expression="^198\.168\.1\.0$"/>
<condition field="destination_number" expression="^(\d+)$">
    <action application="bridge" data="sofia/customprofile/$1@198.168.2.0"/>
</condition>
</extension>

Note : $1 varibles value is not available outside of the condition block
Store captured values in standard variables 

<action application=”set” data=”domain_name=$${domain}”/>

Following example store stores destination_number ( freeswitch variable ) into ‘dialed_number’

<extension name="ipmatch_variable">
<condition field="destination_number" expression="^(\d+)$">
    <action application="set" data="dialed_number=$1"/>
</condition>
<condition field="network_addr" expression="^192\.168\.1\.1$">
    <action application="bridge" data="sofia/customprofile/${dialed_number}@192.168.2.2"/>
</condition>
</extension>

Playback

Media recording and playback in audio (wav)

<extension name="recording">
<condition field="destination_number" expression="^(4444)$">
    <action application="answer"/>
    <action application="set" data="playback_terminators=#"/>
    <action application="record" data="/tmp/audiofile.wav 20 200"/>
</condition>
</extension>

<extension name="playback">
<condition field="destination_number" expression="^(5555)$">
    <action application="answer"/>
    <action application="set" data="playback_terminators=#"/>
    <action application="playback" data="/tmp/audiofile.wav"/>
</condition>
</extension>

Routing by listening on the audio stream for a touch-tone * followed by a single digit.

If the called user dials *1, then the execute_extension::dx XML features command is executed.

<extension name="Local_Extension">
<condition field="destination_number" expression="^(10[01][0-9])$">
    <action application="export" data="dialed_extension=$1"/>
    <!-- bind_meta_app can have these args <key> [a|b|ab] [a|b|o|s] <app> -->
    <action application="bind_meta_app" data="1 b s execute_extension::dx XML features"/>
    <action application="bind_meta_app" data="2 b s record_session::${recordings_dir}/${caller_id_number}.${strftime(%Y-%m-%d-%H-%M-%S)}.wav"/>
    <action application="bind_meta_app" data="3 b s execute_extension::cf XML features"/>
    <action application="bind_meta_app" data="4 b s execute_extension::att_xfer XML features"/>
..
</condition>
</extension>

The dx extension in features accepts the digits and proceeds as defined with the call

<extension name="dx">
<condition field="destination_number" expression="^dx$">
    <action application="answer"/>
    <action application="read" data="11 11 'tone_stream://%(10000,0,350,440)' digits 5000 #"/>
    <action application="execute_extension" data="is_transfer XML features"/>
</condition>
</extension>

Some authentication and security related dialplan applications :-

Checking user is authenticated before routing call , else respond 407

<extension name="9191">
<condition field="destination_number" expression="^9191$"/>
<condition field="${sip_authorized}" expression="true">
    <anti-action application="respond" data="407"/>
</condition>
<condition>
    <action application="playback" data="misc/connected_securly.wav"/>
</condition>
</extension>

Checking if there is TLS and SRTP security , else set not_secure

<extension name="is_secure">
<condition field="${sip_via_protocol}" expression="tls"/>
<condition field="${rtp_secure_media_confirmed}" expression="^true$">
<action application="sleep" data="1000"/>
<action application="playback" data="misc/connected_securly.wav"/>
<anti-action application="eval" data="not_secure"/>
</condition>
</extension>

Catching invalid destinations or extensions

Catch numbers which didnt match any other case. Add this extension to bottom. It plays an invalid tune

<extension name="catchall">
<condition field="destination_number" expression=".*" continue="true">
    <action application="playback" data="misc/invalid_extension.wav"/>
</condition>
</extension>

Call screening and blocking dialplan applications

Call Screening by name announcement

User caller’s name store in wave file

<action application="set" data="call_screen_filename=/tmp/${caller_id_number}-name.wav"/>

Connect to the called party. On answer announce the name. since playback_terminators is set to digits , pressing any one of them will terminate the call

<action application="set" data="hangup_after_bridge=true" />
<action application="answer"/>
<action application="sleep" data="1000"/>
<action application="phrase" data="voicemail_record_name"/>
<action application="playback" data="tone_stream://%(500, 0, 640)"/>
<action application="set" data="playback_terminators=#*0123456789"/>
<action application="record" data="${call_screen_filename} 7 200 2"/>

If called party presses 1 connect the call, or hang up.

<action application="set" data="group_confirm_key=1"/>
<action application="set" data="fail_on_single_reject=true"/>
<action application="set" data="group_confirm_file=phrase:screen_confirm:${call_screen_filename}"/>
<action application="set" data="continue_on_fail=true"/>
<action application="bridge" data="user/$1"/>

If the called party hangs up, the caller is connected with voicemail.

<action application="voicemail" data="default ${domain} $1"/>

finally hangup

<action application="hangup"/>

Block caller

Dial *77 followed by the number to be blocked

<extension name="block_caller_id">
<condition field="destination_number" expression="^\*77(\d+)$">
<action application="privacy" data="full"/>
<action application="set" data="sip_h_Privacy=id"/>
<action application="set" data="privacy=yes"/>
<action application="transfer" data="$1 XML default"/>
</condition>
</extension>

Block certain codes

block certain NPAs that you do not want to terminate based on caller id area codes and respond with SIP:503 to your origination so that they can route advance if they have other carrier to terminate to.

<extension name="blocked_cid_npa">
<condition field="caller_id_number" expression="^(\+1|1)?((876|809)\d{7})$">
<action application="respond" data="503"/>
<action application="hangup"/>
</condition>
</extension>

DID – Direct Inward Dialling via dialplan Public.xml

Assume we have a DID number 676767 which is served by telco provider either over SIP trunk/PRI lines . When someone from external world calls this number , FE needs to route the call to an internal user for example user at extension 3003 ( in default .xml context)

<include>
<extension name="public_did">
<condition field="destination_number" expression="^\+?1?(676767)$">
    <action application="set" data="domain_name=${domain}"/>
    <action application="transfer" data="3003 XML default"/>
</condition>
</extension>
</include>

If we are on multi domain setup , we need to setup the domain correctly .$${domain} is the default domain set from vars.xml but you can set it to any domain we have setup in user directory. Added the extra characters in from of DID number to adjust for various ISD code and number formats suffixes such as +1- ,91- , 0- etc .

IVR ( Interactive Voice Respondent ) using Menu

Main Menu – uses tts enginer and 3 attempsts to repond with timeout 10 seconds
On pressing 1 – bridge the call to conference , on press 2 – transfer to 2222 using default
On press of 3 – transfer using enum while on press 4 – play submenu. On press of 9 – goto top menu

<menu name="demo_ivr"
greet-long="say:Press 1 to join the conference, Press 2 to transfer , 3 to transfer , 4 to goto another menu "
greet-short="phrase:demo_ivr_main_menu_short"
invalid-sound="ivr/ivr-that_was_an_invalid_entry.wav"
exit-sound="voicemail/vm-goodbye.wav"
confirm-macro=""
confirm-key=""
tts-engine="flite"
tts-voice="rms"
confirm-attempts="3"
timeout="10000"
inter-digit-timeout="2000"
max-failures="3"
max-timeouts="3"
digit-len="4">
    <entry action="menu-exec-app" digits="1" param="bridge sofia/${domain}/888@conference.telcocompany.org"/>
    <entry action="menu-exec-app" digits="2" param="transfer 2222 XML default"/> 
    <entry action="menu-exec-app" digits="3" param="transfer 1234*256 enum"/> 
    <entry action="menu-sub" digits="4" param="demo_ivr_submenu"/> 
    <entry action="menu-exec-app" digits="/^(10[01][0-9])$/" param="transfer $1 XML features"/>
    <entry action="menu-top" digits="9"/> 
</menu>

Submenu – press * to repeat menu , # to exit . the timeout is 15 seconds

<menu name="demo_ivr_submenu"
greet-long="phrase:demo_ivr_sub_menu"
greet-short="phrase:demo_ivr_sub_menu_short"
invalid-sound="ivr/ivr-that_was_an_invalid_entry.wav"
exit-sound="voicemail/vm-goodbye.wav"
timeout="15000"
max-failures="3"
max-timeouts="3">
    <entry action="menu-top" digits="*"/>
    <entry action="menu-exit" digits="#"/>
</menu>

Find me Follow Me

If a users has lets say 3 phone – home , office and car then an incomming call should subesquently ring everywhere one by one till the user picks up the phone closet to him . leg_delay_start is the timer after which this endpoint will start riniging and leg_timeout is the duration till when this endpoint will ring.
Therfore as per below sample homephone will ring , after 5 sceonds office phone will ring and after 15 secons his cellphone 987654321 will ring . after 25 seconds call will end.

<action application="bridge" data="user/homephone0@mydomain.com, 
[leg_delay_start=5]user/officephone@mydomain.com, 
[leg_delay_start=15,leg_timeout=25] sofia/gateway/flowroute/987654321" />

DID can bridge to multiple extensions or gateways sequentially in a hunt pattern

<extension name="did_hunt">
<condition field="destination_number" expression="87654321">

<action application="set" data="hangup_after_bridge=true"/>
<action application="set" data="continue_on_fail=true"/>

<!-- this is needed to allow call_timeout to work after bridging to a gateway -->
<action application="set" data="ignore_early_media=true"/>

<!-- ring desk extension for 10 seconds. -->
<action application="set" data="call_timeout=10"/>
<action application="bridge" data="sofia/${domain}/1001"/>

<!-- Now try cell phone, hangup after 13 -->
<action application="set" data="call_timeout=13"/>
<action application="bridge" data="sofia/gateway/voicepulse/987654321" />

<!-- No answer, transfer to voicemail -->
<action application="answer"/>
<action application="sleep" data="1000"/>
<action application="voicemail" data="default ${domain} 1001"/>

</condition>
</extension>

Ring Multiple Targets

<action application="bridge" 
data="{ignore_early_media=true}user/7001@${domain}, 
user/7010@${domain}, user/7022@${domain}, user/7007@${domain}, 
sofia/gateway/flowroute/12345678901"/>

Handle Failures and Early Media

<action application="bridge" 
data="{ ignore_early_media=true, 
monitor_early_media_fail=user_busy:3:480+620!
destination_out_of_order:2:1776.7 }
sofia/internal/3000@local.telco.com|
sofia/internal/3004@local.telco.com"/>

To detect early media fail the conditions are
user busy – number of attempts is 3 and 480Hz 620Hz is the tone of frequency which is standard busy tone.
destination out of order – number of attempts 2 , 1776.7 Hz frequency .
Note that as per condition only these frequencies are detected for action , others are ignored .

Directory

A simple directory listing containing two groups with 2 users each

<domain name="${domain}">
<params>
<param name="dial-string" value="{^^:sip_invite_domain=${dialed_domain}:
presence_id=${dialed_user}@${dialed_domain}}${sofia_contact(*/${dialed_user}@${dialed_domain})}/>
</params>

<variables>
<variable name="record_stereo" value="true"/>
<variable name="default_gateway" value="${default_provider}"/>
<variable name="default_areacode" value="${default_areacode}"/>
<variable name="transfer_fallback_extension" value="operator"/>
</variables>

<groups>
<group name="default">
    <users>
        <X-PRE-PROCESS cmd="include" data="default/*.xml"/>
    </users>
</group>

<group name="team1">
    <users>
        <user id="1000" type="pointer"/>
        <user id="1001" type="pointer"/>
    </users>
</group>

<group name="team2">
    <users>
        <user id="1002" type="pointer"/>
        <user id="1003" type="pointer"/>
    </users>
</group>

</groups>
</domain>

1001 user’s xml

<include>
<user id="1001">
<params>
<param name="password" value="${default_password}"/>
</params>
<variables>
    <variable name="toll_allow" value="domestic,international,local"/>
    <variable name="accountcode" value="1001"/>
    <variable name="user_context" value="default"/>
    <variable name="effective_caller_id_name" value="Extension 1001"/>
    <variable name="effective_caller_id_number" value="1001"/>
    <variable name="outbound_caller_id_name" value="${outbound_caller_name}"/>
    <variable name="outbound_caller_id_number" value="${outbound_caller_id}"/>
    <variable name="callgroup" value="team1"/>
</variables>
</user>
</include>

Adding users

/usr/src/freeswitch-debs/freeswitch# scripts/perl/add_user 3000

perl: warning: Setting locale failed.
perl: warning: Please check that your locale settings:
 LANGUAGE = (unset),
 LC_ALL = (unset),
 LC_CTYPE = "UTF-8",
 LANG = "en_US.UTF-8"
    are supported and installed on your system.

perl: warning: Falling back to a fallback locale ("en_US.UTF-8").
Added 3000 in file /usr/local/freeswitch/conf/directory/default/3000.xml 
Operation complete. 1 user added.
Be sure to reloadxml.
Regular expression information:
            Sample regex for all new users: ^3000$
Sample regex for all new AND current users: ^(10(0[0-9]|1[0-9]|20)|3000)$

In the default configuration you can modify the expression in the condition for 'Local_Extension'.

Adding a range of users , 3000 to 3010

Since 3000 was already added previously , it threw a warning , rest were successfully added

root@ip-172-31-27-106:/usr/src/freeswitch-debs/freeswitch# scripts/perl/add_user -users=3000-3010 

perl: warning: Setting locale failed.
perl: warning: Please check that your locale settings:
 LANGUAGE = (unset),
 LC_ALL = (unset),
 LC_CTYPE = "UTF-8",
 LANG = "en_US.UTF-8"
    are supported and installed on your system.
perl: warning: Falling back to a fallback locale ("en_US.UTF-8").

User id 3000 already exists, skipping...
Added 3001 in file /usr/local/freeswitch/conf/directory/default/3001.xml 
Added 3002 in file /usr/local/freeswitch/conf/directory/default/3002.xml 
Added 3003 in file /usr/local/freeswitch/conf/directory/default/3003.xml 
Added 3004 in file /usr/local/freeswitch/conf/directory/default/3004.xml 
Added 3005 in file /usr/local/freeswitch/conf/directory/default/3005.xml 
Added 3006 in file /usr/local/freeswitch/conf/directory/default/3006.xml 
Added 3007 in file /usr/local/freeswitch/conf/directory/default/3007.xml 
Added 3008 in file /usr/local/freeswitch/conf/directory/default/3008.xml 
Added 3009 in file /usr/local/freeswitch/conf/directory/default/3009.xml 
Added 3010 in file /usr/local/freeswitch/conf/directory/default/3010.xml 
Operation complete. 10 users added.
Be sure to reloadxml.
Regular expression information:
            Sample regex for all new users: ^30(0[123456789]|10)$
Sample regex for all new AND current users: ^(10(0[0-9]|1[0-9]|20)|30(0[0-9]|10))$
In the default configuration you can modify the expression in the condition for 'Local_Extension'.

After adding the user to directory , users can now make outbound calls . But howver cannot be rechable for incoming calls . To enable that e need to add them to dialplan .

Creating dialplan for the newly added users  in conf/dialplan/default.xml

update the existing condition <condition field=destination_number expression=^(10[01][0-9])$> with <condition field=destination_number expression=^30(0[123456789]|10)$>

After this goto fs_cli cmd prompt and do reloadxml

Installation

Quick Installation on MacOS

Download and run the dmg , screenshots attached .

Building from source on Ubuntu 16.04 Xenial

*experimental not suitable for production as per Freeswitch docs

The master branch depends on video libraries which are not available as packages in Debian distribution, but are available from FreeSWITCH repository , requires the use of the devscripts and cowbuilder packages.apt-get install git devscripts cowbuilder

Change to root and add freeswitch to sources.list

wget -O - https://files.freeswitch.org/repo/deb/freeswitch-1.8/fsstretch-archive-keyring.asc | apt-key add -
 
echo "deb http://files.freeswitch.org/repo/deb/freeswitch-1.8/ jessie main" > /etc/apt/sources.list.d/freeswitch.list
echo "deb-src http://files.freeswitch.org/repo/deb/freeswitch-1.8/ jessie main" >> /etc/apt/sources.list.d/freeswitch.list
 
apt-get update

apt-get build-dep freeswitch

cd /usr/src/

git clone https://freeswitch.org/stash/scm/fs/freeswitch.git -bv1.8 freeswitch

cd freeswitch

git config pull.rebase true

Enter freeswitch directory and Build

./bootstrap.sh -j
./configure
make
make install

for errors such as “The repository ‘http://files.freeswitch.org/repo/ubuntu-1604/freeswitch-unstable xenial InRelease’ is not signed.” and “The following signatures couldn’t be verified because the public key is not available: NO_PUBKEY 0xxxxxxx” please note than only debian 8 is the officially supported os version by FS now. hence is using AWS ( amazon web service ) stick with ubuntu v 14 ie Ubuntu Server 14.04 LTS (HVM), SSD Volume Type  which is also free tier eligible.

  Ubuntu      |       Debian  
18.04  bionic     buster  / sid   - 10
17.10  artful     stretch / sid   - 9
17.04  zesty      stretch / sid
16.10  yakkety    stretch / sid
16.04  xenial     stretch / sid
15.10  wily       jessie  / sid   - 8
15.04  vivid      jessie  / sid
14.10  utopic     jessie  / sid
14.04  trusty     jessie  / sid
13.10  saucy      wheezy  / sid   - 7
13.04  raring     wheezy  / sid
12.10  quantal    wheezy  / sid
12.04  precise    wheezy  / sid
11.10  oneiric    wheezy  / sid
11.04  natty      squeeze / sid   - 6
10.10  maverick   squeeze / sid
10.04  lucid      squeeze / sid

Manual Process of bootstarp and cofigure

Once build is successfull , install libtool-bin , libcurl4-openssl-dev , libpcre3-dev , libspeex-dev , libspeexdsp-dev ,libtiff5 ,libtiff5-dev , yasm for libvpx , liblua5.1-0-dev for scripting

For mod_enum support install libldns-dev or disable it in modules.conf

we can either install libedit-dev (>= 2.11) or configure with –disable-core-libedit-support

./bootstrap.sh
./configure 
make

For errors around lua file such as Cannot find lua.h header file , just do apt-get install lua5.2 and lua5.2-dev and copy the headers file manually to freeswitch languages folder such as
cp -R /usr/include/lua5.2/ src/mod/languages/mod_lua/
or you can copy these one by one lauxlib.h lua.h lua.hpp luaconf.h lualib.h

ln -s /usr/lib/x86_64-linux-gnu/liblua5.1.so llua

sudo make install
sudo make uhd-sounds-install
sudo make uhd-moh-install
sudo make samples

If you want to make lua from source

mkdir -p ~/Developing/third_party
cd Developing
wget https://www.lua.org/ftp/lua-5.3.2.tar.gz
tar xf lua-5.3.2.tar.gz
cd lua-5.3.2.tar.gz
make linux 
sudo make install INSTALL_TOP=/usr/local
cd ~/Developing/third_party/rtags/build
cmake -DLUA_INCLUDE_DIR=/usr/local/include/ -DLUA_LIBRARY=/usr/local/lib/liblua.a ../
aptitude install -y -r -o APT::Install-Suggests=true freeswitch-meta-vanilla
cp -a /usr/share/freeswitch/conf/vanilla /etc/freeswitch
/etc/init.d/freeswitch start

To see if freeswitch is running  – ps aux | grep freeswitch

fs_cli
Screen Shot 2018-09-20 at 10.45.47 AM

To check listening ports – ngrep -W byline -d any port 5060 or netstat -lnp | grep 5060

HTTPTCP800.0.0.0/0
HTTPTCP80::/0
Custom TCP RuleTCP5080 – 50810.0.0.0/0
Custom TCP RuleTCP5080 – 5081::/0
Custom UDP RuleUDP16384 – 327680.0.0.0/0
Custom UDP RuleUDP16384 – 32768::/0
All trafficAllAll0.0.0.0/0
All trafficAllAll::/0
SSHTCP220.0.0.0/0
Custom TCP RuleTCP80210.0.0.0/0
Custom TCP RuleTCP8021::/0
Custom UDP RuleUDP5060 – 50620.0.0.0/0
Custom UDP RuleUDP5060 – 5062::/0
Custom UDP RuleUDP5080 – 50810.0.0.0/0
Custom UDP RuleUDP5080 – 5081::/0
HTTPSTCP4430.0.0.0/0
HTTPSTCP443::/0
Custom TCP RuleTCP8081 – 80820.0.0.0/0
Custom TCP RuleTCP8081 – 8082::/0
Custom TCP RuleTCP5060 – 50610.0.0.0/0
Custom TCP RuleTCP5060 – 5061::/0

Security

-tbd

  • ACL
  • Fail2Ban
  • IPtables

Debugging and Call

For internal calls , originate api can be used to initiate calls such as  originate ALEG BLEG

originate {origination_caller_id_number=9999988888}sofia/internal/1004@127.0.0.1:5060 91999998888 XML default CALLER_ID_NAME CALLER_ID_NUMBER

This will make a call out to sip:1004@1127.0.0.1 with the Caller ID number set to 999998888, then it will send the call to the XML dialplan using context=default. Then the dialplan will process call to 91999998888 with the Caller ID name and number specified in the fields CALLER_ID_NAME and CALLER_ID_NUMBER.

fsc_cli> originate sofia/internal/1002@127.0.0.1:5060 &echo()
switch_ivr_originate.c:2159 Parsing global variables
switch_channel.c:1104 New Channel sofia/internal/1002@127.0.0.1:5060 [5188806e-cabd-4acc-b20b-00620c3362ec]
mod_sofia.c:5026 (sofia/internal/1002@127.0.0.1:5060) State Change CS_NEW -> CS_INIT
switch_core_state_machine.c:584 (sofia/internal/1002@127.0.0.1:5060) Running State Change CS_INIT (Cur 5 Tot 122559)
switch_core_state_machine.c:627 (sofia/internal/1002@127.0.0.1:5060) State INIT
mod_sofia.c:93 sofia/internal/1002@127.0.0.1:5060 SOFIA INIT
sofia_glue.c:1299 sofia/internal/1002@127.0.0.1:5060 sending invite version: 1.9.0 -654-ed4920e 64bit
Local SDP:
v=0
o=FreeSWITCH 1538689496 1538689497 IN IP4 172.31.27.106
s=FreeSWITCH
c=IN IP4 172.31.27.106
t=0 0
m=audio 24636 RTP/AVP 9 0 8 101
a=rtpmap:9 G722/8000
a=rtpmap:0 PCMU/8000
a=rtpmap:8 PCMA/8000
a=rtpmap:101 telephone-event/8000
a=fmtp:101 0-16
a=ptime:20
a=sendrecv
m=video 19042 RTP/AVP 102
b=AS:1024
a=rtpmap:102 VP8/90000
a=sendrecv
a=rtcp-fb:102 ccm fir
a=rtcp-fb:102 ccm tmmbr
a=rtcp-fb:102 nack
a=rtcp-fb:102 nack pli
switch_core_state_machine.c:40 sofia/internal/1002@127.0.0.1:5060 Standard INIT
switch_core_state_machine.c:48 (sofia/internal/1002@127.0.0.1:5060) State Change CS_INIT -> CS_ROUTING
switch_core_state_machine.c:627 (sofia/internal/1002@127.0.0.1:5060) State INIT going to sleep
switch_core_state_machine.c:584 (sofia/internal/1002@127.0.0.1:5060) Running State Change CS_ROUTING (Cur 4 Tot 122612)
sofia.c:7291 Channel sofia/internal/1002@127.0.0.1:5060 entering state [calling][0]
sofia.c:7291 Channel sofia/internal/1002@127.0.0.1:5060 entering state [terminated][503]

Ref :
https://freeswitch.org/confluence/display/FREESWITCH/Ubuntu+16.04+Xenial
https://freeswitch.org/confluence/display/FREESWITCH/Ubuntu+Quick+Start

My freeswitch contributor profile  https://freeswitch.org/confluence/users/viewuserprofile.action?username=altanai

Freeswitch Wiki

Freeswitch bitbucket Codebase 

Features set JAINSLEE vs SIP/J2EE

Feature Set JAINSLEE vs SIP/J2EE
Portability Portability of JAINSLEE is limited to number of available applications servers on the market.
Complexity 1) SIP Servlet components handle directly SIP signaling, there is no abstraction layer so there is no loss in network features. 2) If a comparison between SIP Servlets and JAIN SLEE is made it can be said that JAIN SLEE is a more complex specification than SIP Servlets and it seems that JAIN SLEE has not gained much support in the SDP industry which has been dominated by servers running J2EE.
Protocol Agnosticism Lagre number of protocols are supported in JAINSLEE using resource adapters.
Failure Handling JAINSLEE uses ACID (Atomicity,Consistency, Isolation, and Durability) properties of transactions and features of the SLEE programming model for failure handling.
Network Abstraction Capability JAINSLEE define a high level API that developers must use to access network resources.
Expandibility Expandability means whether the technology supports the addition of new protocol stack into the SDP.For that purpose the technology must provide a sort of plug-in architecture.
Flexibility Flexibility is high or low depending on the level of abstraction of network protocols.

SIP Servlets – Develop and Deploy

With this article I will outlines the SIP servlet creation and various call routing logic development.

A simple proxy SIP ser vlet application also has 4 parts

Extension SIP servlet Classand global var declaration

public class VoiceCall extends SipServlet{
	public ServletContext context;
	SipApplicationSession sas;
	public SipFactory factory;
	SipServletRequest incoming;
  	public static final Log log = LogFactory.getLog(VoiceCall.class);

2. Init

public void init(ServletConfig config) {
 	try{
	log.info("Init.");
	super.init(config);

	factory = (SipFactory) getServletContext().getAttribute(
			SipServlet.SIP_FACTORY);
	sas=factory.createApplicationSession();
	context=config.getServletContext();
	context.setAttribute("servlet",this);
	//registerWithBroker();
 	}
 	catch(Exception e){
 		log.info("VoiceCall:27 "+e.toString());
 	}
}

3. doRequest

public void doRequest(SipServletRequest req){
	try{
		if(req.getMethod().equals("INVITE") && req.isInitial()){
		SipServletRequest req2=factory.createRequest(sas,"MESSAGE","sip:ser@100.1.1.15:5061","sip:100.1.1.15:2519");
		req2.setHeader("Type","Query");
		req2.send();
		incoming=req;
	}
	else{
		((CallLeg)req.getSession().getAttribute("CALL_LEG")).transferReq(req);
	}
	}
	catch(Exception e){
		log.info("VoiceCall:39 "+e.toString());
	}
}

4. doResponse

public void doResponse(SipServletResponse res){
	try{
	if(res.getRequest().getMethod().equals("MESSAGE") && res.getContent().equals("OK")){			
	System.out.println("Message Reply Recieved "+ res.getContent());
	SipServletRequest req=factory.createRequest(sas,"INVITE","sip:ser@100.1.1.15:5061","sip:1@100.1.1.15:5070");
	CallLeg leg1=new CallLeg(incoming, factory, log);
	CallLeg leg2=new CallLeg(req, factory, log);
	leg1.state="Invited";
	leg1.otherLeg=leg2;
	leg2.otherLeg=leg1;
	leg2.startCall();
	}
	else
	((CallLeg)res.getSession().getAttribute("CALL_LEG")).transferRes(res);
	}
	catch(Exception e){
		log.info("VoiceCall:44 "+e.toString());
	}
}

Githuhb Repo for Source Code of given applications : https://github.com/altanai/sip-servlets

SIP protocol based Surveillance

Stream media from Surveillance camera into mobile by just calling a particular number. The camera also records movements and send a message to user on suspicious activity . This is a user triggered application for security purpose. If an IP camera is installed in secure zone. The user can run the surveillance application on his smart phone. As IP camera detects any motion, immediately this application sends a SMS and a mail having snapshots of scene before and after the suspected motion. The user can directly go to the URL’s obtained from mail and see the suspected event. In addition to this at any point of time he wants to see the captured media feed from the camera he just needs to give a call to the camera .

SIP Trunking

The SIP Trunking can be implemented to deliver a SIP Trunk connection with  any number of IP-based voice “circuits” to each customer site and enabling the multiple SIP Trunks from different sites that can be grouped together so that different premises for a customer can be linked and interconnected.  It includes the functionality of Call control and number translation

Voice Call continuity

In this use case call is established between two users Bob and Alice using PC, if Bob wants to resume call from his mobile, he needs to run the VCC application on his mobile. Bob resumes the call to Alice through his mobile. The former connection is between PC to PC, Later the connection transfers between PC and mobile

Enhanced Call Screening

The use case implements the screening of many SIP users and the user can enable the feature of Do not Disturb for any particular date, time of the day or day of the week. Also every call made or screened is recorded with timestamp

protected void doInvite(SipServletRequest req) throws java.lang.IllegalArgumentException,java.lang.IllegalStateException,javax.servlet.ServletException,java.io.IOException
{
	String scuser=(String)context.getAttribute("ScreenedUser");
	System.out.println("Screened User:"+scuser);
	SipURI from=((SipURI)req.getFrom().getURI());
	if(from.getUser().equals(scuser))
	{
		req.createResponse(487).send();
		System.out.println("User is blocked");
	}
	else
	{
		Proxy px=req.getProxy(true);
		URI sburi=factory.createURI("sip:<x.x.x.x>:5090");
		px.proxyTo(sburi);
		System.out.println("User is not blocked");
	}
}

Basic Calls creening source code – https://github.com/altanai/sip-servlets/tree/master/CallScreening

Auto Attendant

The use case implements the screening of many SIP users and the user can enable the feature of Do not Disturb for any particular date, time of the day or day of the week. Also every call made or screened is recorded with timestamp

Click To Dial

A supervisor can enable the call between any two registered SIP clients via a web based interface.

Develop JSR 116 – SIP Servlet 1.0 API applications

Moe about JSR 116 – SIP SERVLET 1.0 here

SIP Servlet 1.0 API

  • Built into the Servlet container that also hosts portlets and HTTP Servlets.
  • SIP Servlet API developed under the JCP (Java Community Process) as JSR 116 (Java Specification Request), as a set of neutral interfaces

Servlet Container

  • Environment in which a servlet can exist
  • Loads and initializes a servlet
  • Invokes the appropriate methods when SIP messages arrive

Servlets

  • Class with a service method, compiled into a Servlet Archive File (SAR)

Deployment descriptors

  • XML based file with configuration information
  • message matching rules

Screens

Screenshot making a sip servlet . The project is a SAR file

4
3
2
1

Logical Entity diagram for JSR116 , sip servlet version 1.0

jsr116

SIP Response methods and flows

SIP messages life-cycle process , ie init() , service() , destroy()

Bea Weblogic 

J2EE application server and also an HTTP web server by BEA Systems for Unix, Linux, Microsoft Windows, and other platforms,

Supports Oracle, DB2, Microsoft SQL Server, and other JDBC-compliant databases

WebLogic Server supports WS-Security and is compliant with J2EE 1.4

The most reliable server is no doubt BEA’s WebLogic Application Server. It is the only one which can resist to over 3000 concurrent clients without throwing exceptions.

The WebLogic Server is the most reliable server and complex application server and offers the best support for the real-world applications.

•Although it needs a higher level of understanding of the J2EE concepts, has a complex configuration and is very expensive, this server is the best choice for a secure and fault-tolerant application.

weblogic

BEA WebLogic Server is part of the BEA WebLogic Platform™.

The other parts of WebLogic Platform are :

a) Portal, which includes Commerce Server and Personalization Server   (which is built on a BEA-produced Rete rules engine),

b) WebLogic Integration,

c) WebLogic Workshop, an IDE for Java, and d) JRockit, a JVM for Intel CPUs

Brekeke SIP Server – SIP Proxy, Registrar Server

  • Based on the Session Initiation Protocol (SIP), the Brekeke SIP Server provides reliable and scalable SIP communication platform for Enterprises and Service Providers.
  • Brekeke SIP Server provides functionality of SIP Registrar Server, SIP Redirect Server, and SIP Proxy Server.
  • Brekeke SIP Server is a Stateful Proxy that maintain session status therefore performs optimum processing for call control
brekeke

SOFTPHONES  –  X-LITE AND KAPANGA

xlite
kapanga

A soft phone is a software program for making telephone calls over the Internet using a general purpose computer, rather than using dedicated hardware. Often a soft phone is designed to behave like a traditional telephone, sometimes appearing as an image of a phone, with a display panel and buttons with which the user can interact.

To communicate, both end-points must have the same communication protocol and at least one common audio codec. Many service providers use the Session Initiation Protocol (SIP) standardized by the Internet Engineering Task Force (IETF).

X-Lite is a proprietary freeware VoIP soft phone that uses the Session Initiation Protocol.

Kapanga is a Session Initiation Protocol (SIP) software phone capable of voice, fax, and video over IP communications. As a SIP phone, Kapanga can be used on Voice over IP networks to interact with traditional Public Switching Telecommunication Networks (PSTNs) and future IP-based telecommunication devices. This document explains how to use Brekeke SIP Server with the Kapanga Soft Phone.

SIP Application Development Essentials
SIP Application Development Essentials

Figure depicts a typical setup required for any telecom software developer

Orchestration of IN/IMS services

Open Cloud Service broker orchestrates services, by managing the interactions between the services in a centralized middleware layer. The Open Cloud Service Interaction SLEE (SIS) provides service brokering and service interaction functionality for SS7 and IMS networks. We can orchestrate two services such as Call Screening and find-me follow me (fmfm). The usecase is that when the caller calls callee it will be checked if the callee has screened the caller or not, in case the caller is not screened the second service fmfm will be invoked. If the callee has registered from multiple devices, till the call is not picked all the numbers will be tried

Credit Transfer

The Credit Transfer service enables subscribers to transfer credit from their post-paid or pre-paid account to another subscriber’s pre-paid account. For example, a parent can quickly top-up their child’s balance. The donating subscriber can transfer credit using SMS or a USSD menu, or can call an IVR service. When credit has been transferred both the donating subscriber and the credited subscriber receive an SMS detailing the credit transferred.

Call Request

Enables a pre-paid subscriber with low credit to request a contact to call them. The subscriber uses USSD menus or calls a service number and provides the number of their contact. Additionally, the service may also be automatically offered to subscribers attempting to call with insufficient credit.

The service can either simply send a text message to the contact requesting them to call back, or the service may out-dial and interact with the “called” party, asking them to accept the call charges before setting up the call. The service can be configured for use only by pre-paid customers with a balance below a specified threshold, and may be restricted to send call requests only to on-net destinations.

Toll Free Phone Number

The Free-phone Number application enables enterprise subscribers to provide a free-phone number for their business, so their customers can call them for free from land lines and reduced cost from mobile (depending on local practices).
Calls made to the free-phone number are diverted to the enterprise subscriber’s regular number (or any other number they specify). The enterprise pays for the originating and terminating call charges.

Cloud-based PBX

This service, hosted by the network operator, provides enterprises with PBX functionality without needing equipment to be installed on their premises, with opportunities to buy as a monthly subscription rather than as a capital investment.
PBX functions may include: Call forwarding, call transfer, call pick-up, call hold, call screening, hunt groups, call distribution and call queuing, etc.

Code for SIP servlets  : https://github.com/altanai/sip-servlets

Code for JAINSLEE Applications :  https://github.com/altanai/Jaisnlee

Code for SIP WebRTC : https://github.com/altanai/webrtcmetro