From 2c3b99e62aa45ae4c3631155795246056a3dddb9 Mon Sep 17 00:00:00 2001 From: Neels Hofmeyr Date: Mon, 18 Sep 2017 16:19:30 +0200 Subject: add OsmoMSC manual Change-Id: I9ecff2837fbf5fdc19675a726f6d70c21eb178ee --- Makefile | 4 + OsmoMSC/Makefile | 42 + OsmoMSC/chapters/control.adoc | 31 + OsmoMSC/chapters/mncc.adoc | 206 +++ OsmoMSC/chapters/net.adoc | 153 ++ OsmoMSC/chapters/overview.adoc | 123 ++ OsmoMSC/chapters/running.adoc | 138 ++ OsmoMSC/chapters/smpp.adoc | 146 ++ OsmoMSC/osmomsc-usermanual-docinfo.xml | 47 + OsmoMSC/osmomsc-usermanual.adoc | 39 + OsmoMSC/osmomsc-vty-reference.xml | 38 + OsmoMSC/vty/msc_vty_additions.xml | 24 + OsmoMSC/vty/msc_vty_reference.xml | 3019 ++++++++++++++++++++++++++++++++ 13 files changed, 4010 insertions(+) create mode 100644 OsmoMSC/Makefile create mode 100644 OsmoMSC/chapters/control.adoc create mode 100644 OsmoMSC/chapters/mncc.adoc create mode 100644 OsmoMSC/chapters/net.adoc create mode 100644 OsmoMSC/chapters/overview.adoc create mode 100644 OsmoMSC/chapters/running.adoc create mode 100644 OsmoMSC/chapters/smpp.adoc create mode 100644 OsmoMSC/osmomsc-usermanual-docinfo.xml create mode 100644 OsmoMSC/osmomsc-usermanual.adoc create mode 100644 OsmoMSC/osmomsc-vty-reference.xml create mode 100644 OsmoMSC/vty/msc_vty_additions.xml create mode 100644 OsmoMSC/vty/msc_vty_reference.xml diff --git a/Makefile b/Makefile index c09dd58..ffa25de 100644 --- a/Makefile +++ b/Makefile @@ -8,6 +8,7 @@ all: check-deps cd OsmoNAT; $(MAKE) cd OsmoPCU; $(MAKE) cd OsmoGSMTester; $(MAKE) + cd OsmoMSC; $(MAKE) clean: cd OsmoBTS; $(MAKE) clean @@ -19,6 +20,7 @@ clean: cd OsmoNAT; $(MAKE) clean cd OsmoPCU; $(MAKE) clean cd OsmoGSMTester; $(MAKE) clean + cd OsmoMSC; $(MAKE) clean upload: cd OsmoBTS; $(MAKE) upload @@ -30,6 +32,7 @@ upload: cd OsmoNAT; $(MAKE) upload cd OsmoPCU; $(MAKE) upload cd OsmoGSMTester; $(MAKE) upload + cd OsmoMSC; $(MAKE) upload check: cd OsmoBTS; $(MAKE) check @@ -42,6 +45,7 @@ check: #cd OsmoMGCP; $(MAKE) check #cd OsmoNAT; $(MAKE) check cd OsmoGSMTester; $(MAKE) check + cd OsmoMSC; $(MAKE) check define check_dep_bin @type $(1) >/dev/null 2>&1 || { echo >&2 "Binary '$(1)' not found in path, please install $(2)."; exit 1; } diff --git a/OsmoMSC/Makefile b/OsmoMSC/Makefile new file mode 100644 index 0000000..febf7d1 --- /dev/null +++ b/OsmoMSC/Makefile @@ -0,0 +1,42 @@ +# XSL stylesheets downloaded from http://docbook.sourceforge.net/release/xsl/current/html/ +# Makefile from BitBake/OpenEmbedded manuals + +topdir = . +msc_reference = $(topdir)/osmomsc-vty-reference.xml +manuals = $(msc_reference) +# types = pdf txt rtf ps xhtml html man tex texi dvi +# types = pdf txt +types = $(docbooktotypes) +docbooktotypes = pdf +# htmlcssfile = +# htmlcss = + +TOPDIR := .. +ASCIIDOCS := osmomsc-usermanual + +include $(TOPDIR)/build/Makefile.asciidoc.inc +include $(TOPDIR)/build/Makefile.inc + +osmomsc-usermanual.pdf: chapters/*.adoc generated/docbook_vty.xml + +clean: + -rm -rf $(cleanfiles) + -rm osmomsc-usermanual__*.svg + -rm osmomsc-usermanual__*.png + -rm osmomsc-usermanual.check + +generated/docbook_vty.xml: osmomsc-vty-reference.xml vty/*xml ../common/vty_additions.xml ../vty_reference.xsl + $(call command,xsltproc -o generated/combined1.xml \ + --stringparam with $(PWD)/../common/vty_additions.xml \ + $(MERGE_DOC) vty/msc_vty_reference.xml, \ + XSLTPROC,Merging Common VTY) + $(call command,xsltproc -o generated/combined2.xml \ + --stringparam with $(PWD)/../common/bsc_vty_additions.xml \ + $(MERGE_DOC) generated/combined1.xml, \ + XSLTPROC,Merging Common BSC VTY) + $(call command,xsltproc -o generated/combined3.xml \ + --stringparam with $(PWD)/vty/msc_vty_additions.xml \ + $(MERGE_DOC) generated/combined2.xml, \ + XSLTPROC,Merging MSC VTY) + $(call command,xsltproc ../vty_reference.xsl generated/combined3.xml > generated/docbook_vty.xml, \ + XSLTPROC,Converting MSC VTY to DocBook) diff --git a/OsmoMSC/chapters/control.adoc b/OsmoMSC/chapters/control.adoc new file mode 100644 index 0000000..af03be7 --- /dev/null +++ b/OsmoMSC/chapters/control.adoc @@ -0,0 +1,31 @@ +[[control]] +== Control interface + +The actual protocol is described in <>, the variables common +to all programs using it are described in <>. This section +describes the CTRL interface variables specific to OsmoMSC. + +.Variables available on OsmoMSC's Control interface +[options="header",width="100%",cols="20%,5%,5%,50%,20%"] +|=== +|Name|Access|Trap|Value|Comment +|subscriber-list-active-v1|RO|No||Return list of active subscribers. +|=== + +=== subscriber-list-active-v1 + +Return a list of subscribers that are successfully attached (including full +successful authentication and ciphering if those are enabled). + +The reply comprises of one subscriber per line, of the format + +---- +,\n[,\n[...]] +---- + +For example: + +---- +901700000015252,22801 +901700000015253,22802 +---- diff --git a/OsmoMSC/chapters/mncc.adoc b/OsmoMSC/chapters/mncc.adoc new file mode 100644 index 0000000..6ea7e72 --- /dev/null +++ b/OsmoMSC/chapters/mncc.adoc @@ -0,0 +1,206 @@ +[[mncc]] +== MNCC for external Call Control + +The 3GPP GSM specifications define an interface point (service access +point) inside the MSC between the call-control part and the rest of the +system. This service access point is called the MNCC-SAP. It is +described in _3GPP TS 24.007_ <<3gpp-ts-24-007>> Chapter 7.1. + +However, like for all internal interfaces, 3GPP does not give any +specific encoding for the primitives passed at this SAP. + +The MNCC protocol of OsmoMSC has been created by the Osmocom community +and allows to control the call handling and audio processing by an +external application. The interface is currently exposed using Unix +Domain Sockets. The protocol is defined in the `mncc.h` header file. + +OsmoMSC can run in two different modes: + +. with internal MNCC handler +. with external MNCC handler + +=== Internal MNCC handler + +When the internal MNCC handler is enabled, OsmoMSC will switch voice +calls between GSM subscribers internally and automatically based on +the subscribers __extension__ number. No external software is required. + +NOTE: Internal MNCC is the default behavior. + +==== Internal MNCC Configuration + +The internal MNCC handler offers some configuration parameters under the +`mncc-int` VTY configuration node. + +===== `default-codec tch-f (fr|efr|amr)` + +Using this command, you can configure the default voice codec to be used +by voice calls on TCH/F channels. + +===== `default-codec tch-h (hr|amr)` + +Using this command, you can configure the default voice codec to be used +by voice calls on TCH/H channels. + +=== External MNCC handler + +When the external MNCC handler is enabled, OsmoMSC will not perform any +internal call switching, but delegate all call-control handling towards +the external MNCC program connected via the MNCC socket. + +If you intend to operate OsmoMSC with external MNCC handler, you have +to start it with the `-m` or `--mncc-sock` command line option. + +At the time of this writing, the only external application implementing +the MNCC interface compatible with the OsmoMSC MNCC socket was `lcr`, +the Linux Call Router. + +=== MNCC protocol description + +The protocol follows the primitives specified in 3GPP TS 04.07 Chapter +7.1. The encoding of the primitives is provided in the `openbsc/mncc.h` +header file, which uses some common definitions from +`osmocom/gsm/mncc.h` (part of libosmocore.git). + +However, OsmoMSC MNCC specifies a number of additional primitives +beyond those listed in the 3GPP specification. + +The different calls in the network are distinguished by their callref +(call reference), which is a unique unsigned 32bit integer. + +==== MNCC_HOLD_IND + +Direction: MSC -> Handler + +A 'CC HOLD' message was received from the MS. + +==== MNCC_HOLD_CNF + +Direction: Handler -> MSC + +Acknowledge a previously-received 'CC HOLD' message, causes the +transmission of a 'CC HOLD ACK' message to the MS. + +==== MNCC_HOLD_REJ + +Direction: Handler -> MSC + +Reject a previously-received 'CC HOLD' message, causes the +transmission of a 'CC HOLD REJ' message to the MS. + +==== MNCC_RETRIEVE_IND + +Direction: MSC -> Handler + +A 'CC RETRIEVE' message was received from the MS. + +==== MNCC_RETRIEVE_CNF + +Direction: Handler -> MSC + +Acknowledge a previously-received 'CC RETRIEVE' message, causes the +transmission of a 'CC RETRIEVE ACK' message to the MS. + + +==== MNCC_RETRIEVE_REJ + +Direction: Handler -> MSC + +Reject a previously-received 'CC RETRIEVE' message, causes the +transmission of a 'CC RETRIEVE REJ' message to the MS. + +==== MNCC_USERINFO_REQ + +Direction: MSC -> Handler + +Causes a 'CC USER INFO' message to be sent to the MS. + +==== MNCC_USERINFO_IND + +Direction: MSC -> Handler + +Indicates that a 'CC USER-USER' message has been received from the MS. + +==== MNCC_BRIDGE + +Direction: Handler -> MSC + +Requests that the TCH (voice) channels of two calls shall be +inter-connected. This is the old-fashioned way of using MNCC, +primarily required for circuit-switched BTSs whose TRAU frames are +received via an E1 interface card on the MSC machine. + +==== MNCC_FRAME_RECV + +Direction: Handler -> MSC + +Enable the forwarding of TCHF voice frames via the MNCC interface in +MSC->Handler direction for the specified call. + +==== MNCC_FRAME_DROP + +Direction: Handler -> MSC + +Disable the forwarding of TCHF voice frames via the MNCC interface in +MSC->Handler direction for the specified call. + +==== MNCC_LCHAN_MODIFY + +Direction: Handler -> MSC + +Modify the current dedicated radio channel from signalling to voice, or +if it is a signalling-only channel (SDCCH), assign a TCH to the MS. + +==== MNCC_RTP_CREATE + +Direction: Handler -> MSC + +Create a RTP socket for this call at the BTS/TRAU that serves this BTS. + +==== MNCC_RTP_CONNECT + +Direction: Handler -> MSC + +Connect the RTP socket of this call to the given remote IP address and +port. + +==== MNCC_RTP_FREE + +Direction: Handler -> MSC + +Release a RTP connection for one given call. + +==== GSM_TCHF_FRAME + +Direction: both + +Transfer the payload of a GSM Full-Rate (FR) voice frame between the +MSC and an external MNCC handler. + +==== GSM_TCHF_FRAME_EFR + +Direction: both + +Transfer the payload of a GSM Enhanced Full-Rate (EFR) voice frame +between the MSC and an external MNCC handler. + +==== GSM_TCHH_FRAME + +Direction: both + +Transfer the payload of a GSM Half-Rate (HR) voice frame between the +MSC and an external MNCC handler. + +==== GSM_TCH_FRAE_AMR + +Direction: both + +Transfer the payload of a GSM Adaptive-Multi-Rate (AMR) voice frame +between the MSC and an external MNCC handler. + +==== GSM_BAD_FRAME + +Direction: MSC -> Handler + +Indicate that no valid voice frame, but a 'bad frame' was received over +the radio link from the MS. diff --git a/OsmoMSC/chapters/net.adoc b/OsmoMSC/chapters/net.adoc new file mode 100644 index 0000000..94a30be --- /dev/null +++ b/OsmoMSC/chapters/net.adoc @@ -0,0 +1,153 @@ +[[net]] +== Configuring the Core Network + +The core network parameters are configured by the config file (as in `osmo-msc +-c osmo-msc.cfg`). The config file is parsed by the VTY, which is also +available via telnet in the running `osmo-msc` instance. Be aware that even +though you may be able to change these parameters without restarting +`osmo-msc`, some may not take immediate effect, and it is safest to use the +config file to have these parameters set at startup time. + +The core network parameters are found in the `config` / `network`. + +A full reference to the available commands can be found in the _OsmoMSC VTY +reference manual_ <>. This section describes only the most +commonly used settings. + +Here is an overview of the config items, described in more detail below: + +---- +network + network country code 262 + mobile network code 89 + mm info 1 + short name OsmoMSC + long name OsmoMSC + authentication required + encryption a5 3 +---- + +[TIP] +==== +Use the telnet VTY interface to query the current configuration of a running +`osmo-msc` process: + +---- +$ telnet localhost 4254 +OsmoMSC> enable +OsmoMSC# show running-config +---- + +Some parameters may be changed without restarting `osmo-msc`. To reach the +`network` node, enter: + +---- +OsmoMSC> enable +OsmoMSC# configure terminal +OsmoMSC(config)# network +OsmoMSC(config-net)# short name Example-Name +OsmoMSC(config-net)# exit +OsmoMSC(config)# +---- + +The telnet VTY features tab-completion as well as context sensitive help shown +when entering a `?` question mark. + +You can always use the `list` VTY command or enter `?` on the blank prompt to +get a list of all possible commands at the current node. +==== + + +=== MCC/MNC + +The key identities of every GSM PLMN is the Mobile Country Code and the Mobile +Network Code. They are identical over the entire network. In most cases, the +MCC/MNC will be allocated to the operator by the respective local regulatory +authority. For example, to set the MCC/MNC of 262-89, have this in your +osmo-msc.cfg: + +---- +network + network country code 262 + mobile network code 89 +---- + + +=== Configuring MM INFO + +The _MM INFO_ procedure can be used after a successful _LOCATION UPDATE_ in +order to transmit the human-readable network name as well as local time zone +information to the MS. By default, _MM INFO_ is not active, i.e. `0`. Set to `1` +to activate this feature: + +---- +network + mm info 1 + short name OsmoMSC + long name OsmoMSC +---- + +[NOTE] +==== +Not all phones support the MM INFO procedure. If a phone is not +factory-programmed to contain the name for your MCC/MNC, it will likely only +provide a numeric display of the network name, such as _262-89_, or show the +country code transformed into a letter, such as _D 89_. +==== + +The time information transmitted is determined by the local system time of the +operating system on which OsmoMSC is running. + + +=== Authentication + +Authorized subscribers must be entered in the HLR database. If authentication +tokens (such as KI for 2G, or K and OP/OPC for UMTS) are present in the HLR, +OsmoMSC will only attach a subscriber after successful authentication. + +If no authentication keys are present in the HLR for a given subscriber, +OsmoMSC will attach the subscriber _without_ authentication. You can reject +subscribers that lack authentication info in the HLR with this setting: + +---- +network + authentication required +---- + +=== Ciphering + +To enable ciphering on the radio link, authentication must take place first: +the Kc resulting from authentication is the key used for ciphering. Hence, all +subscribers must have authentication tokens available in the HLR for ciphering. + +The MS, BTS and MSC must agree on a ciphering algorithm to use. + +- The MS sends its supported ciphering algorithms via Classmark IEs during + Location Updating. +- Typically the BSC needs to know which A5 ciphers are supported by connected + BTSes. +- Finally, OsmoMSC may impose that specific A5 ciphers shall not be considered. + +It is the responsibility of the BSC to then pick an A5 cipher that satisfies +all requirements. + +- In OsmoMSC, A5/0 means that ciphering is turned off. ++ +---- +network + encryption a5 0 +---- + +- A5/1 and A5/3 are currently supported by Osmocom. ++ +---- +network + encryption a5 3 +---- + +- Never use A5/2: it is an "export grade cipher" and has been deprecated for + its low ciphering strength. + +NOTE: At the time of writing, OsmoMSC supports setting only a single A5 cipher, +while it should be able to allow a set of ciphers. This is subject to ongoing +development. diff --git a/OsmoMSC/chapters/overview.adoc b/OsmoMSC/chapters/overview.adoc new file mode 100644 index 0000000..4aa25df --- /dev/null +++ b/OsmoMSC/chapters/overview.adoc @@ -0,0 +1,123 @@ +[[overview]] +== Overview + +This manual should help you getting started with OsmoMSC. It will cover +aspects of configuring and running the OsmoMSC. + +[[intro_overview]] +=== About OsmoMSC + +OsmoMSC is the Osmocom implementation of a Mobile Switching Center (MSC) for 2G +and 3G GSM and UMTS mobile networks. Its interfaces are: + +- GSUP towards OsmoHLR (or a MAP proxy); +- A over IP towards a BSC (e.g. OsmoBSC); +- IuCS towards an RNC or HNB-GW (e.g. OsmoHNBGW) for 3G voice; +- MNCC (Mobile Network Call Control derived from GSM TS 04.07); +- SMPP 3.4 (Short Message Peer-to-Peer); +- The Osmocom typical telnet VTY and CTRL interfaces. + +OsmoMSC originated from the OpenBSC project, which started as a minimalistic +all-in-one implementation of the GSM Network. In 2017, OpenBSC had reached +maturity and diversity (including M3UA SIGTRAN and 3G support in the form of +IuCS and IuPS interfaces) that naturally lead to a separation of the all-in-one +approach to fully independent separate programs as in typical GSM networks. +OsmoMSC was one of the parts split off from the old openbsc.git. Before, it was +the libmsc part of the old OsmoNITB. Since a true __A__ interface and IuCS for +3G support is available, OsmoMSC exists only as a separate standalone entity. + +Key differences of the new OsmoMSC compared to the old OsmoNITB are: + +- The complete VLR implementation that communicates with the separate HLR + (OsmoHLR) for subscriber management. In contrast to the OsmoNITB, this is now + fully asynchronous and allows using centralized subscriber management for + both circuit-switched and packet-switched domains (i.e. one OsmoHLR for both + OsmoMSC and OsmoSGSN), as well as full UMTS AKA (Authentication and Key + Agreement), i.e. Milenage authentication. + +- Addition of a true __A__ interface for 2G voice services. Previously, OsmoBSC + had an SCCPlite based __A__ interface towards 3rd party MSC implementations. + OsmoMSC features a true M3UA/SCCP __A__ interface, which allows running a now + separate OsmoBSC against an Osmocom based MSC implementation. The new + M3UA/SCCP SIGTRAN is implemented in libosmo-sccp, which is used by OsmoMSC + and OsmoBSC, among other projects, to establish a link via an STP (e.g. + OsmoSTP). + +- Addition of an __IuCS__ interface to allow operating 3G voice services. + +Find OsmoMSC issue tracker and wiki online at + +- https://osmocom.org/projects/osmomsc +- https://osmocom.org/projects/osmomsc/wiki + + +[[fig-gsm]] +.Typical GSM network architecture used with OsmoMSC +[graphviz] +---- +digraph G { + rankdir=LR; + MS0 [label="MS"] + MS1 [label="MS"] + MS2 [label="MS"] + MS3 [label="MS"] + UE0 [label="UE"] + UE1 [label="UE"] + BTS0 [label="BTS"] + BTS1 [label="BTS"] + STP [label="STP\n(SCCP routing)"] + HLR [label="HLR+AUC+EIR"] + HNB [label="RNC or hNodeB"] + MGW + MS0->BTS0 [label="Um"] + MS1->BTS0 [label="Um"] + MS2->BTS1 [label="Um"] + MS3->BTS1 [label="Um"] + UE0->HNB + UE1->HNB + BTS0->BSC [label="Abis"] + BTS1->BSC [label="Abis"] + BSC->STP [label="A/M3UA"] + STP->MSC [label="A/M3UA"] + STP->MSC [label="IuCS/M3UA"] + VLR->HLR [label="GSUP"] + HNB->HNBGW [label="Iuh"] + HNBGW->STP [label="IuCS/M3UA"] + MSC->MGW [label="MGCP"] + BTS0->MGW [label="RTP"] + BTS1->MGW [label="RTP"] + subgraph cluster_msc { + label = "OsmoMSC"; + MSC->SMSC; + MSC->VLR + } +} +---- + + +=== Software Components + +This is a brief description of OsmoMSC's internal software components. + +==== SMSC + +A minimal store-and-forward server for SMS, supporting both MO and MT +SMS service, as well as multi-part messages. + +The built-in SMSC also supports an external SMSC interface. For more +information, see <>. + +==== MSC + +The MSC component implements the mobility management (MM) functions of the TS +04.08 and delegates to SMSC for SMS message handling and the VLR for subscriber +management. + +Furthermore, it can handle TS 04.08 Call Control (CC), either by use of +an internal MNCC handler, or by use of an external MNCC agent. For more +information see <>. + +==== VLR + +A fully featured Visitor Location Register handles the subscriber management +and authentication, and interfaces via GSUP to the external HLR. diff --git a/OsmoMSC/chapters/running.adoc b/OsmoMSC/chapters/running.adoc new file mode 100644 index 0000000..d56e8be --- /dev/null +++ b/OsmoMSC/chapters/running.adoc @@ -0,0 +1,138 @@ +== Running OsmoMSC + +The OsmoMSC executable (`osmo-msc`) offers the following command-line +arguments: + +=== SYNOPSIS + +*osmo-msc* [-h|-V] [-d 'DBGMASK'] [-D] [-c 'CONFIGFILE'] [-s] [-T] [-e 'LOGLEVEL'] [-l 'DATABASE'] [-M 'SOCKETPATH'] [-C] + +=== OPTIONS + +*-h, --help*:: + Print a short help message about the supported options +*-V, --version*:: + Print the compile-time version number of the OsmoBTS program +*-d, --debug 'DBGMASK','DBGLEVELS'*:: + Set the log subsystems and levels for logging to stderr. This + has mostly been superseded by VTY-based logging configuration, + see <> for further information. +*-D, --daemonize*:: + Fork the process as a daemon into background. +*-c, --config-file 'CONFIGFILE'*:: + Specify the file and path name of the configuration file to be + used. If none is specified, use `openbsc.cfg` in the current + working directory. +*-s, --disable-color*:: + Disable colors for logging to stderr. This has mostly been + deprecated by VTY based logging configuration, see <> + for more information. +*-T, --timestamp*:: + Enable time-stamping of log messages to stderr. This has mostly + been deprecated by VTY based logging configuration, see + <> for more information. +*-e, --log-level 'LOGLEVEL'*:: + Set the global log level for logging to stderr. This has mostly + been deprecated by VTY based logging configuration, see + <> for more information. +*-l, --database 'DATABASE'*:: + Specify the file name of the SQLite3 database to use as HLR/AUC + storage +*-M, --mncc-sock-path*:: + Enable the MNCC socket for an external MNCC handler. See + <> for further information. +*-m, --mncc-sock*:: + Same as option -M (deprecated). +*-C, --no-dbcounter*:: + Disable the regular periodic synchronization of statistics + counters to the database. + + +=== Multiple instances + +Running multiple instances of `osmo-msc` is possible if all interfaces (VTY, +CTRL) are separated using the appropriate configuration options. The IP based +interfaces are binding to local host by default. In order to separate the +processes, the user has to bind those services to specific but different IP +addresses. + +The VTY and the Control interface can be bound to IP addresses from the loopback +address range. + +.Example: Binding VTY and control interface to a specific IP address +---- +line vty + bind 127.0.0.2 +ctrl + bind 127.0.0.2 +---- + +The M3UA/SCCP links (__A__ to BSCs and/or __IuCS__ to HNB-GWs) are typically +established by OsmoMSC contacting an OsmoSTP instance; also the GSUP link to +the HLR is established by OsmoMSC acting as the client. For all of these links, +OsmoMSC thus does not listen/bind do a specific interface and will not +encounter conflicts for multiple instances running on the same interface. + + +=== Configure primary links + +==== Configure M3UA/SCCP to accept __A__ and __IuCS__ links + +OsmoMSC will contact an STP instance to establish an M3UA/SCCP link. BSC and +HNBGW will then reach the MSC via this link. By default, an STP instance is +assumed to listen on the default M3UA port (2905) on the local host. + +Establishing an M3UA/SCCP link towards an STP instance not on the local host is +configured as follows: + +---- +cs7 instance 0 + asp asp-clnt-OsmoMSC-A-Iu 2905 0 m3ua + ! IP address of the remote STP: + remote-ip 10.23.24.1 +---- + +Note that __A__ and __IuCS__ may use different SCCP instances: + +---- +cs7 instance 0 + asp asp-clnt-OsmoMSC-A 2905 0 m3ua + remote-ip 10.23.42.1 +cs7 instance 1 + asp asp-clnt-OsmoMSC-Iu 2905 0 m3ua + remote-ip 10.23.42.2 +msc + cs7-instance-a 0 + cs7-instance-iu 1 +---- + +A full configuration needs an `asp` on an `as` -- an Application Server Process +running on an Application Server -- as well as a local point code. The SCCP VTY +automatically creates those parts that are missing, by assuming sane defaults. + +A complete configuration would look like this: + +---- +cs7 instance 0 + point-code 0.23.1 + asp asp-clnt-OsmoMSC-A-Iu 2905 0 m3ua + remote-ip 127.0.0.1 + as as-clnt-OsmoMSC-A-Iu m3ua + asp asp-clnt-OsmoMSC-A-Iu + routing-key 0 0.23.1 +---- + +==== Configure GSUP to reach the HLR + +OsmoMSC will assume a GSUP server (OsmoHLR) to run on the local host and the +default GSUP port (4222). Contacting an HLR at a different IP address can be +configured as follows: + +.Example: Contacting a remote HLR via GSUP +---- +hlr + ! IP address of the remote HLR: + remote-ip 10.23.42.1 + ! default port is 4222, optionally configurable by: + remote-port 1234 +---- diff --git a/OsmoMSC/chapters/smpp.adoc b/OsmoMSC/chapters/smpp.adoc new file mode 100644 index 0000000..fab42b5 --- /dev/null +++ b/OsmoMSC/chapters/smpp.adoc @@ -0,0 +1,146 @@ +[[smpp]] +== Short Message Peer to Peer (SMPP) + +In OsmoMSC, the _Short Message Peer to Peer_ (SMPP) Protocol <> +interface allows sending MT-SMS to an attached subscriber or receiving unrouted +MO-SMS. OsmoMSC implements version 3.4 of the protocol. + +NOTE: `osmo-msc` must have been compiled with the `--enable-smpp` configure +option to offer the SMPP interface. + +Multiple ESMEs (External SMS Entities) may interact with an SMSC (SMS Service +Center) via the SMPP protocol. Each entity is identified by its System Id, a +character string which is configured by the system administrator. + +OsmoMSC implements the SMSC side of SMPP and acts as a TCP server accepting +incoming connections from ESME client programs. + +Each ESME identifies itself to the SMSC with its system-id and an +optional shared password. + + +=== Global SMPP configuration + +Configure OsmoMSC's SMPP behavior at the top-level `smpp` VTY node, for +example: + +---- +smpp + local-tcp-ip 10.23.42.1 2775 + system-id osmomsc123 + policy closed + no smpp-first +---- + +Use the `local-tcp-ip` command to define the TCP IP and port at which the +OsmoMSC internal SMSC should listen for incoming SMPP connections. The default +is to listen on all IPs (0.0.0.0) and the default port assigned to SMPP (2775). + +Use the `system-id` command to define the System ID of the SMSC. + +Use the `policy` parameter to define whether only explicitly configured +ESMEs are permitted to access the SMSC (`closed`), or whether any +ESME should be accepted (`accept-all`). + +Use the `smpp-first` command to define if SMPP routes have higher precedence +than MSISDNs contained in the HLR, or `no smpp-first` if only MSISDNs not +present in the HLR should be considered for routing to SMPP. + + +[[esme]] +=== ESME configuration + +Under the `smpp` vty node, you can add any number of `esme` nodes, one +for each ESME that you wish to configure. For example: + +---- +smpp + policy closed + no smpp-first + esme example1 + password s3cr3t + default-route + deliver-src-imsi + osmocom-extensions + esme example2 + password p4ssw0rd + deliver-src-imsi + osmocom-extensions + route prefix national isdn 2342 +---- + +Use the `esme NAME` command (where NAME corresponds to the system-id of +the ESME to be configured) under the SMPP vty node to enter the +configuration node for this given ESME. + +Use the `password` command to specify the password (if any) for the +ESME. + +Use the `default-route` command to indicate that any MO-SMS without a +more specific route should be routed to this ESME. + +Use the `deliver-src-imsi` command to indicate that the SMPP DELIVER +messages for MO SMS and the SMPP ALERT should state the IMSI (rather +than the MSISDN) as source address. + +Use the `osmocom-extensions` command to request that Osmocom specific +extension TLVs shall be included in the SMPP PDUs. Those extensions +include the ARFCN of the cell, the L1 transmit power of the MS, the +timing advance, the uplink and dwnlink RxLev and RxQual, as well as the +IMEI of the terminal at the time of generating the SMPP DELIVER PDU. + +Use the `dcs-transparent` command to transparently pass the DCS value +from the SMS Layer3 protocols to SMPP, instead of converting them to the +SMPP-specific values. + +Use the `route prefix` command to specify a route towards this ESME. +Using routes, you specify which destination MSISDNs should be routed +towards your ESME. + + +=== Osmocom SMPP protocol extensions + +Osmocom has implemented some extensions to the SMPP v3.4 protocol. + +These extensions can be enabled using the `osmocom-extensions` VTY +command at `esme` level, see <>. + +The TLV definitions can be found in the +`` header file provided by +libosmocore. + +==== RF channel measuremets + +When the Osmocom SMPP extensions are enabled, we add the following +TLVs to each SMPP DELIVER PDU: + +[options="header", cols="3,1,1,5"] +|=== +| TLV | IEI | Length (Octets) | Purpose +| TLVID_osmo_arfcn | 0x2300 | 2 | GSM ARFCN of the radio interface +| TLVID_osmo_ta | 0x2301 | 1 | Timing Advance on the radio interface +| TLVID_osmo_ms_l1_txpwr | 0x2307 | 1 | Transmit Power of the MS in uplink direction +| TLVID_osmo_rxlev_ul | 0x2302 | 2 | Uplink receive level as measured by BTS in dBm (int16_t) +| TLVID_osmo_rxqual_ul | 0x2303 | 1 | Uplink RxQual value as measured by BTS +| TLVID_osmo_rxlev_dl | 0x2304 | 2 | Downlink receive level as measured by MS in dBm (int16_t) +| TLVID_osmo_rxqual_dl | 0x2305 | 1 | Downlink RxQual value as measured by MS +|=== + +All of the above values reflect the *last measurement report* as +recieved vi A-bis RSL from the BTS. It is thus a snapshot value (of +the average within one 480ms SACCH period), and not an average over +all the SACCH periods during which the channel was open or the SMS was +received. Not all measurement reports contain all the values. So you +might not get an TLVID_osmo_rxlev_dl IE, as that particular uplink +frame might habe benn lost for the given snapshot we report. + +==== Equipment IMEI + +If we know the IMEI of the subscribers phone, we add the following TLV +to each SMPP DELIVER PDU: + +[options="header", cols="3,1,1,5"] +|=== +| TLV | IEI | Length | Purpose +| TLVID_osmo_imei | 0x2306 | variable | IMEI of the subscibers phone (ME) +|=== diff --git a/OsmoMSC/osmomsc-usermanual-docinfo.xml b/OsmoMSC/osmomsc-usermanual-docinfo.xml new file mode 100644 index 0000000..d99bba7 --- /dev/null +++ b/OsmoMSC/osmomsc-usermanual-docinfo.xml @@ -0,0 +1,47 @@ + + + 1 + September 18th, 2017 + NH + + Initial version; based on OsmoNITB manual version 2. + + + + + + + Neels + Hofmeyr + nhofmeyr@sysmocom.de + NH + + sysmocom + sysmocom - s.f.m.c. GmbH + Senior Developer + + + + + + 2017 + sysmocom - s.f.m.c. GmbH + + + + + Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU Free Documentation License, + Version 1.3 or any later version published by the Free Software + Foundation; with the Invariant Sections being just 'Foreword', + 'Acknowledgements' and 'Preface', with no Front-Cover Texts, + and no Back-Cover Texts. A copy of the license is included in + the section entitled "GNU Free Documentation License". + + + The Asciidoc source code of this manual can be found at + + http://git.osmocom.org/osmo-gsm-manuals/ + + + diff --git a/OsmoMSC/osmomsc-usermanual.adoc b/OsmoMSC/osmomsc-usermanual.adoc new file mode 100644 index 0000000..d59ac7c --- /dev/null +++ b/OsmoMSC/osmomsc-usermanual.adoc @@ -0,0 +1,39 @@ +:gfdl-enabled: + +OsmoMSC User Manual +==================== +Neels Hofmeyr + + +include::../common/chapters/preface.adoc[] + +include::chapters/overview.adoc[] + +include::chapters/running.adoc[] + +include::chapters/control.adoc[] + +include::../common/chapters/vty.adoc[] + +include::../common/chapters/logging.adoc[] + +include::chapters/net.adoc[] + +include::chapters/smpp.adoc[] + +include::chapters/mncc.adoc[] + +include::../common/chapters/control_if.adoc[] + +include::../common/chapters/cell-broadcast.adoc[] + +include::../common/chapters/abis.adoc[] + +include::../common/chapters/port_numbers.adoc[] + +include::../common/chapters/bibliography.adoc[] + +include::../common/chapters/glossary.adoc[] + +include::../common/chapters/gfdl.adoc[] + diff --git a/OsmoMSC/osmomsc-vty-reference.xml b/OsmoMSC/osmomsc-vty-reference.xml new file mode 100644 index 0000000..a954b84 --- /dev/null +++ b/OsmoMSC/osmomsc-vty-reference.xml @@ -0,0 +1,38 @@ + + + + +]> + + + + + + v1 + 18th September 2017 + nh + Initial + + + + OsmoMSC VTY Reference + + + 2017 + + + + This work is copyright by sysmocom - s.f.m.c. GmbH. All rights reserved. + + + + + + &chapter-vty; + + diff --git a/OsmoMSC/vty/msc_vty_additions.xml b/OsmoMSC/vty/msc_vty_additions.xml new file mode 100644 index 0000000..0d473bd --- /dev/null +++ b/OsmoMSC/vty/msc_vty_additions.xml @@ -0,0 +1,24 @@ + + + + MNCC Internal Configuration + This node allows to configure the default codecs for + the internal call control handling. + + + + SMPP Configuration + This node allows to configure the SMPP interface + for interfacing with external SMS applications. This section + contains generic/common SMPP related configuration, and no + per-ESME specific parameters. + + + + ESME Configuration + This node allows to configure one particular SMPP + ESME, which is an External SMS Entity such as a SMS based + application server. You can define any number of ESME within + the SMPP node of the OsmoNITB VTY. + + diff --git a/OsmoMSC/vty/msc_vty_reference.xml b/OsmoMSC/vty/msc_vty_reference.xml new file mode 100644 index 0000000..b7311ab --- /dev/null +++ b/OsmoMSC/vty/msc_vty_reference.xml @@ -0,0 +1,3019 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file -- cgit v1.2.3