Neels Hofmeyr | 43de5ef | 2019-11-20 15:03:59 +0100 | [diff] [blame] | 1 | == Distributed GSM / Multicast MS Lookup |
| 2 | |
| 3 | Distributed GSM (D-GSM) allows independent mobile core network stacks to provide voice, SMS and Roaming services to each |
| 4 | other, without the need for centralised entities or administration authority, and in a way that is resilient against |
| 5 | unstable network links between sites. |
| 6 | |
| 7 | D-GSM aims at communal networks, where several independent sites, let's call them villages, each have a full mobile core |
| 8 | network infrastructure. It elegantly provides ad-hoc service for subscribers moving across villages, and allows villages |
| 9 | to dynamically join or leave the cooperative network without the need for configuration changes at other sites. |
| 10 | |
| 11 | A challenge for linking separate sites is to find the current location of a subscriber. Typically, in mobile networks, a |
| 12 | centralized entity keeps track of where to Page for subscribers. Running several fully independent sites with unreliable |
| 13 | links between them makes it hard to provide such centralisation. |
| 14 | |
| 15 | D-GSM finds subscribers by mslookup, a service provided by OsmoHLR, typically using multicast DNS queries. This allows |
| 16 | routing Location Updating requests, calls, and SMS to the right site without administrative delay nor the need for a |
| 17 | reliable link to a central database. |
| 18 | |
| 19 | D-GSM is highly resilient against single sites or links becoming temporarily unavailable. Service between still |
| 20 | reachable sites simply continues; Service to a disconnected site resumes as soon as it becomes reachable again. |
| 21 | |
| 22 | This brings an entirely new paradigm to mobile core network infrastructure: as sites become reachable on the IP network |
| 23 | and join the common IP multicast group, services between them become available immediately. Basically, the only premise |
| 24 | is that IP routing and multicast works across sites, and that each site uses unique IPA names in the GSUP config. |
| 25 | |
| 26 | This chapter describes how D-GSM and mslookup work, and how to configure sites to use D-GSM, using Osmocom core network |
| 27 | infrastructure. |
| 28 | |
| 29 | === Finding Subscribers: mslookup Clients |
| 30 | |
| 31 | There are two fundamentally distinct subscriber lookups provided by the mslookup service. |
| 32 | |
| 33 | ==== Find the Current Location of an MSISDN |
| 34 | |
| 35 | [[fig_dgsm_connect]] |
| 36 | .mslookup for connecting subscribers: Alice is visiting village C; a phone call gets routed directly to her current location independently from her resident village infrastructure |
| 37 | [graphviz] |
| 38 | ---- |
| 39 | digraph G { |
| 40 | rankdir=LR |
| 41 | |
| 42 | subgraph cluster_village_b { |
| 43 | label="Village B" |
| 44 | ms_bob [label="Bob\n(from village B)",shape=box] |
| 45 | pbx_b [label="SIP B"] |
| 46 | } |
| 47 | |
| 48 | subgraph cluster_village_c { |
| 49 | label="Village C" |
| 50 | ms_alice [label="Alice\n(from village A)",shape=box] |
| 51 | msc_c [label="MSC C"] |
| 52 | hlr_c [label="HLR C"] |
| 53 | sip_c [label="SIP C"] |
| 54 | } |
| 55 | |
| 56 | ms_alice -> msc_c [style=dashed,arrowhead=none] |
| 57 | msc_c -> hlr_c [label="attached",style=dashed,arrowhead=none] |
| 58 | ms_bob -> pbx_b [label="call Alice"] |
| 59 | pbx_b -> hlr_c [label="mslookup by MSISDN",style=dotted,dir=both] |
| 60 | pbx_b -> sip_c -> msc_c -> ms_alice [label="call"] |
| 61 | } |
| 62 | ---- |
| 63 | |
| 64 | For example, if a subscriber is currently visiting another village, establish a phone call / send SMS towards that |
| 65 | village. |
| 66 | |
| 67 | - To deliver a phone call, a SIP agent integrates an mslookup client to request the SIP service of an MSISDN's current |
| 68 | location (example: <<dgsm_conf_dialplan>>). It receives an IP address and port to send the SIP Invite to. |
| 69 | |
| 70 | - To deliver an SMS, an ESME integrates an mslookup client to request the SMPP service of an MSISDN's current location |
| 71 | (example: <<dgsm_conf_esme_smpp>>). |
| 72 | |
| 73 | The current location of a subscriber may change at any time, and, when moving across locations, a subscriber may |
| 74 | suddenly lose reception to the previous location without explicitly detaching. Hence an mslookup request for the current |
| 75 | location of an MSISDN may get numerous responses. To find the currently valid location, mslookup includes the age of the |
| 76 | subscriber record, i.e. how long ago the subscriber was last reached. The one response with the youngest age reflects |
| 77 | the current location. |
| 78 | |
| 79 | In order to evaluate several responses, mslookup always waits for a fixed amount of time (1 second), and then evaluates |
| 80 | the available responses. |
| 81 | |
| 82 | Services are not limited to SIP and SMPP, arbitrarily named services can be added to the mslookup configuration. |
| 83 | |
| 84 | .Message sequence for locating an MSISDN to deliver a voice call |
| 85 | ["mscgen"] |
| 86 | ---- |
| 87 | msc { |
| 88 | hscale="2"; |
| 89 | moms[label="MS,BSS\nvillage A"],momsc[label="MSC,MGW\nvillage A"],mosipcon[label="osmo-sip-connector\nvillage A"],mopbx[label="PBX\nvillage A"],mthlr[label="OsmoHLR\nvillage B"],mtsipcon[label="osmo-sip-connector\nvillage B"],mtmsc[label="MGW,MSC\nvillage B"],mtms[label="RAN,MS\nvillage B"]; |
| 90 | |
| 91 | moms =>> momsc [label="CC Setup"]; |
| 92 | momsc =>> mosipcon [label="MNCC_SETUP_IND"]; |
| 93 | mosipcon =>> mopbx [label="SIP INVITE"]; |
| 94 | mopbx rbox mopbx [label="dialplan: launch mslookup by MSISDN"]; |
| 95 | --- [label="multicast-DNS query to all connected sites"]; |
| 96 | ...; |
| 97 | mopbx <<= mthlr [label="mDNS response\n(age)"]; |
| 98 | mopbx rbox mopbx [label="wait ~ 1s for more mDNS responses"]; |
| 99 | ...; |
| 100 | mopbx =>> mtsipcon [label="SIP INVITE (MT)"]; |
| 101 | mtmsc <<= mtsipcon [label="MNCC_SETUP_REQ"]; |
| 102 | mtms <<= mtmsc [label="Paging (CC)"]; |
| 103 | moms rbox mtms [label="voice call commences"]; |
| 104 | |
| 105 | } |
| 106 | ---- |
| 107 | |
| 108 | ==== Find the Home HLR for an IMSI |
| 109 | |
| 110 | [[fig_dgsm_roaming]] |
| 111 | .mslookup for Roaming: Alice visits village B; she can attach to the local mobile network, which proxies HLR administration to her home village. |
| 112 | [graphviz] |
| 113 | ---- |
| 114 | digraph G { |
| 115 | rankdir=LR |
| 116 | |
| 117 | subgraph cluster_village_b { |
| 118 | label="Village B" |
| 119 | |
| 120 | ms_alice [label="Alice\n(from village A)",shape=box] |
| 121 | msc_b [label="MSC B"] |
| 122 | hlr_b [label="HLR B"] |
| 123 | } |
| 124 | |
| 125 | subgraph cluster_village_a { |
| 126 | label="Village A" |
| 127 | hlr_alice [label="Alice's home HLR"] |
| 128 | } |
| 129 | |
| 130 | ms_alice -> msc_b -> hlr_b [label="Location\nUpdating"] |
| 131 | hlr_b -> hlr_alice [label="mslookup by IMSI",style=dotted,dir=both] |
| 132 | hlr_b -> hlr_alice [label="GSUP proxy forwarding"] |
| 133 | } |
| 134 | ---- |
| 135 | |
| 136 | For example, when attaching to a local network, a local resident gets serviced directly by the local village's HLR, |
| 137 | while a visitor from another village gets serviced by the remote village's HLR (Roaming). |
| 138 | |
| 139 | A home HLR typically stays the same for a given IMSI. If the home site is reachable, there should be exactly one |
| 140 | response to an mslookup request asking for it. The age of such a home-HLR response is always sent as zero. |
| 141 | |
| 142 | If a response's age is zero, mslookup does not wait for further responses and immediately uses the result. |
| 143 | |
| 144 | If there were more than one HLR accepting service for an IMSI, the one with the shortest response latency is used. |
| 145 | |
| 146 | === mslookup Configuration |
| 147 | |
| 148 | OsmoHLR the main mslookup agent. It provides the responses for both current location services as well as for locating |
| 149 | the fixed home-HLR. But naturally, depending on the mslookup request's purpose, different OsmoHLR instances will respond |
| 150 | for a given subscriber. |
| 151 | |
| 152 | - When querying the home HLR, it is always the (typically single) home HLR instance that sends the mslookup response. As |
| 153 | soon as it finds the queried IMSI in the local HLR database, an OsmoHLR will respond to home-HLR requests. |
| 154 | In <<fig_dgsm_roaming>>, Alice's home HLR responds to the Roaming request ("where is the home HLR?"). |
| 155 | |
| 156 | - When querying the location of an MSISDN, it is always the HLR proxy nearest to the servicing MSC that sends the |
| 157 | mslookup response. Even though the home HLR keeps the Location Updating record also for Roaming cases, it will only |
| 158 | respond to an mslookup service request if the subscriber has attached at a directly connected MSC. If attached at a |
| 159 | remote MSC, that MSC's remote HLR will be the GSUP proxy for the home HLR, and the remote HLR is responsible for |
| 160 | responding to service requests. |
| 161 | In <<fig_dgsm_roaming>>, HLR B is the nearest proxy and will answer all service requests ("where is this MSISDN?"). |
| 162 | Alice's home HLR will not answer service requests, because it detects that the servicing MSC is connected via another |
| 163 | HLR proxy. |
| 164 | |
| 165 | [[dgsm_example_config]] |
| 166 | ==== Example |
| 167 | |
| 168 | Here is an osmo-hlr.cfg mslookup configuration example for one site, which is explained in subsequent chapters. |
| 169 | |
| 170 | hlr |
| 171 | gsup |
| 172 | bind ip 10.9.8.7 |
| 173 | ipa-name hlr-23 |
| 174 | mslookup |
| 175 | mdns bind |
| 176 | server |
| 177 | service sip.voice at 10.9.8.7 5060 |
| 178 | service smpp.sms at 10.9.8.7 2775 |
| 179 | |
| 180 | OsmoHLR has both an mslookup server and a client. |
| 181 | |
| 182 | - The server responds to incoming service and home-HLR requests, when the local HLR is responsible. |
| 183 | - The client is used as GSUP proxy to a remote home HLR (found by mslookup upon a locally unknown IMSI). |
| 184 | - The client may also be used for forwarding SMS-over-GSUP. |
| 185 | |
| 186 | The mslookup service can be implemented by various methods. |
| 187 | At the time of writing, the only method implemented is mDNS. |
| 188 | |
| 189 | ==== mDNS |
| 190 | |
| 191 | The stock mslookup method is mDNS, multicast DNS. It consists of standard DNS encoding according to <<ietf-rfc1035>> and |
| 192 | <<ietf-rfc3596>>, but sent and received on IP multicast. In the response, standard A and AAAA records return the |
| 193 | service's IP address, while additional TXT records provide the service's port number and the MS attach age. |
| 194 | |
| 195 | TIP: To watch D-GSM mDNS conversations in wireshark, select "udp.port == 4266" (the default mslookup mDNS port |
| 196 | number), right click on the packet to "Decode as...", and select "DNS". |
| 197 | |
| 198 | In OsmoHLR, the mDNS server and client are typically both enabled at the same time: |
| 199 | |
| 200 | mslookup |
| 201 | mdns bind |
| 202 | |
| 203 | Server and client can also be enabled/disabled individually: |
| 204 | |
| 205 | mslookup |
| 206 | server |
| 207 | mdns bind |
| 208 | client |
| 209 | mdns bind |
| 210 | |
| 211 | These examples use the default mslookup multicast IP address and port. It is possible to configure custom IP address and |
| 212 | port, but beware that the IP address must be from a multicast range, see <<ietf-rfc5771>>: |
| 213 | |
| 214 | mslookup |
| 215 | mdns bind 239.192.23.42 4266 |
| 216 | |
| 217 | Domain names generated from mslookup queries (e.g. "sip.voice.123.msisdn") should not collide with IANA permitted |
| 218 | domains. Therefore we add the "mdns.osmocom.org" suffix. It can be overridden as follows: |
| 219 | |
| 220 | mslookup |
| 221 | mdns domain-suffix mdns.osmocom.org |
| 222 | |
| 223 | ==== Server: Site Services |
| 224 | |
| 225 | The mslookup server requires a list of service addresses provided at the local site, in order to respond to service |
| 226 | requests matching locally attached subscribers. |
| 227 | |
| 228 | mslookup |
| 229 | server |
| 230 | service sip.voice at 10.9.8.7 5060 |
| 231 | service smpp.sms at 10.9.8.7 2775 |
| 232 | |
| 233 | In this example: |
| 234 | |
| 235 | - "10.9.8.7 5060" are the IP address and port on which the local site's osmo-sip-connector is bound to receive SIP |
| 236 | Invite requests. |
| 237 | - "10.9.8.7 2775" are the local site's OsmoMSC SMPP bind address and port. |
| 238 | |
| 239 | Obviously, these IP addresses must be routable back to this site from all other sites. Using link-local or "ANY" |
| 240 | addresses, like 127.0.0.1 or 0.0.0.0, will not work here. Instead, each service config requires a public IP address that |
| 241 | all remote requestors are able to reach (not necessarily on the host that osmo-hlr is running on). |
| 242 | |
| 243 | If a site has more than one MSC, services can also be configured for each MSC individually, keyed by the IPA unit name |
| 244 | that each MSC sends on the GSUP link: |
| 245 | |
| 246 | mslookup |
| 247 | server |
| 248 | msc ipa-name msc-262-42-0 |
| 249 | service sip.voice at 10.11.12.13 5060 |
| 250 | service smpp.sms at 10.11.12.13 2775 |
| 251 | msc ipa-name msc-901-70-0 |
| 252 | service sip.voice at 10.9.8.7 5060 |
| 253 | service smpp.sms at 10.9.8.7 2775 |
| 254 | |
| 255 | Here, "msc-262-42-0" is the IPA name of a local OsmoMSC instance. To configure an OsmoMSC's IPA name on the GSUP link, |
| 256 | see osmo-msc.cfg, setting `hlr` / `ipa-name`. |
| 257 | |
| 258 | For mslookup service responses, only Location Updatings in the Circuit Switched domain are relevant. OsmoHLR does manage |
| 259 | IMSIs attaching in the Packet Switched domain (via an SGSN) similarly to Circuit Switched (via an MSC), but mslookup |
| 260 | completely ignores the Packet Switched attach status. |
| 261 | |
| 262 | ==== Server: Own GSUP Address |
| 263 | |
| 264 | When responding to home-HLR requests, OsmoHLR implicitly by default responds with its locally configured GSUP bind |
| 265 | address (setting `hlr` / `gsup` / `bind ip`). If required, an explicit local GSUP address and port can be configured, |
| 266 | for example: |
| 267 | |
| 268 | hlr |
| 269 | gsup |
| 270 | bind ip 0.0.0.0 |
| 271 | ipa-name hlr-23 |
| 272 | mslookup |
| 273 | server |
| 274 | # osmo-hlr's own GSUP address to send in mslookup responses: |
| 275 | service gsup.hlr at 10.9.8.7 4222 |
| 276 | |
| 277 | The gsup.hlr service can only be configured globally (because requests come from arbitrary mDNS clients, before a |
| 278 | Location Updating has associated the IMSI with the requesting MSC). |
| 279 | |
| 280 | ==== Client IPA Naming |
| 281 | |
| 282 | For reliable GSUP proxy routing to a remote HLR (Roaming), it is important that each GSUP client, i.e. each HLR, MSC and |
| 283 | SGSN instance, has a unique IPA name. |
| 284 | |
| 285 | Example for configuring an OsmoHLR instance's IPA name: |
| 286 | |
| 287 | hlr |
| 288 | gsup |
| 289 | ipa-name hlr-23 |
| 290 | |
| 291 | Here, "hlr-23" is the unique identification of this OsmoHLR instance across all potentially connected D-GSM sites. |
| 292 | |
| 293 | Furthermore, each MSC and SGSN must have a uniquely distinct IPA name across all sites (here "msc-262-42-0" and |
| 294 | "msc-901-70-0" are used as example IPA names for local MSCs). |
| 295 | |
| 296 | When this OsmoHLR connects to a remote HLR, be it for GSUP proxying or SMS-over-GSUP, it communicates its own IPA name |
| 297 | (on GSUP link-up) as well as the IPA name of the requesting client MSC/SGSN (as Source Name in each message) to the |
| 298 | remote OsmoHLR GSUP server. These names are used to route GSUP responses back to the respective requesting peer. |
| 299 | |
| 300 | If two MSCs were accidentally configured with identical names, a problem will occur as soon as both MSCs attempt to |
| 301 | attach to the same OsmoHLR (either directly or via GSUP proxying). The MSC that shows up first will work normally, but |
| 302 | any duplicate that shows up later will be rejected, since a route for its name already exists. |
| 303 | |
| 304 | === Queries |
| 305 | |
| 306 | In URL notation, typical mslookup queries look like: |
| 307 | |
| 308 | gsup.hlr.123456789.imsi |
| 309 | sip.voice.123.msisdn |
| 310 | smpp.sms.123.msisdn |
| 311 | |
| 312 | A query consists of |
| 313 | |
| 314 | - a service name ("gsup.hlr"), |
| 315 | - an id ("123456789"), |
| 316 | - the id type ("imsi"). |
| 317 | |
| 318 | The calling client also defines a timeout to wait for responses. |
| 319 | |
| 320 | The mslookup ID types are fixed, while service names can be chosen arbitrarily. |
| 321 | |
| 322 | .mslookup ID types, no other ID types are understood by mslookup |
| 323 | [options="header",width="100%",cols="20%,80%"] |
| 324 | |=== |
| 325 | |ID Type|Description |
| 326 | |imsi|An IMSI as existing in an OsmoHLR subscriber database |
| 327 | |msisdn|A phone number as configured in an OsmoHLR subscriber database |
| 328 | |=== |
| 329 | |
| 330 | .mslookup service name conventions, arbitrary service names can be added as required |
| 331 | [options="header",width="100%",cols="20%,20%,60%"] |
| 332 | |=== |
| 333 | |Service Name|Protocol|Description |
| 334 | |gsup.hlr | GSUP | Home HLR's GSUP server, to handle Location Updating related procedures |
| 335 | |sip.voice | SIP | OsmoSIPConnector, to receive a SIP Invite (MT side of a call) |
| 336 | |smpp.sms | SMPP | Destination OsmoMSC (or other SMPP server) to deliver an SMS to the recipient |
| 337 | |gsup.sms | GSUP | GSUP peer to deliver an SMS to the recipient using SMS-over-GSUP |
| 338 | |=== |
| 339 | |
| 340 | Arbitrarily named services can be added to the mslookup configuration and queried by mslookup clients; as soon as a |
| 341 | service name is present in osmo-hlr.cfg, it can be queried from any mslookup client. |
| 342 | |
| 343 | Service names should consist of a protocol name (like "sip", "gsup", "english") and an intended action/entity (like |
| 344 | "voice", "hlr", "greeting"). |
| 345 | |
| 346 | === Service Client Implementation |
| 347 | |
| 348 | In principle, arbitrary services could query target addresses via mslookup, leaving it up to any and all kinds of |
| 349 | clients to find their respective destination addresses. But of course, mslookup was designed with specific services in |
| 350 | mind, namely: |
| 351 | |
| 352 | - SIP call agents and |
| 353 | - SMS delivery (an ESME or SMSC) |
| 354 | |
| 355 | The following chapters describe examples of setting up a working distributed core network providing SIP voice calls and |
| 356 | SMS forwarding across sites. |
| 357 | |
| 358 | ==== mslookup Library |
| 359 | |
| 360 | The OsmoHLR provides an mslookup client C library, libosmo-mslookup. Service lookups can be integrated directly |
| 361 | in client programs using this library. However, its mDNS implementation requires the libosmocore select() loop, which |
| 362 | can be challenging to integrate in practice. An alternative solution is the osmo-mslookup-client tool. |
| 363 | |
| 364 | [[dgsm_osmo_mslookup_client]] |
| 365 | ==== osmo-mslookup-client |
| 366 | |
| 367 | The mslookup C library is available, but often, a simpler approach for client implementations is desirable: |
| 368 | |
| 369 | - When querying for a service address, the client is typically interested in the single final best result (youngest age |
| 370 | / first responding home HLR). |
| 371 | - Voice call and SMS clients typically would block until an mslookup result is known. For example, the FreeSwitch |
| 372 | dialplan integration expects a result synchronously, i.e. without waiting for mslookup responses via a select() loop. |
| 373 | - Integrating the libosmocore select() loop required for mDNS can break the already existing socket handling in the |
| 374 | client program. |
| 375 | |
| 376 | The osmo-mslookup-client cmdline tool provides a trivial way to synchronously acquire the single result for an mslookup |
| 377 | request. The service client can invoke an osmo-mslookup-client process per request and read the result from stdout. |
| 378 | |
| 379 | Each invocation obviously spawns a separate process and opens a multicast socket for mDNS. For better scalability, |
| 380 | osmo-mslookup-client can also be run as a daemon, providing results via a unix domain socket. Using synchronous write() |
| 381 | and recv() allows blocking until a result is received without interfering with the client program's select() setup. |
| 382 | |
| 383 | By itself, osmo-mslookup-client is also helpful as a diagnostic tool: |
| 384 | |
| 385 | ---- |
| 386 | $ osmo-mslookup-client sip.voice.1001.msisdn |
| 387 | sip.voice.1001.msisdn ok 10.9.8.7 5060 |
| 388 | |
| 389 | $ osmo-mslookup-client gsup.hlr.901700000014701.imsi |
| 390 | gsup.hlr.901700000014701.imsi ok 10.9.8.7 4222 |
| 391 | |
| 392 | $ osmo-mslookup-client gsup.hlr.111111.imsi |
| 393 | gsup.hlr.111111.imsi not-found |
| 394 | |
| 395 | $ osmo-mslookup-client gsup.hlr.1001.msisdn sip.voice.1001.msisdn smpp.sms.1001.msisdn foo.1001.msisdn |
| 396 | gsup.hlr.1001.msisdn ok 10.9.8.7 4222 |
| 397 | foo.1001.msisdn not-found |
| 398 | smpp.sms.1001.msisdn ok 10.9.8.7 2775 |
| 399 | sip.voice.1001.msisdn ok 10.9.8.7 5060 |
| 400 | |
| 401 | $ osmo-mslookup-client --csv-headers gsup.hlr.901700000014701.imsi |
| 402 | QUERY RESULT V4_IP V4_PORT V6_IP V6_PORT |
| 403 | gsup.hlr.901700000014701.imsi ok 10.9.8.7 4222 |
| 404 | |
| 405 | $ osmo-mslookup-client -f json gsup.hlr.901700000014701.imsi |
| 406 | {"query": "gsup.hlr.901700000014701.imsi", "result": "ok", "v4": ["10.9.8.7", "4222"]} |
| 407 | ---- |
| 408 | |
| 409 | For full help including example client invocations in Python, see the output of: |
| 410 | |
| 411 | osmo-mslookup-client -h |
| 412 | |
| 413 | ==== SIP Service Client |
| 414 | |
| 415 | [[dgsm_conf_dialplan]] |
| 416 | ===== FreeSwitch dialplan.py |
| 417 | |
| 418 | The FreeSWITCH PBX software <<freeswitch_pbx>> offers a Python integration to determine a SIP call recipient by a custom |
| 419 | dialplan implementation. An example dialplan implementation for FreeSWITCH that uses D-GSM mslookup is provided in the |
| 420 | osmo-hlr source tree under `contrib`, called `freeswitch_dialplan_dgsm.py`. |
| 421 | |
| 422 | To integrate it with your FREESWITCH setup, add a new `extension` block to your `dialplan/public.xml`: |
| 423 | |
| 424 | ---- |
| 425 | <extension name="outbound"> |
| 426 | <condition field="destination_number" expression=".*"> |
| 427 | <action application="set" data="hangup_after_bridge=true"/> |
| 428 | <action application="set" data="session_in_hangup_hook=true"/> |
| 429 | <action application="set" data="ringback=%(2000, 4000, 440.0, 480.0)"/> |
| 430 | <action application="python" data="freeswitch_dialplan_dgsm"/> |
| 431 | </condition> |
| 432 | </extension> |
| 433 | ---- |
| 434 | |
| 435 | Make sure that the dir containing `freeswitch_dialplan_dgsm.py` is in your `PYTHONPATH` environment variable, and start |
| 436 | the server: |
| 437 | |
| 438 | ---- |
| 439 | $ export PYTHONPATH="$PYTHONPATH:/home/user/code/osmo-hlr/contrib/dgsm" |
| 440 | $ freeswitch -nf -nonat -nonatmap -nocal -nort -c |
| 441 | ---- |
| 442 | |
| 443 | ==== SMS Service Client |
| 444 | |
| 445 | [[dgsm_conf_esme_smpp]] |
| 446 | ===== SMS via SMPP Port |
| 447 | |
| 448 | An example ESME using D-GSM mslookup, `esme_dgsm.py`, is provided in the osmo-hlr source tree under `contrib`. It |
| 449 | attaches to OsmoMSC's SMPP port to send SMS to recipients determined by mslookup. |
| 450 | |
| 451 | OsmoMSC should be configured as "smpp-first", so that all SMS routing is determined by mslookup. If configured without |
| 452 | smpp-first, OsmoMSC may try to deliver an SMS locally, even though the recipient has recently moved to a different site. |
| 453 | |
| 454 | An example OsmoMSC configuration to work with esme_dgsm.py: |
| 455 | |
| 456 | ---- |
| 457 | smpp |
| 458 | local-tcp-ip 127.0.0.1 2775 |
| 459 | system-id test-msc |
| 460 | policy closed |
| 461 | smpp-first |
| 462 | # outgoing to esme_dgsm.py |
| 463 | esme OSMPP |
| 464 | no alert-notifications |
| 465 | password foo |
| 466 | default-route |
| 467 | # incoming from esme_dgsm.py |
| 468 | esme ISMPP |
| 469 | no alert-notifications |
| 470 | password foo |
| 471 | ---- |
| 472 | |
| 473 | Launch esme_dgsm.py alongside OsmoMSC: |
| 474 | |
| 475 | ---- |
| 476 | ./esme_dgsm.py --src-host 127.0.0.1 |
| 477 | ---- |
| 478 | |
| 479 | esme_dgsm.py will be notified via SMPP for each SMS to be delivered, and will forward them either to a remote |
| 480 | recipient, or back to the same OsmoMSC, depending on the mslookup result. If the MSISDN is not reachable (or |
| 481 | esme_dgsm.py can't handle the message for other reasons), it returns the RSYSERR code back to OsmoMSC. |
| 482 | |
| 483 | Note that the esme_dgsm.py is a proof of concept and should not be used in production. It has several limitations, such |
| 484 | as not supporting multipart SMS messages. |
| 485 | |
| 486 | ===== SMS-Over-GSUP |
| 487 | |
| 488 | The GSUP protocol defines SMS delivery messages. When OsmoMSC is configured to deliver SMS via GSUP, MO SMS are directly |
| 489 | forwarded to the HLR, which will determine where to forward the SMS-over-GSUP messages using its mslookup client. |
| 490 | |
| 491 | FIXME implement this |