<p>Harald Welte has uploaded this change for <strong>review</strong>.</p><p><a href="https://gerrit.osmocom.org/10363">View Change</a></p><pre style="font-family: monospace,monospace; white-space: pre-wrap;">hlr: Add chapter on USSD configuration<br><br>Change-Id: Ie5196ece9f340303bcb4868e3333a9698e28c3d0<br>---<br>A OsmoHLR/chapters/ussd.adoc<br>M OsmoHLR/osmohlr-usermanual.adoc<br>2 files changed, 80 insertions(+), 0 deletions(-)<br><br></pre><pre style="font-family: monospace,monospace; white-space: pre-wrap;">git pull ssh://gerrit.osmocom.org:29418/osmo-gsm-manuals refs/changes/63/10363/1</pre><pre style="font-family: monospace,monospace; white-space: pre-wrap;"><span>diff --git a/OsmoHLR/chapters/ussd.adoc b/OsmoHLR/chapters/ussd.adoc</span><br><span>new file mode 100644</span><br><span>index 0000000..5e907a8</span><br><span>--- /dev/null</span><br><span>+++ b/OsmoHLR/chapters/ussd.adoc</span><br><span>@@ -0,0 +1,78 @@</span><br><span style="color: hsl(120, 100%, 40%);">+[[ussd]]</span><br><span style="color: hsl(120, 100%, 40%);">+== Unstructured Supplementary Services Data (USSD)</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+The _Unstructured Supplementary Services Data (USSD)_ is one service within</span><br><span style="color: hsl(120, 100%, 40%);">+2G/3G networks next to other services such as circuit-switched voice, packet-switched</span><br><span style="color: hsl(120, 100%, 40%);">+data and SMS (Short Message Service).</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+It is on an abstract level quite similar to SMS in that USSD can be used to send</span><br><span style="color: hsl(120, 100%, 40%);">+textual messages.  However, there are the following differences:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+* USSD is between the MS (phone) and an USSD application on the network, while</span><br><span style="color: hsl(120, 100%, 40%);">+  SMS is primarily between two subscribers identified by their MSISDN</span><br><span style="color: hsl(120, 100%, 40%);">+* USSD is faster, as it doesn't suffer from the complicated three-layer CP/RP/TP</span><br><span style="color: hsl(120, 100%, 40%);">+  protocol stack of SMS with it's acknowledgement of the acknowledged acknowledgement.</span><br><span style="color: hsl(120, 100%, 40%);">+* USSD is session-oriented, i.e. a dialogue/session between subscriber and application</span><br><span style="color: hsl(120, 100%, 40%);">+  can persist for the transfer of more than one message.  The dedicated radio channel</span><br><span style="color: hsl(120, 100%, 40%);">+  on the RAN remains established throughout that dialogue.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+=== USSD in Osmocom</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Until August 2018, OsmoMSC contained some minimalistic internal USSD</span><br><span style="color: hsl(120, 100%, 40%);">+handling with no</span><br><span style="color: hsl(120, 100%, 40%);">+ability to attach/extend it with external USSD applications.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+From August 2018 onwards, OsmoMSC doesn't contain any internal USSD</span><br><span style="color: hsl(120, 100%, 40%);">+handlers/applications anymore.  Instead, all USSD is transported to/from</span><br><span style="color: hsl(120, 100%, 40%);">+OsmoHLR via the GSUP protocol.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+OsmoHLR contains some intenal USSD handlers and can route USSD messages</span><br><span style="color: hsl(120, 100%, 40%);">+to any number of external USSD entities (EUSEs).  The EUSE also use GSUP</span><br><span style="color: hsl(120, 100%, 40%);">+to communicate USSD from/to OsmoHLR.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Each EUSE is identified by its name.  The name consists of a single-word</span><br><span style="color: hsl(120, 100%, 40%);">+string preceding a currently fixed ("-00-00-00-00-00-00") suffix.</span><br><span style="color: hsl(120, 100%, 40%);">+There is no authentication between EUSE and OsmoHLR: Any lient program</span><br><span style="color: hsl(120, 100%, 40%);">+able to connect to the GSUP port of OsmoHLR can register as any EUSE</span><br><span style="color: hsl(120, 100%, 40%);">+(name).</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+NOTE:: We plan to remove the requirement for this suffix as soon as we</span><br><span style="color: hsl(120, 100%, 40%);">+are done resolving all more important issues.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+=== USSD Configuration</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+USSD configuration in OsmoHLR happens within the `hlr` VTY node.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+`euse foobar-00-00-00-00-00-00` defines an EUSE with the given name `foobar`</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+`ussd route prefix *123 external foobar-00-00-00-00-00-00` installs a</span><br><span style="color: hsl(120, 100%, 40%);">+prefix route to the named EUSE.  All USSD short codes starting with *123 will be</span><br><span style="color: hsl(120, 100%, 40%);">+routed to the named EUSE.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+`ussd route prefix *#100# internal own-msisdn` installs a prefix route</span><br><span style="color: hsl(120, 100%, 40%);">+to the named internal USSD handler.  There above command will restore</span><br><span style="color: hsl(120, 100%, 40%);">+the old behavior, in which #*100# will return a text message containing</span><br><span style="color: hsl(120, 100%, 40%);">+the subscribers own phone number.  There is one other handler called</span><br><span style="color: hsl(120, 100%, 40%);">+`own-imsi` which will return the IMSI instead of the MSISDN.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+`ussd default-route external foobar-00-00-00-00-00-00` installs a</span><br><span style="color: hsl(120, 100%, 40%);">+default route to the named EUSE.  This means that all USSD codes for</span><br><span style="color: hsl(120, 100%, 40%);">+which no more specific route exists will be routed to the named EUSE.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+=== Example EUSE program</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+We have provided an example EUSE developed in C language using existing</span><br><span style="color: hsl(120, 100%, 40%);">+Osmocom libraries for GSUP protocol handling and USSD encoding/decoding.</span><br><span style="color: hsl(120, 100%, 40%);">+It will register as `foobar` EUSE to OsmoHLR on localhost.  You can run</span><br><span style="color: hsl(120, 100%, 40%);">+it on a different machine by specifying e.g. `osmo-euse-demo 1.2.3.4 5678`</span><br><span style="color: hsl(120, 100%, 40%);">+to make it connect to OsmoHLR on IP address 1.2.3.4 and GSUP/TCP port</span><br><span style="color: hsl(120, 100%, 40%);">+5678.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+The idea is that you can use this as a template to develop your own USSD</span><br><span style="color: hsl(120, 100%, 40%);">+applications, or any gateways to other protocols or interfaces.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+You can find it in `osmo-hlr/src/osmo-euse-demo.c` or online by</span><br><span style="color: hsl(120, 100%, 40%);">+following the link to http://git.osmocom.org/osmo-hlr/tree/src/osmo-euse-demo.c</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+This demonstration program will echo back any USSD message sent/routed</span><br><span style="color: hsl(120, 100%, 40%);">+to it, quoted like _You sent "..."_.</span><br><span>diff --git a/OsmoHLR/osmohlr-usermanual.adoc b/OsmoHLR/osmohlr-usermanual.adoc</span><br><span>index 043c971..d9a4654 100644</span><br><span>--- a/OsmoHLR/osmohlr-usermanual.adoc</span><br><span>+++ b/OsmoHLR/osmohlr-usermanual.adoc</span><br><span>@@ -14,6 +14,8 @@</span><br><span> </span><br><span> include::chapters/subscribers.adoc[]</span><br><span> </span><br><span style="color: hsl(120, 100%, 40%);">+include::chapters/ussd.adoc[]</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span> include::../common/chapters/vty.adoc[]</span><br><span> </span><br><span> include::../common/chapters/logging.adoc[]</span><br><span></span><br></pre><p>To view, visit <a href="https://gerrit.osmocom.org/10363">change 10363</a>. To unsubscribe, or for help writing mail filters, visit <a href="https://gerrit.osmocom.org/settings">settings</a>.</p><div itemscope itemtype="http://schema.org/EmailMessage"><div itemscope itemprop="action" itemtype="http://schema.org/ViewAction"><link itemprop="url" href="https://gerrit.osmocom.org/10363"/><meta itemprop="name" content="View Change"/></div></div>

<div style="display:none"> Gerrit-Project: osmo-gsm-manuals </div>
<div style="display:none"> Gerrit-Branch: master </div>
<div style="display:none"> Gerrit-MessageType: newchange </div>
<div style="display:none"> Gerrit-Change-Id: Ie5196ece9f340303bcb4868e3333a9698e28c3d0 </div>
<div style="display:none"> Gerrit-Change-Number: 10363 </div>
<div style="display:none"> Gerrit-PatchSet: 1 </div>
<div style="display:none"> Gerrit-Owner: Harald Welte <laforge@gnumonks.org> </div>