Routing guide

Version 46 (Adrian Georgescu, 10/24/2019 01:56 pm)

1 5 Tijmen de Mes
h1. Routing Guide
2 5 Tijmen de Mes
3 20 Adrian Georgescu
MSP and SIP Thor platforms are based on a SIP Proxy/Registrar/Presence Agent design. Each SIP server node maintains transaction and dialog state for each session and is able to terminate each of them based on various criteria. The platform handles and controls the RTP and MSRP media planes and is able to take decisions related to authorization, authentication, accounting, NAT traversal and session termination based on the media flow behavior. The design eliminates the need of separate session border controller elements which just add costs, hurt scalability and add no end-user features.  
4 1 Tijmen de Mes
5 12 Adrian Georgescu
The platform has rich telephony functions equivalent with traditional Class 4 switches (routing inter-carrier calls) and Class 5 switches (routing last-mile calls to end-users).
6 1 Tijmen de Mes
7 12 Adrian Georgescu
The platform can be equally used to perform SIP services that include and are not limited to Residential VoIP, Prepaid Cards, Video Calling, Presence and IM, Trunking, Least Cost Routing and ENUM Peering.
8 1 Tijmen de Mes
9 4 Tijmen de Mes
h2. Logical Architecture
10 2 Tijmen de Mes
11 6 Tijmen de Mes
!msp-interconnect.png!
12 2 Tijmen de Mes
13 42 Adrian Georgescu
h2. IP addressing
14 42 Adrian Georgescu
15 43 Adrian Georgescu
The platform is designed to operate using IPv4 addresses using public IP space, this topology allows end-points to operate behind any type of NAT router. The end-points can use both private or private IPv4 addresses.
16 42 Adrian Georgescu
17 42 Adrian Georgescu
18 1 Tijmen de Mes
h2. SIP Entities
19 1 Tijmen de Mes
20 2 Tijmen de Mes
This document describes routing logic between several SIP entities defined as follows:
21 2 Tijmen de Mes
22 4 Tijmen de Mes
# SIP Proxy: the platform core that performs the logic described in this document
23 4 Tijmen de Mes
# End-Point: a SIP end-user device that is configured with the credentials of a SIP account for which the platform is responsable
24 4 Tijmen de Mes
# PBX: a SIP end-point or intermediary that is configured under a foreign SIP domain not handled by the platform
25 4 Tijmen de Mes
# PSTN gateway: a SIP end-point or intermediary that is handling the translation between IP (using SIP protocol) and PSTN networks
26 1 Tijmen de Mes
27 4 Tijmen de Mes
h2. Supported Signaling
28 3 Tijmen de Mes
29 20 Adrian Georgescu
The platform supports SIP protocol over UDP/TCP/TLS transports. Additional, a gateway to and from XMPP remote domains can be configured. 
30 2 Tijmen de Mes
31 3 Tijmen de Mes
h2. Supported Media
32 2 Tijmen de Mes
33 2 Tijmen de Mes
The platform supports sessions containing the following media types:
34 1 Tijmen de Mes
35 4 Tijmen de Mes
* Audio (RTP and sRTP)
36 4 Tijmen de Mes
* Video (RTP and sRTP)
37 4 Tijmen de Mes
* FAX (RTP and T.38)
38 4 Tijmen de Mes
* Instant messaging (MSRP and its relay extension)
39 4 Tijmen de Mes
* File transfer (MSRP and its relay extension)
40 4 Tijmen de Mes
* Page mode messaging (SIP MESSAGE method)
41 44 Adrian Georgescu
* Presence (RLS Subscriptions and Presence Agent)
42 44 Adrian Georgescu
* XCAP contact lists (the OMA variant)
43 2 Tijmen de Mes
44 4 Tijmen de Mes
The platform is codec agnostic, the negotiation of the codecs depends entirely on the end-points. The MediaProxy component that relays the RTP media between the end-points, for NAT traversal and accounting purposes, relays all packets at IP layer 3 (UDP protocol that encapsulates the RTP/RTCP streams). The actual payload with the particular codecs used inside the RTP streams is transparently passed between end-points without interference from MediaProxy.
45 2 Tijmen de Mes
46 1 Tijmen de Mes
Other payloads are supported as long as they are embedded into a supported stream, for example any payload that is embedded within the RTP streams (zRTP, DTMF tones) or MSRP streams (file transfer, multy-party chat service, desktop sharing).
47 1 Tijmen de Mes
48 2 Tijmen de Mes
h2. Primitives
49 2 Tijmen de Mes
50 3 Tijmen de Mes
The routing of SIP sessions is governed by two main protocols:
51 2 Tijmen de Mes
52 4 Tijmen de Mes
# Domain based SIP routing based on RFC3261 and RFC3263
53 4 Tijmen de Mes
# ENUM lookups based on RFC3761
54 2 Tijmen de Mes
55 2 Tijmen de Mes
The routing logic of the platform can be configured by changing its database tables and configuration files. The primitives used for routing are:
56 2 Tijmen de Mes
57 2 Tijmen de Mes
58 4 Tijmen de Mes
|Registrar database|Used to translate a SIP address into a SIP contact address|
59 4 Tijmen de Mes
|ENUM|Used to translate an E.164 telephone number into a SIP address|
60 4 Tijmen de Mes
|SIP alias|Used for adding aliases to existing SIP accounts|
61 4 Tijmen de Mes
|Emergency numbers|Translation between 911 and 112 into closest emergency access points|
62 4 Tijmen de Mes
|Call diversion|Translate a SIP address into another based on signaling conditions or end-user preferences|
63 1 Tijmen de Mes
|DNS lookups|Translate a SIP domain/hostname into an protocol:IP:port combination|
64 22 Adrian Georgescu
|LCR|Used for selection of outgoing PSTN gateway|
65 2 Tijmen de Mes
66 2 Tijmen de Mes
67 4 Tijmen de Mes
h2. Server Location
68 1 Tijmen de Mes
69 4 Tijmen de Mes
To locate the SIP Proxy/Registrar for a domain, SIP endpoints must perform DNS lookups based on RFC3263 that return the IP:port combination for which the server is configured.
70 1 Tijmen de Mes
71 4 Tijmen de Mes
h2. Configuration Files
72 1 Tijmen de Mes
73 4 Tijmen de Mes
Index of SIP Proxy configuration files located in/etc/opensips/:
74 2 Tijmen de Mes
75 4 Tijmen de Mes
76 4 Tijmen de Mes
|config/settings.m4|Contains the settings that can customize the routing logic|
77 4 Tijmen de Mes
|config/opensips.m4|Contains the proxy routing logic (should not be modified)|
78 4 Tijmen de Mes
|config/siteconfig/handle-incoming-pstn.m4|Used to customize routing logic for incoming PSTN calls|
79 4 Tijmen de Mes
|config/siteconfig/handle-local-extensions.m4|Used to define installation specific custom local extensions|
80 4 Tijmen de Mes
|config/siteconfig/handle-outgoing-peers.m4|Used to customize routing for outgoing calls to non-local domains|
81 4 Tijmen de Mes
|config/siteconfig/postprocess-request.m4|Used to customize outgoing requests before they leave the proxy|
82 4 Tijmen de Mes
|config/siteconfig/preprocess-pstn.m4|Used to customize outgoing PSTN requests before applying LCR routing|
83 4 Tijmen de Mes
|config/siteconfig/preprocess-request.m4|Used to apply custom pre-processing to a request before anything else|
84 4 Tijmen de Mes
|config/siteconfig/preprocess-uri.m4|Used to apply custom pre-processing to the request URI before converting to E164|
85 4 Tijmen de Mes
86 4 Tijmen de Mes
87 4 Tijmen de Mes
The settings.m4 file is used to customize the existing routing logic defined in opensips.m4 using the predefined routing options. 
88 4 Tijmen de Mes
 The files under the siteconfig/ directory can contain installation specific routing logic, which will be included by opensips.m4 and will allow for the routing logic to be adapted to the specific requirements of a given installation. The opensips.m4 file will always be overwritten on upgrades, so it should never be modified, while the files under the siteconfig/ directory will never be overwritten and can be modified without restrictions.
89 4 Tijmen de Mes
90 2 Tijmen de Mes
h2. NAT Traversal
91 1 Tijmen de Mes
92 4 Tijmen de Mes
NAT traversal methods encountered in the field and their properties:
93 1 Tijmen de Mes
94 4 Tijmen de Mes
* SIP server based (Relay) - reliable server side technology that works with all SIP clients, this method is used by the platform
95 4 Tijmen de Mes
* SIP client based (ICE) - client and server technology where client may negotiate media paths, is supported by the platform
96 4 Tijmen de Mes
* Intermediates based:
97 4 Tijmen de Mes
** NAT routers with SIP Application Level Gateway (SIP ALG) - located in customer premises network and the most *unreliable* technique
98 4 Tijmen de Mes
** Sessions Border Controllers (SBC) - located in service provider network - reliable with high cost and high complexity
99 1 Tijmen de Mes
100 4 Tijmen de Mes
The most reliable way to solve NAT issues with SIP is server based, by relaying packets using servers visible by both end-points. A new methodology under development is ICE, which relies partially on the SIP clients. NAT traversal applied in intermediates only introduce problems and SBCs add costs without adding value to the SIP service.
101 2 Tijmen de Mes
102 2 Tijmen de Mes
Below is a display of all possible NAT traversal techinques used for SIP and related media.
103 2 Tijmen de Mes
104 6 Tijmen de Mes
!nat-traversal-techniques.png!
105 1 Tijmen de Mes
106 4 Tijmen de Mes
The platform handles the NAT traversal for all its end-points by relaying all traffic, signaling and media through its servers that have public IP address and are visible for both end-points involved in a call flow.
107 2 Tijmen de Mes
108 4 Tijmen de Mes
Optional, "ICE can be deployed":http://mediaproxy-ng.org/wiki/ICE when supported by the end-points. The media relay acts like a TURN candidate and the operator may choose on a per call basis when and how this relay is to be used. When using ICE, SIP sessions that do not have a BYE cannot be accounted for.
109 2 Tijmen de Mes
110 4 Tijmen de Mes
NAT traversal is not the same thing as Firewall traversal. A firewall has an administrative policy, which must be set to support SIP and associated media traffic.
111 2 Tijmen de Mes
112 1 Tijmen de Mes
h3. Platform Ports
113 1 Tijmen de Mes
114 4 Tijmen de Mes
See the Firewall Setup section for a list of ports used by the platform software.
115 1 Tijmen de Mes
116 4 Tijmen de Mes
bq. Make sure that NAT traversal functions related to SIP known as SIP ALG functionality in the NAT routers are disabled.
117 1 Tijmen de Mes
118 4 Tijmen de Mes
119 4 Tijmen de Mes
120 1 Tijmen de Mes
h2. AAA
121 1 Tijmen de Mes
122 1 Tijmen de Mes
Authentication, Authorization and Accounting are performed depending on particular call flows as follows:
123 1 Tijmen de Mes
124 4 Tijmen de Mes
h3. Authentication
125 1 Tijmen de Mes
126 4 Tijmen de Mes
The trust relationship between SIP subscribers and SIP Proxy is based on DIGEST algorithm, both have a database with shared credentials.
127 1 Tijmen de Mes
128 4 Tijmen de Mes
h4. Sessions
129 4 Tijmen de Mes
130 1 Tijmen de Mes
Authentication for INVITE requests based on two methods:
131 2 Tijmen de Mes
132 4 Tijmen de Mes
# *SIP credentials*, when the From header contains a domain served by the platform. The From header presented by the device must match the credentials used for authentication.
133 4 Tijmen de Mes
# *Trusted peer* identified by IP address, used when the From header contains a remote domain and the request URI is not a local SIP address.
134 1 Tijmen de Mes
135 4 Tijmen de Mes
By default, incoming SIP sessions from remote domains to local SIP accounts served by the platform are not authenticated and always authorized.
136 1 Tijmen de Mes
137 1 Tijmen de Mes
For Instant Messaging and File transfers, MSRP relay reservations are authenticated using the same credentials for each SIP account.
138 1 Tijmen de Mes
139 4 Tijmen de Mes
h4. Register
140 1 Tijmen de Mes
141 1 Tijmen de Mes
Authentication for REGISTER methods is based on SIP credentials, this method can be used only by local SIP accounts and will not be relayed outside the platform. The From header presented by the SIP device must match the credentials used for authentication.
142 2 Tijmen de Mes
143 2 Tijmen de Mes
h4. Presence
144 1 Tijmen de Mes
145 1 Tijmen de Mes
The platform provides a Presence Agent that handles PUBLISH, SUBSCRIBE and NOTIFY methods based on SIP SIMPLE standards. The following event packages are supported:
146 1 Tijmen de Mes
147 4 Tijmen de Mes
* presence
148 4 Tijmen de Mes
* presence.winfo
149 19 Adrian Georgescu
* xcap-diff
150 1 Tijmen de Mes
151 4 Tijmen de Mes
Authentication for PUBLISH is based on SIP credentials, this methods can be used only by local SIP accounts and will not be relayed outside the platform. The From header presented by the SIP device must match the credentials used for authentication. Authentication for SUBSCRIBE requests are based on SIP credentials, when the From header contains a domain served by the SIP Proxy.
152 1 Tijmen de Mes
153 4 Tijmen de Mes
SUBSCRIBE requests from remote domains are allowed without authentication when the request URI is a local SIP address served by the platform.
154 1 Tijmen de Mes
155 1 Tijmen de Mes
SUBSCRIBE for the events message-summary and presence.winfo are allowed only for local users.
156 1 Tijmen de Mes
157 2 Tijmen de Mes
XCAP requests are authenticated using the same credentials for each SIP account.
158 1 Tijmen de Mes
159 1 Tijmen de Mes
The following XCAP documents are supported:
160 1 Tijmen de Mes
161 13 Adrian Georgescu
http://www.openxcap.org/projects/openxcap/wiki/Features
162 2 Tijmen de Mes
163 4 Tijmen de Mes
h3. Authorization
164 1 Tijmen de Mes
165 4 Tijmen de Mes
h4. Sessions
166 2 Tijmen de Mes
167 2 Tijmen de Mes
Authorization for outgoing SIP sessions can be performed for local SIP accounts based on:
168 1 Tijmen de Mes
169 4 Tijmen de Mes
# Access to PSTN
170 4 Tijmen de Mes
# Administrative blocking
171 4 Tijmen de Mes
# Monthly quota usage
172 4 Tijmen de Mes
# Prepaid balance
173 14 Adrian Georgescu
# Concurrent number of calls
174 4 Tijmen de Mes
# Call barring (user driven)
175 4 Tijmen de Mes
# Custom SIP Proxy logic
176 1 Tijmen de Mes
177 2 Tijmen de Mes
Authorization for incoming SIP sessions can be performed for local SIP accounts based on:
178 2 Tijmen de Mes
179 14 Adrian Georgescu
# Source IP address
180 4 Tijmen de Mes
# Administrative blocking
181 4 Tijmen de Mes
# Accept based on caller
182 4 Tijmen de Mes
# Accept based on time of day
183 4 Tijmen de Mes
# Reject based on caller id
184 4 Tijmen de Mes
# Custom SIP Proxy logic
185 1 Tijmen de Mes
186 1 Tijmen de Mes
Automatic session cut-off
187 1 Tijmen de Mes
188 1 Tijmen de Mes
SIP sessions can be terminated forcefully by the platform based on the following conditions:
189 1 Tijmen de Mes
190 4 Tijmen de Mes
# Prepaid balance exceeded (in real time)
191 4 Tijmen de Mes
# Monthly quota exceeded (on the next call)
192 4 Tijmen de Mes
# Maximum call duration exceeded
193 4 Tijmen de Mes
# RTP media timeout
194 14 Adrian Georgescu
# Signaling path lost
195 14 Adrian Georgescu
196 1 Tijmen de Mes
197 4 Tijmen de Mes
h4. Presence
198 1 Tijmen de Mes
199 2 Tijmen de Mes
Authorization for SUBSCRIBE for the presence event can be performed for local SIP accounts based on:
200 2 Tijmen de Mes
201 4 Tijmen de Mes
# XCAP pres-rules document
202 4 Tijmen de Mes
# Trusted peers
203 2 Tijmen de Mes
204 2 Tijmen de Mes
205 2 Tijmen de Mes
206 4 Tijmen de Mes
h3. Accounting
207 2 Tijmen de Mes
208 4 Tijmen de Mes
All SIP and RTP sessions are accounted by using RADIUS requests. See "accounting guide for more information":/wiki/AccountingGuide.
209 1 Tijmen de Mes
210 4 Tijmen de Mes
h2. End-Point to End-Point
211 1 Tijmen de Mes
212 7 Tijmen de Mes
!flow-sip-phone-a-b.png!
213 4 Tijmen de Mes
214 4 Tijmen de Mes
215 4 Tijmen de Mes
|Authentication|SIP account A|
216 4 Tijmen de Mes
|Authorization|SIP account A|
217 4 Tijmen de Mes
|Billing party|SIP account A|
218 4 Tijmen de Mes
|Accounting|Postpaid, Prepaid|
219 4 Tijmen de Mes
|Media types|RTP (audio and video), Presence, MSRP (Instant messaging and file transfers)|
220 4 Tijmen de Mes
|Address resolution|SIP address, SIP alias, Quickdial, ENUM|
221 4 Tijmen de Mes
|From header|Must contain a local SIP domain|
222 30 Adrian Georgescu
|Fraud Control | PIKE, ACL, Call control | 
223 4 Tijmen de Mes
224 4 Tijmen de Mes
h3. Quick Dial
225 4 Tijmen de Mes
226 1 Tijmen de Mes
Quick dial is a per SIP account feature that allows to dial short numbers to match other SIP accounts in the same number range. The SIP Proxy will try to autocomplete the number to form a full address. To use this feature:
227 1 Tijmen de Mes
228 4 Tijmen de Mes
# The username part of the SIP account must be numeric (example "31208005169@ag-projects.com":mailto:31208005169@ag-projects.com)
229 4 Tijmen de Mes
# The *quickdial* attribute of the SIP account must be set to a substring matching the beginning of the username (e.g. 312080051).
230 4 Tijmen de Mes
# When user dials 60 the example above, the SIP Proxy will concatenate the quickdial set to 312080051 with the dialed number 60 and try "31208005160@ag-projects.com":mailto:31208005160@ag-projects.com as destination.
231 1 Tijmen de Mes
232 4 Tijmen de Mes
h2. End-Point to PBX
233 1 Tijmen de Mes
234 7 Tijmen de Mes
!flow-sip-phone-a-pbx-b.png!
235 1 Tijmen de Mes
236 1 Tijmen de Mes
237 4 Tijmen de Mes
|Authentication|SIP account A|
238 4 Tijmen de Mes
|Authorization|SIP account A|
239 4 Tijmen de Mes
|Caller Id|Asserted by the platform|
240 4 Tijmen de Mes
|Billing party|SIP account A|
241 4 Tijmen de Mes
|Accounting|Postpaid, Prepaid|
242 4 Tijmen de Mes
|Media types|RTP (audio)|
243 4 Tijmen de Mes
|Address resolution|ENUM|
244 4 Tijmen de Mes
|From header|Must contain a local SIP domain|
245 30 Adrian Georgescu
|Fraud Control | PIKE, ACL, Call control | 
246 1 Tijmen de Mes
247 4 Tijmen de Mes
h2. PBX to PBX
248 4 Tijmen de Mes
249 7 Tijmen de Mes
!flow-pbx-a-pbx-b.png!
250 4 Tijmen de Mes
251 1 Tijmen de Mes
The PBX has its own accounts and connected devices. Requests originating from a PBX cannot be therefore authorized based on username/password combinations as they are not provisioned in the platform subscriber database, they are locally managed by the PBX owner. The traffic generated by the PBX can be only identified by its source IP address(es). To allow traffic from a PBX, the platform uses the concept of trusted peers. A trusted peer is an IP address that is allowed to route SIP calls through the platform without digest authorization. Beware that, no checks are done by the proxy related to the incoming caller identity, as long as the SIP sessions originate from the trusted IP address. Once you trust an IP address, you trust all traffic generated by it.
252 1 Tijmen de Mes
253 1 Tijmen de Mes
254 4 Tijmen de Mes
|Authentication|None|
255 4 Tijmen de Mes
|Authorization|Trusted peer A|
256 4 Tijmen de Mes
|Caller Id|Supplied by trusted peer A|
257 4 Tijmen de Mes
|Billing party|Trusted peer A|
258 4 Tijmen de Mes
|Accounting|Postpaid|
259 36 Adrian Georgescu
|Media types|RTP (audio, video), T.38 Fax, SIP MESSAGE|
260 1 Tijmen de Mes
|Address resolution|ENUM|
261 4 Tijmen de Mes
|From header|Must contain a non-local SIP domain|
262 30 Adrian Georgescu
|Fraud Control | None | 
263 2 Tijmen de Mes
264 4 Tijmen de Mes
* The domain name used by the PBX in the From field must be different than any domain served by the SIP Proxy otherwise the Proxy will challenge the session for credentials as it does for any other locally registered SIP account.
265 4 Tijmen de Mes
* To route incoming traffic for a number block assigned to the PBX, create ENUM entries that point to the hostname (or IP address) of the PBX.
266 4 Tijmen de Mes
267 4 Tijmen de Mes
h2. End-Point to PSTN
268 4 Tijmen de Mes
269 1 Tijmen de Mes
For interconnection with PSTN, a SIP trunking service must be setup between the SIP Proxy and the PSTN gateway provider. The authorization of SIP requests is based on transitive trust. The SIP Proxy has a trust relationship with each SIP subscriber and the PSTN gateway has a trust relation with the SIP Proxy. The trust relation between the SIP Proxy and the PSTN gateway is based on the IP addresses. The PSTN gateway cannot use DIGEST authentication in the relation with the SIP Proxy because it does not have access to the SIP accounts database of the SIP Proxy.
270 1 Tijmen de Mes
271 4 Tijmen de Mes
h3. PSTN Gateway Requirements
272 2 Tijmen de Mes
273 2 Tijmen de Mes
Must have:
274 2 Tijmen de Mes
275 4 Tijmen de Mes
* SIP signaling based on RFC 3261
276 4 Tijmen de Mes
* DNS lookups based on RFC 3263
277 4 Tijmen de Mes
* Support for SIP extensions for caller id and privacy (P headers)
278 4 Tijmen de Mes
* RTP active mode (send RTP data as soon as call setup is completed)
279 4 Tijmen de Mes
* Use public routable IP addresses for both signaling and media
280 2 Tijmen de Mes
281 2 Tijmen de Mes
Recommended:
282 2 Tijmen de Mes
283 4 Tijmen de Mes
* ENUM lookups based on RFC 3761
284 2 Tijmen de Mes
285 2 Tijmen de Mes
Routing to PSTN destinations is realized by provisioning the PSTN carriers, gateways and routes (also known as Least Cost Routing engine or LCR). The structure of the PSTN provisioning is as follows:
286 2 Tijmen de Mes
287 9 Tijmen de Mes
  Route ->  Carriers -> Gateways -> Rules
288 2 Tijmen de Mes
289 2 Tijmen de Mes
290 45 Tijmen de Mes
For each PSTN prefix (called a PSTN route) a set of carriers can be assigned with an optional priority. Each carrier can have one or more gateways and each gateway can have optional rules for converting the number. For more information see the "provisioning guide":/projects/documentation/wiki/Provisioning_guide
291 4 Tijmen de Mes
292 2 Tijmen de Mes
Once the SIP request is authenticated, the SIP Proxy authorizes the request based on the rights associated with the subscriber account and decides whether a SIP session to the PSTN gateway is allowed or not. If the session is allowed, the SIP Proxy asserts an identity associated to the SIP account, which can be the telephone number presented as caller ID to the destination, locates a PSTN gateway for the dialed number (by using least cost routing or other configured logic) and forwards the request to the PSTN gateways inserting itself in the path of subsequent messages.
293 2 Tijmen de Mes
294 7 Tijmen de Mes
!flow-sip-phone-a-pstn.png!
295 2 Tijmen de Mes
296 2 Tijmen de Mes
297 4 Tijmen de Mes
|Authentication|SIP account A|
298 4 Tijmen de Mes
|Authorization|SIP account A|
299 4 Tijmen de Mes
|Caller Id|Asserted by the platform|
300 1 Tijmen de Mes
|Billing party|SIP account A|
301 4 Tijmen de Mes
|Accounting|Postpaid, Prepaid|
302 36 Adrian Georgescu
|Media types|RTP (audio, video), T.38 Fax, SIP MESSAGE|
303 4 Tijmen de Mes
|Address resolution|ENUM, LCR|
304 2 Tijmen de Mes
|From header|Must contain a local SIP domain|
305 45 Tijmen de Mes
|Fraud Control | PIKE, ACL, Call limit |
306 2 Tijmen de Mes
307 4 Tijmen de Mes
h3. Caller id indication
308 2 Tijmen de Mes
309 4 Tijmen de Mes
The platform generates a Caller ID indication by appending Remote-Party-Id or P-Asserted identity headers, depending on its configuration. The content of the headers is generated with the SipAccount->rpid attribute associated with the SIP account.
310 2 Tijmen de Mes
311 4 Tijmen de Mes
h2. PSTN to End-Point
312 2 Tijmen de Mes
313 4 Tijmen de Mes
The platform is designed to accept traffic from outside SIP end-points (this includes remote PSTN gateways) to any local user. This means that a PSTN gateway that initiates a session to a correct SIP address user@domain belonging to the platform will be accepted and routed to the SIP devices belonging to the user with no extra configurations. When a SIP session originates from the PSTN, only the dialed telephone (a.k.a. E.164) number is known. For routing sessions from the PSTN to the SIP Proxy of the platform the gateway must translate the telephone number into a valid SIP address.
314 2 Tijmen de Mes
315 41 Tijmen de Mes
PSTN gateways for incoming traffic to local users must be provisioned in the *PSTN Gateways* section of Provisioning server by *IP*. Because they are only used for incoming traffic, no *PSTN route* or *PSTN rules* must be added for them. These PSTN gateways that should *not* transit the platform don't need an entry in *Trusted Peers*.
316 40 Tijmen de Mes
317 4 Tijmen de Mes
h4. ENUM Routing
318 4 Tijmen de Mes
319 7 Tijmen de Mes
!msp-enum-lookup.png!
320 4 Tijmen de Mes
321 2 Tijmen de Mes
The ideal way to achieve this number translation with minimum configuration is for the PSTN gateway to perform an ENUM lookup (RFC 3761). All popular open source software gateways like Asterisk and OpenSIPS are able to perform ENUM lookups and commercial gateways have started adding this support into their commercial products.
322 2 Tijmen de Mes
323 2 Tijmen de Mes
The ENUM look-up queries the DNS server provisioned with E.164 numbers by the operator, which is always kept up to date by the operator. The result of a successful ENUM lookup is a SIP address. Once the ENUM lookup is complete, the PSTN gateway can initiate the SIP session to the SIP address returned by the ENUM lookups.
324 2 Tijmen de Mes
325 2 Tijmen de Mes
The only setting required in the PSTN gateway for this setup is the top level domain used to perform ENUM lookups. The ENUM top level domain must be the same used by the SIP Proxy lookup and NGNPro provisioning.
326 2 Tijmen de Mes
327 4 Tijmen de Mes
h4. Manual Routing
328 2 Tijmen de Mes
329 4 Tijmen de Mes
For PSTN gateways that are not able to perform ENUM lookups and from which we need to accept incoming sessions, the SIP Proxy can be configured to accept any traffic, manipulate the number format based on custom rules and help performing the ENUM lookup in the behalf of the gateway.
330 2 Tijmen de Mes
331 2 Tijmen de Mes
The PSTN gateway must be configured for the E.164 number ranges to be routed to the MSP platform and the hostname of the SIP Proxy machine (e.g. sip.example.com). Do not use static IP addresses in the PSTN configuration, use the DNS name configured by the operator so that when the IP addresses of the SIP Proxy change or when multiple SIP Proxies are used by default (like in SIP Thor) the gateway does not need to be re-configured.
332 2 Tijmen de Mes
333 2 Tijmen de Mes
You must setup the following SIP Proxy configuration file:
334 2 Tijmen de Mes
335 8 Tijmen de Mes
  sipproxy:/etc/opensips/config/siteconfig/handle-incoming-pstn.m4
336 2 Tijmen de Mes
337 2 Tijmen de Mes
338 4 Tijmen de Mes
Example:
339 1 Tijmen de Mes
340 1 Tijmen de Mes
<pre class="wiki">
341 38 Adrian Georgescu
if (src_ip == 201.176.11.13) {
342 38 Adrian Georgescu
    DINFO("Call from Carrier 1");
343 2 Tijmen de Mes
344 31 Adrian Georgescu
    $rd = "SERVER_DOMAIN";
345 31 Adrian Georgescu
    prefix("+");
346 31 Adrian Georgescu
    set_billing_party();
347 31 Adrian Georgescu
    DINFO("Performing ENUM lookup");
348 31 Adrian Georgescu
    route(__ENUM_LOOKUP);
349 31 Adrian Georgescu
   
350 31 Adrian Georgescu
    if ($retcode==-1) {
351 31 Adrian Georgescu
        DINFO("User not found");
352 31 Adrian Georgescu
        sl_send_reply('404', 'User not found');
353 31 Adrian Georgescu
        LOG_MISSED_CALL('404');
354 30 Adrian Georgescu
        exit;
355 31 Adrian Georgescu
    } else if (!is_uri_host_local()) {  
356 31 Adrian Georgescu
        DINFO("Call to non local user");
357 31 Adrian Georgescu
        sl_send_reply('403', 'Invalid destination');
358 31 Adrian Georgescu
        LOG_MISSED_CALL('403');
359 4 Tijmen de Mes
        exit;
360 1 Tijmen de Mes
    }
361 4 Tijmen de Mes
}
362 4 Tijmen de Mes
</pre>
363 4 Tijmen de Mes
364 4 Tijmen de Mes
365 2 Tijmen de Mes
|Authentication|None|
366 2 Tijmen de Mes
|Authorization|Custom SIP Proxy logic|
367 4 Tijmen de Mes
|Billing party|Trusted peer|
368 4 Tijmen de Mes
|Accounting|Postpaid|
369 7 Tijmen de Mes
|Media types|RTP (audio)|
370 4 Tijmen de Mes
|From header|Must contain a non-local SIP domain|
371 2 Tijmen de Mes
|Address resolution|ENUM, Custom SIP Proxy logic|
372 2 Tijmen de Mes
373 29 Adrian Georgescu
h2. PBX to PSTN
374 1 Tijmen de Mes
375 2 Tijmen de Mes
!flow-pbx-a-pstn.png!
376 2 Tijmen de Mes
377 1 Tijmen de Mes
To allow high call per second ratios for call centers or other high density traffic, many checks related to individual accounts are disabled when using trusted peers. Simultaneous call limit, Access Lists, Pike flood detection, quota checks are disabled. Also trusted peers, as their name imply, are allowed to set Caller Id information and Privacy headers, the SIP Proxy will not check nor enforce them fro Trusted peers.
378 34 Adrian Georgescu
379 34 Adrian Georgescu
|Authentication|Based on source IP address|
380 36 Adrian Georgescu
|Authorization|None required, transit is allowed|
381 36 Adrian Georgescu
|Caller Id|Supplied by trusted peer|
382 36 Adrian Georgescu
|Billing party|IP address|
383 36 Adrian Georgescu
|Accounting|Postpaid|
384 36 Adrian Georgescu
|Media types|RTP (audio, video), T.38 Fax, SIP MESSAGE|
385 34 Adrian Georgescu
|Address resolution|ENUM, LCR, Custom SIP Proxy logic|
386 34 Adrian Georgescu
|From header|Must contain a non-local SIP domain|
387 39 Adrian Georgescu
|Request URI|Must contain a local SIP domain|
388 34 Adrian Georgescu
|Fraud control|Source IP only|
389 1 Tijmen de Mes
390 1 Tijmen de Mes
391 34 Adrian Georgescu
h3. Routing
392 35 Adrian Georgescu
393 35 Adrian Georgescu
To allow transiting the proxy, *handle-incoming-pstn.m4* configuration file is configured with this logic:
394 34 Adrian Georgescu
395 32 Adrian Georgescu
<pre>
396 32 Adrian Georgescu
if (FROM_TRUSTED_PARTY) {
397 32 Adrian Georgescu
    DINFO("Call from trusted party");
398 32 Adrian Georgescu
399 32 Adrian Georgescu
    $var(need_transit) = 0;
400 32 Adrian Georgescu
    if (uri =~ "^sip:PSTN_REGEXP@.*") {
401 32 Adrian Georgescu
        $rd = "SERVER_DOMAIN";
402 32 Adrian Georgescu
        strip(2);
403 32 Adrian Georgescu
        prefix("+");
404 32 Adrian Georgescu
        set_billing_party();
405 32 Adrian Georgescu
        DINFO("Performing ENUM lookup");
406 32 Adrian Georgescu
        route(__ENUM_LOOKUP);
407 32 Adrian Georgescu
408 32 Adrian Georgescu
        if ($retcode==-1) {
409 32 Adrian Georgescu
            DINFO("ENUM number not found. PSTN transit");
410 32 Adrian Georgescu
            revert_uri();
411 32 Adrian Georgescu
            $var(need_transit) = 1;
412 32 Adrian Georgescu
        }
413 32 Adrian Georgescu
    } else if (uri =~ "^sip:LOCAL_PSTN_REGEXP@.*") {
414 32 Adrian Georgescu
        $rd = "SERVER_DOMAIN";
415 32 Adrian Georgescu
        strip(1);
416 32 Adrian Georgescu
        prefix("+COUNTRY_CODE");
417 32 Adrian Georgescu
        set_billing_party();
418 32 Adrian Georgescu
        DINFO("Performing ENUM lookup");
419 32 Adrian Georgescu
        route(__ENUM_LOOKUP);
420 32 Adrian Georgescu
421 32 Adrian Georgescu
        if ($retcode==-1) {
422 32 Adrian Georgescu
            DINFO("ENUM number not found. PSTN transit");
423 32 Adrian Georgescu
            revert_uri();
424 32 Adrian Georgescu
            $var(need_transit) = 1;
425 32 Adrian Georgescu
        }
426 32 Adrian Georgescu
    } else if (uri =~ "^sip:COUNTRY_CODE[1-9][0-9]{4,}@.*") {
427 32 Adrian Georgescu
        $rd = "SERVER_DOMAIN";
428 32 Adrian Georgescu
        prefix("+");
429 32 Adrian Georgescu
        set_billing_party();
430 32 Adrian Georgescu
        DINFO("Performing ENUM lookup");
431 32 Adrian Georgescu
        route(__ENUM_LOOKUP);
432 32 Adrian Georgescu
433 32 Adrian Georgescu
        if ($retcode==-1) {
434 32 Adrian Georgescu
            DINFO("ENUM number not found. PSTN transit");
435 32 Adrian Georgescu
            revert_uri();
436 32 Adrian Georgescu
            $var(need_transit) = 1;
437 32 Adrian Georgescu
        }
438 32 Adrian Georgescu
    } else if (uri =~ "^sip:\+[0-9]{7,}@.*") {
439 32 Adrian Georgescu
        $rd = "SERVER_DOMAIN";
440 32 Adrian Georgescu
        set_billing_party();
441 32 Adrian Georgescu
        DINFO("Performing ENUM lookup");
442 32 Adrian Georgescu
        route(__ENUM_LOOKUP);
443 32 Adrian Georgescu
        if ($retcode==-1) {
444 32 Adrian Georgescu
            DINFO("ENUM number not found. PSTN transit");
445 32 Adrian Georgescu
            strip(1);
446 32 Adrian Georgescu
            prefix("00");
447 32 Adrian Georgescu
            $var(need_transit) = 1;
448 32 Adrian Georgescu
        }
449 32 Adrian Georgescu
    }
450 32 Adrian Georgescu
    if ($var(need_transit) == 1) {
451 32 Adrian Georgescu
        DINFO("Transit call from trusted peer $si");
452 32 Adrian Georgescu
        route(__PSTN_TRANSIT);
453 32 Adrian Georgescu
        exit;
454 32 Adrian Georgescu
    }
455 32 Adrian Georgescu
456 32 Adrian Georgescu
    # Check if it's a local user
457 32 Adrian Georgescu
    if (!is_uri_host_local()) {
458 32 Adrian Georgescu
        set_billing_party();
459 32 Adrian Georgescu
        setflag(ACCOUNTING_FLAG);
460 32 Adrian Georgescu
        $avp(can_uri) = $ru;
461 32 Adrian Georgescu
        t_on_reply("__INVITE_REPLY");
462 32 Adrian Georgescu
        if (!isflagset(NO_MEDIAPROXY_FLAG)) {
463 4 Tijmen de Mes
            DINFO("Engaging mediaproxy for SIP transit call");
464 4 Tijmen de Mes
            engage_media_proxy();
465 29 Adrian Georgescu
        }
466 29 Adrian Georgescu
        $avp(invite_timeout) = OUTGOING_TIMEOUT;
467 4 Tijmen de Mes
        DINFO("Set timeout to OUTGOING_TIMEOUT");
468 29 Adrian Georgescu
        route(__SEND_OUT);
469 29 Adrian Georgescu
        exit;
470 29 Adrian Georgescu
    }
471 2 Tijmen de Mes
}
472 1 Tijmen de Mes
</pre>
473 1 Tijmen de Mes
474 33 Adrian Georgescu
h3. Provisioning
475 33 Adrian Georgescu
476 33 Adrian Georgescu
The IP address(es) of the PBX must be added in the trusted table using the SOAP/XML provisioning API. To allow trusted parties to transit your SIP Proxy edit sip:/etc/opensips/config/siteconfig/handle-incoming-pstn.m4 and add to it:
477 33 Adrian Georgescu
478 2 Tijmen de Mes
 * The domain name used by the PBX in the From field must be different than any domain served by the SIP Proxy otherwise the Proxy will challenge the session for credentials as it does for any other locally registered SIP account.
479 4 Tijmen de Mes
 * The domain name used by the PBX in the Request URI must be different than any domain served by the SIP Proxy otherwise the Proxy will try to lookup a local user.
480 2 Tijmen de Mes
481 1 Tijmen de Mes
h3. Rating
482 2 Tijmen de Mes
483 4 Tijmen de Mes
To rate the traffic generated by trusted peers you must add a rating plan in CDRTool rating engine based on the source IP address (the gateway field in rating customers table). Beware that no quota can be imposed on the traffic of a trusted peer.
484 2 Tijmen de Mes
485 33 Adrian Georgescu
h3. Caller Id
486 2 Tijmen de Mes
487 2 Tijmen de Mes
Traffic generated by the trusted peers and any header thereof containing caller id indication is also trusted. When allowing traffic to transit from PBXs to PSTN gateways connected to the, make sure that the way caller ID indication is provided by the trusted party is compatible with what the PSTN gateway expects.
488 4 Tijmen de Mes
489 4 Tijmen de Mes
h2. PSTN to PBX
490 4 Tijmen de Mes
491 4 Tijmen de Mes
!flow-pbx-a-pstn.png!
492 4 Tijmen de Mes
493 4 Tijmen de Mes
494 4 Tijmen de Mes
|Authentication|None|
495 4 Tijmen de Mes
|Authorization|Trusted peer PSTN gateway|
496 2 Tijmen de Mes
|Caller Id|Supplied by PSTN gateway|
497 4 Tijmen de Mes
|Billing party|Trusted peer PSTN gateway|
498 4 Tijmen de Mes
|Accounting|Postpaid|
499 37 Adrian Georgescu
|Media types|RTP audio, T.38 Fax, SIP MESSAGE|
500 4 Tijmen de Mes
|From header|Must contain a non-local SIP domain|
501 2 Tijmen de Mes
|Address resolution|ENUM, Custom SIP Proxy logic|
502 2 Tijmen de Mes
503 2 Tijmen de Mes
h2. Call Diversion
504 4 Tijmen de Mes
505 4 Tijmen de Mes
!flow-sip-phone-a-b-diverted.png!
506 4 Tijmen de Mes
507 4 Tijmen de Mes
A user may chose to divert his/her calls based on various conditions (like unconditional, busy or not online) to another SIP address including PSTN destinations. Diverted calls are always charged to the user who enabled them. For every call diversion, a new Diversion header is appended to the original SIP request.
508 1 Tijmen de Mes
509 28 Tijmen de Mes
510 4 Tijmen de Mes
|Authentication|SIP account A|
511 4 Tijmen de Mes
|Authorization|SIP account A|
512 4 Tijmen de Mes
|Billing party|SIP account B|
513 7 Tijmen de Mes
|Accounting|Postpaid, Prepaid|
514 4 Tijmen de Mes
|Address resolution|SIP address, SIP alias, Quickdial, ENUM, LCR|
515 2 Tijmen de Mes
|Fraud control | Forwarding destinations can be limited |
516 2 Tijmen de Mes
517 46 Adrian Georgescu
h2. Voice prompts
518 46 Adrian Georgescu
519 46 Adrian Georgescu
To add a new voice - prompt, copy existing examples available in OpenSIPS and Asterisk configurations.
520 46 Adrian Georgescu
521 46 Adrian Georgescu
 * /etc/opensips/config/settings.m4 on OpenSIPS
522 46 Adrian Georgescu
 * /etc/asterisk/config/siteconfig/extensions-extra-prompts.m4 on Asterisk
523 46 Adrian Georgescu
524 46 Adrian Georgescu
Copy the new voice prompt in WAV format sampled at 16KHz, mono channel to thjis location:
525 46 Adrian Georgescu
526 46 Adrian Georgescu
 * /usr/share/msp-media-services/prompts/
527 46 Adrian Georgescu
528 46 Adrian Georgescu
To route calls to a voice-prompt extention you can use ENUM mappings 
529 46 Adrian Georgescu
 
530 46 Adrian Georgescu
531 2 Tijmen de Mes
h2. Presence
532 4 Tijmen de Mes
533 4 Tijmen de Mes
!flow-presence.png!
534 4 Tijmen de Mes
535 2 Tijmen de Mes
Multiple watchers are subscribed to a publisher. The Publisher authorizes the watchers to subscriber to presence notifications by updating pres-rules XCAP document. The Publisher must subscribe to event presence.winfo to receive notifications from the Presence Agent about the watcher list.
536 18 Adrian Georgescu
537 4 Tijmen de Mes
538 7 Tijmen de Mes
|Authorization|XCAP pres-rules|
539 4 Tijmen de Mes
|Address resolution|SIP address, SIP alias, Quickdial, ENUM|
540 2 Tijmen de Mes
|Accounting|None|
541 2 Tijmen de Mes
542 1 Tijmen de Mes
h2. Presence using RLS
543 15 Adrian Georgescu
544 15 Adrian Georgescu
!flow-rls-services.png!
545 15 Adrian Georgescu
546 4 Tijmen de Mes
A subscriber uploads to the XCAP server a resource list. Then it subscribes to the list by sending a SUBSCRIBE for event presence with extra header Supported: eventlist, the Presence agent then subscribes to all recipients from the resource lists and returns consolidated NOTIFY with the state of all lists.
547 1 Tijmen de Mes
548 1 Tijmen de Mes
549 4 Tijmen de Mes
|Authorization|XCAP org.openmobilealliance.pres-rules|
550 4 Tijmen de Mes
|Contacts Storage| XCAP rls-services and resource-lists|
551 7 Tijmen de Mes
|Signaling|RLS SUBSCRIBE RFC4662 and RLMI NOTIFY RFC4662|
552 4 Tijmen de Mes
|Address resolution|SIP address, SIP alias, Quickdial, ENUM|
553 1 Tijmen de Mes
|Accounting|None|
554 1 Tijmen de Mes
555 4 Tijmen de Mes
h2. IM using MSRP Relay
556 1 Tijmen de Mes
557 7 Tijmen de Mes
!flow-msrp-relay.png!
558 1 Tijmen de Mes
559 4 Tijmen de Mes
Instant Messaging based on MSRP protocol is similar to a regular SIP audio session. Instead of RTP media , MSRP is used for establishing a media channel. Instead of MediaProxy, A MSRP relay is used to traverse the NAT. The called party reserves a session in the MSRP relay and offeres it in the response to the SIP INVITE. The calling party the initiates a TCP/TLS connection to the relay reserved address and the called party does the same. By using the relay both parties can establish a TCP flow from behind their NAT routers.
560 1 Tijmen de Mes
561 4 Tijmen de Mes
h2. IM using MSRP ACM
562 1 Tijmen de Mes
563 7 Tijmen de Mes
!flow-msrp-acm.png!
564 1 Tijmen de Mes
565 1 Tijmen de Mes
MSRP ACM is an alternative method for traversing NAT that is standardized by 3GPP that is interoperable with the IETF MSRP relay specification. The SBC mangles the SDP and stays in the SIP signaling and MSRP media path and forces the end-points to be both active (that is starting the outbound MSRP connection) when behind NAT.
566 1 Tijmen de Mes
567 4 Tijmen de Mes
h2. IM using MSRP ACM and Relay
568 4 Tijmen de Mes
569 1 Tijmen de Mes
!flow-msrp-acm-relay.png!
570 1 Tijmen de Mes
571 4 Tijmen de Mes
MSRP ACM and Relay methodologies can interoperate.
572 1 Tijmen de Mes
573 4 Tijmen de Mes
h2. File Transfer
574 1 Tijmen de Mes
575 21 Tijmen de Mes
File transfer based on MSRP protocol is similar to a regular SIP audio session. Instead of RTP media , MSRP is used for establishing a media channel. A MSRP relay is used to traverse the NAT.
576 1 Tijmen de Mes
577 16 Adrian Georgescu
h2. Emergency Calls
578 16 Adrian Georgescu
579 16 Adrian Georgescu
Emergency calls refer to dialing short numbers usually associated with emergency services like police or fire-brigade (e.g. 112 or 911). When a session is setup to a short number designated as an emergency number (in the SIP Proxy configuration), a database lookup is performed by the proxy in the emergency&#95;mapping table. Based on the *region* attribute provisioned with the SIP account, the final destination corresponding with the emergency number is looked up. Only local users can dial an emergency number.
580 16 Adrian Georgescu
581 16 Adrian Georgescu
See [[Provisioning_guide#Emergency-Numbers|"Provisioning the emergency numbers"]] section for more information.
582 16 Adrian Georgescu
583 17 Adrian Georgescu
h2. XMMP gateway
584 1 Tijmen de Mes
585 1 Tijmen de Mes
The platform can be setup to federate with remote XMPP domains using a gateway function. The functionality is described at:
586 1 Tijmen de Mes
587 4 Tijmen de Mes
http://sylkserver.ag-projects.com/projects/sylkserver/wiki/DesignXMPP
588 4 Tijmen de Mes
589 4 Tijmen de Mes
h2. PBX Media Functions
590 4 Tijmen de Mes
591 4 Tijmen de Mes
Functions involving playing media in the middle of a call setup are not possible by the design of a SIP Proxy. Features like:
592 4 Tijmen de Mes
593 1 Tijmen de Mes
* IVR
594 4 Tijmen de Mes
* Auto-attendant
595 1 Tijmen de Mes
* Call queues and ACD
596 1 Tijmen de Mes
* Listen-in and barge-in
597 1 Tijmen de Mes
* Call parking
598 1 Tijmen de Mes
* Music on hold (MoH)
599 1 Tijmen de Mes
600 1 Tijmen de Mes
are not performed by a SIP Proxy. Such functions can be implemented only by dedicated IP-PBX added to the platform. The platform is used to route calls between such PBXs, from the MSP perspective these PBX are seen as SIP trunks connected to the platform.