add OsmoMSC manual

Change-Id: I9ecff2837fbf5fdc19675a726f6d70c21eb178ee
This commit is contained in:
Neels Hofmeyr 2017-09-18 16:19:30 +02:00
parent 2601159326
commit 2c3b99e62a
13 changed files with 4010 additions and 0 deletions

View File

@ -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; }

42
OsmoMSC/Makefile Normal file
View File

@ -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)

View File

@ -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
----

206
OsmoMSC/chapters/mncc.adoc Normal file
View File

@ -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.

153
OsmoMSC/chapters/net.adoc Normal file
View File

@ -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.

View File

@ -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.

View File

@ -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
----

146
OsmoMSC/chapters/smpp.adoc Normal file
View File

@ -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)
|===

View File

@ -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>

View File

@ -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[]

View File

@ -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>

View File

@ -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