add OsmoMSC manual
Change-Id: I9ecff2837fbf5fdc19675a726f6d70c21eb178ee
This commit is contained in:
parent
2601159326
commit
2c3b99e62a
4
Makefile
4
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; }
|
||||
|
|
|
@ -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)
|
|
@ -0,0 +1,31 @@
|
|||
[[control]]
|
||||
== Control interface
|
||||
|
||||
The actual protocol is described in <<common-control-if>>, the variables common
|
||||
to all programs using it are described in <<ctrl_common_vars>>. 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
|
||||
|
||||
----
|
||||
<IMSI>,<MSISDN>\n[<IMSI>,<MSISDN>\n[...]]
|
||||
----
|
||||
|
||||
For example:
|
||||
|
||||
----
|
||||
901700000015252,22801
|
||||
901700000015253,22802
|
||||
----
|
|
@ -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.
|
|
@ -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_ <<vty-ref-osmomsc>>. 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.
|
|
@ -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 <<smpp>>.
|
||||
|
||||
==== 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 <<mncc>>.
|
||||
|
||||
==== VLR
|
||||
|
||||
A fully featured Visitor Location Register handles the subscriber management
|
||||
and authentication, and interfaces via GSUP to the external HLR.
|
|
@ -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 <<logging>> 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 <<logging>>
|
||||
for more information.
|
||||
*-T, --timestamp*::
|
||||
Enable time-stamping of log messages to stderr. This has mostly
|
||||
been deprecated by VTY based logging configuration, see
|
||||
<<logging>> 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
|
||||
<<logging>> 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
|
||||
<<mncc>> 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
|
||||
----
|
|
@ -0,0 +1,146 @@
|
|||
[[smpp]]
|
||||
== Short Message Peer to Peer (SMPP)
|
||||
|
||||
In OsmoMSC, the _Short Message Peer to Peer_ (SMPP) Protocol <<smpp-34>>
|
||||
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 <<esme>>.
|
||||
|
||||
The TLV definitions can be found in the
|
||||
`<osmocom/gsm/protocol/smpp34_osmocom.h>` 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)
|
||||
|===
|
|
@ -0,0 +1,47 @@
|
|||
<revhistory>
|
||||
<revision>
|
||||
<revnumber>1</revnumber>
|
||||
<date>September 18th, 2017</date>
|
||||
<authorinitials>NH</authorinitials>
|
||||
<revremark>
|
||||
Initial version; based on OsmoNITB manual version 2.
|
||||
</revremark>
|
||||
</revision>
|
||||
</revhistory>
|
||||
|
||||
<authorgroup>
|
||||
<author>
|
||||
<firstname>Neels</firstname>
|
||||
<surname>Hofmeyr</surname>
|
||||
<email>nhofmeyr@sysmocom.de</email>
|
||||
<authorinitials>NH</authorinitials>
|
||||
<affiliation>
|
||||
<shortaffil>sysmocom</shortaffil>
|
||||
<orgname>sysmocom - s.f.m.c. GmbH</orgname>
|
||||
<jobtitle>Senior Developer</jobtitle>
|
||||
</affiliation>
|
||||
</author>
|
||||
</authorgroup>
|
||||
|
||||
<copyright>
|
||||
<year>2017</year>
|
||||
<holder>sysmocom - s.f.m.c. GmbH</holder>
|
||||
</copyright>
|
||||
|
||||
<legalnotice>
|
||||
<para>
|
||||
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".
|
||||
</para>
|
||||
<para>
|
||||
The Asciidoc source code of this manual can be found at
|
||||
<ulink url="http://git.osmocom.org/osmo-gsm-manuals/">
|
||||
http://git.osmocom.org/osmo-gsm-manuals/
|
||||
</ulink>
|
||||
</para>
|
||||
</legalnotice>
|
|
@ -0,0 +1,39 @@
|
|||
:gfdl-enabled:
|
||||
|
||||
OsmoMSC User Manual
|
||||
====================
|
||||
Neels Hofmeyr <nhofmeyr@sysmocom.de>
|
||||
|
||||
|
||||
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[]
|
||||
|
|
@ -0,0 +1,38 @@
|
|||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!--
|
||||
ex:ts=2:sw=42sts=2:et
|
||||
-*- tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*-
|
||||
-->
|
||||
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V5.0//EN"
|
||||
"http://www.docbook.org/xml/5.0/dtd/docbook.dtd" [
|
||||
<!ENTITY chapter-vty SYSTEM "../common/chapters/vty.xml" >
|
||||
<!ENTITY sections-vty SYSTEM "generated/docbook_vty.xml" >
|
||||
]>
|
||||
|
||||
<book>
|
||||
<info>
|
||||
<revhistory>
|
||||
<revision>
|
||||
<revnumber>v1</revnumber>
|
||||
<date>18th September 2017</date>
|
||||
<authorinitials>nh</authorinitials>
|
||||
<revremark>Initial</revremark>
|
||||
</revision>
|
||||
</revhistory>
|
||||
|
||||
<title>OsmoMSC VTY Reference</title>
|
||||
|
||||
<copyright>
|
||||
<year>2017</year>
|
||||
</copyright>
|
||||
|
||||
<legalnotice>
|
||||
<para>This work is copyright by <orgname>sysmocom - s.f.m.c. GmbH</orgname>. All rights reserved.
|
||||
</para>
|
||||
</legalnotice>
|
||||
</info>
|
||||
|
||||
<!-- Main chapters-->
|
||||
&chapter-vty;
|
||||
</book>
|
||||
|
|
@ -0,0 +1,24 @@
|
|||
<vtydoc xmlns='urn:osmocom:xml:libosmocore:vty:doc:1.0'>
|
||||
<node id='32'>
|
||||
<child_of nodeid='4' />
|
||||
<name>MNCC Internal Configuration</name>
|
||||
<description>This node allows to configure the default codecs for
|
||||
the internal call control handling.</description>
|
||||
</node>
|
||||
<node id='35'>
|
||||
<child_of nodeid='4' />
|
||||
<name>SMPP Configuration</name>
|
||||
<description>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.</description>
|
||||
</node>
|
||||
<node id='36'>
|
||||
<child_of nodeid='35' />
|
||||
<name>ESME Configuration</name>
|
||||
<description>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.</description>
|
||||
</node>
|
||||
</vtydoc>
|
File diff suppressed because it is too large
Load Diff
Loading…
Reference in New Issue