add OsmoMSC manual

Add OsmoMSC and OsmoHLR to bibliography (even though the OsmoHLR manual does
not yet exist, a reference to it has been added in OsmoMSC's manual).

Change-Id: I9ecff2837fbf5fdc19675a726f6d70c21eb178ee
This commit is contained in:
Neels Hofmeyr 2017-09-18 16:19:30 +02:00
parent 845031955e
commit 8c8ebb13b6
10 changed files with 3666 additions and 0 deletions

42
doc/manuals/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
----

View File

@ -0,0 +1,154 @@
[[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, see the _OsmoHLR
reference manual_ <<userman-osmohlr>>. 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,127 @@
[[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.
Before it was split off, OsmoMSC originated from libmsc of the old openbsc.git.
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, HLR queries
are fully asynchronous, and the separate HLR allows using centralized
subscriber management for both circuit-switched and packet-switched domains
(i.e. one OsmoHLR for both OsmoMSC and OsmoSGSN).
- VLR and HLR brought full UMTS AKA (Authentication and Key Agreement) support,
i.e. Milenage authentication in both the full 3G variant as well as the
backwards compatible 2G variant.
- 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 SCCP/M3UA _A_ interface, which allows running OsmoBSC
against this Osmocom based MSC implementation. The new SCCP/M3UA SIGTRAN for
the _A_ interface is implemented in libosmo-sccp, which is used by OsmoMSC
and OsmoBSC (and others), to establish a link via an STP (e.g. OsmoSTP).
- Addition of an _IuCS_ interface to allow operating 3G voice services, also
via SCCP/M3UA SIGTRAN, for example connecting via OsmoHNBGW to a 3G small
cell device.
Find the 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/SCCP/M3UA"]
STP->MSC [label="A/SCCP/M3UA"]
STP->MSC [label="IuCS/SCCP/M3UA"]
VLR->HLR [label="GSUP"]
HNB->HNBGW [label="Iuh"]
HNBGW->STP [label="IuCS/SCCP/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,148 @@
== 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 SMS 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, for example:
----
line vty
bind 127.0.0.2
ctrl
bind 127.0.0.2
----
If external SMPP is enabled, you may bind it to a different interface using:
----
smpp
local-tcp-ip 10.23.42.1 2775
----
More on SMPP configuration in <<smpp-config-global>>.
The external MNCC handler is configured by the `--mncc-sock` commandline
argument. Choose a different such socket path for each OsmoMSC instance running
on the same file system. See more in <<mncc-external>>.
For the following links, OsmoMSC acts as a client and does not listen/bind to a
specific interface, and will hence not encounter conflicts for multiple instances
running on the same interface:
- The SCCP/M3UA links are established by OsmoMSC contacting an STP.
- The GSUP link is established by OsmoMSC contacting an HLR.
=== Configure primary links
==== Configure SCCP/M3UA to accept _A_ and _IuCS_ links
OsmoMSC will contact an STP instance to establish an SCCP/M3UA 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 SCCP/M3UA link towards an STP instance not on the local host
can be configured as follows:
----
cs7 instance 0
asp my-OsmoMSC 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, if so desired:
----
cs7 instance 0
asp my-OsmoMSC-A 2905 0 m3ua
remote-ip 10.23.42.1
cs7 instance 1
asp my-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 and routing
configuration. 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 my-OsmoMSC-A-Iu 2905 0 m3ua
remote-ip 127.0.0.1
as my-as-for-OsmoMSC-A-Iu m3ua
asp my-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:
----
hlr
! IP address of the remote HLR:
remote-ip 10.23.42.1
! default port is 4222, optionally configurable by:
remote-port 1234
----

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,36 @@
:gfdl-enabled:
:program-name: OsmoMSC
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::../common/chapters/smpp.adoc[]
include::../common/chapters/mncc.adoc[]
include::../common/chapters/control_if.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