[PATCH] osmo-gsm-manuals[master]: First step towards an OsmoSTP manual

This is merely a historical archive of years 2008-2021, before the migration to mailman3.

A maintained and still updated list archive can be found at https://lists.osmocom.org/hyperkitty/list/gerrit-log@lists.osmocom.org/.

Harald Welte gerrit-no-reply at lists.osmocom.org
Sun Apr 16 01:28:45 UTC 2017


Hello Jenkins Builder,

I'd like you to reexamine a change.  Please visit

    https://gerrit.osmocom.org/2371

to look at the new patch set (#2).

First step towards an OsmoSTP manual

Change-Id: I450bfac7444ac9cb7f50c086d87cf7157c2e2a31
---
M Makefile
A OsmoSTP/Makefile
A OsmoSTP/osmostp-usermanual-docinfo.xml
A OsmoSTP/osmostp-usermanual.adoc
A OsmoSTP/osmostp-vty-reference.xml
A OsmoSTP/vty/stp_vty_reference.xml
M common/chapters/bibliography.adoc
M common/chapters/glossary.adoc
A common/chapters/sigtran-osmocom.adoc
A common/chapters/sigtran-simple-2g.dot
A common/chapters/sigtran-simple-3g.dot
A common/chapters/sigtran.adoc
12 files changed, 1,019 insertions(+), 0 deletions(-)


  git pull ssh://gerrit.osmocom.org:29418/osmo-gsm-manuals refs/changes/71/2371/2

diff --git a/Makefile b/Makefile
index 035595c..ed0c894 100644
--- a/Makefile
+++ b/Makefile
@@ -6,6 +6,7 @@
 	cd OsmoSGSN; $(MAKE)
 	cd OsmoNAT; $(MAKE)
 	cd OsmoPCU; $(MAKE)
+	cd OsmoSTP; $(MAKE)
 
 clean:
 	cd OsmoBTS; $(MAKE) clean
@@ -15,6 +16,7 @@
 	cd OsmoSGSN; $(MAKE) clean
 	cd OsmoNAT; $(MAKE) clean
 	cd OsmoPCU; $(MAKE) clean
+	cd OsmoSTP; $(MAKE) clean
 
 upload:
 	cd OsmoBTS; $(MAKE) upload
@@ -24,6 +26,7 @@
 	cd OsmoSGSN; $(MAKE) upload
 	cd OsmoNAT; $(MAKE) upload
 	cd OsmoPCU; $(MAKE) upload
+	cd OsmoSTP; $(MAKE) upload
 
 check:
 	cd OsmoBTS; $(MAKE) check
@@ -31,6 +34,7 @@
 	cd OsmoBSC; $(MAKE) check
 	cd OsmoSGSN; $(MAKE) check
 	cd OsmoPCU; $(MAKE) check
+	cd OsmoSTP; $(MAKE) check
 	# These don't use asciidoc, so they have no 'make check' target:
 	#cd OsmoMGCP; $(MAKE) check
 	#cd OsmoNAT; $(MAKE) check
diff --git a/OsmoSTP/Makefile b/OsmoSTP/Makefile
new file mode 100644
index 0000000..bf3ba8f
--- /dev/null
+++ b/OsmoSTP/Makefile
@@ -0,0 +1,45 @@
+# XSL stylesheets downloaded from http://docbook.sourceforge.net/release/xsl/current/html/
+# Makefile from BitBake/OpenEmbedded manuals
+
+
+EXTRA_DEPS = gen-stp-vty-docbook
+
+topdir = .
+stp_reference = $(topdir)/osmostp-vty-reference.xml
+manuals = $(stp_reference)
+# types = pdf txt rtf ps xhtml html man tex texi dvi
+# types = pdf txt
+types = $(docbooktotypes)
+docbooktotypes = pdf
+# htmlcssfile =
+# htmlcss =
+
+TOPDIR := ..
+ASCIIDOCS := osmostp-usermanual
+
+include $(TOPDIR)/build/Makefile.asciidoc.inc
+include $(TOPDIR)/build/Makefile.inc
+
+osmostp-usermanual.pdf: chapters/*.adoc
+
+clean:
+	-rm -rf $(cleanfiles)
+	-rm osmostp-usermanual__*.png
+	-rm osmostp-usermanual__*.svg
+	-rm osmostp-usermanual*.check
+
+gen-stp-vty-docbook: FORCE
+	$(call command,xsltproc -o generated/combined1.xml \
+		--stringparam with $(PWD)/../common/vty_additions.xml \
+		$(MERGE_DOC) vty/stp_vty_reference.xml, \
+		XSLTPROC,Merging Common VTY)
+	$(call command,xsltproc -o generated/combined2.xml \
+		--stringparam with $(PWD)/../common/stp_vty_additions.xml \
+		$(MERGE_DOC) generated/combined1.xml, \
+		XSLTPROC,Merging Common STP VTY)
+	$(call command,xsltproc -o generated/combined3.xml \
+		--stringparam with $(PWD)/vty/stp_vty_additions.xml \
+		$(MERGE_DOC) generated/combined2.xml, \
+		XSLTPROC,Merging STP VTY)
+	$(call command,xsltproc ../vty_reference.xsl generated/combined3.xml > generated/docbook_vty.xml, \
+		XSLTPROC,Converting STP VTY to DocBook)
diff --git a/OsmoSTP/osmostp-usermanual-docinfo.xml b/OsmoSTP/osmostp-usermanual-docinfo.xml
new file mode 100644
index 0000000..4253957
--- /dev/null
+++ b/OsmoSTP/osmostp-usermanual-docinfo.xml
@@ -0,0 +1,47 @@
+<revhistory>
+  <revision>
+    <revnumber>1</revnumber>
+    <date>April 16, 2017</date>
+    <authorinitials>HW</authorinitials>
+    <revremark>
+      Initial OsmoSTP manual
+    </revremark>
+  </revision>
+</revhistory>
+
+<authorgroup>
+  <author>
+    <firstname>Harald</firstname>
+    <surname>Welte</surname>
+    <email>hwelte at sysmocom.de</email>
+    <authorinitials>HW</authorinitials>
+    <affiliation>
+      <shortaffil>sysmocom</shortaffil>
+      <orgname>sysmocom - s.f.m.c. GmbH</orgname>
+      <jobtitle>Managing Director</jobtitle>
+    </affiliation>
+  </author>
+</authorgroup>
+
+<copyright>
+  <year>2012-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>
diff --git a/OsmoSTP/osmostp-usermanual.adoc b/OsmoSTP/osmostp-usermanual.adoc
new file mode 100644
index 0000000..2be3372
--- /dev/null
+++ b/OsmoSTP/osmostp-usermanual.adoc
@@ -0,0 +1,33 @@
+OsmoSTP User Manual
+===================
+Harald Welte <hwelte at sysmocom.de>
+
+
+include::../common/chapters/preface.adoc[]
+
+// include::chapters/overview.adoc[]
+
+include::../common/chapters/sigtran.adoc[]
+include::../common/chapters/sigtran-osmocom.adoc[]
+
+//include::chapters/running.adoc[]
+// include::chapters/control.adoc[]
+
+include::../common/chapters/vty.adoc[]
+
+include::../common/chapters/logging.adoc[]
+
+//include::../common/chapters/bts.adoc[]
+
+//include::../OsmoNITB/chapters/bts-examples.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[]
+
diff --git a/OsmoSTP/osmostp-vty-reference.xml b/OsmoSTP/osmostp-vty-reference.xml
new file mode 100644
index 0000000..807d427
--- /dev/null
+++ b/OsmoSTP/osmostp-vty-reference.xml
@@ -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>April 16, 2017</date>
+            <authorinitials>h2</authorinitials>
+            <revremark>Initial</revremark>
+        </revision>
+    </revhistory>
+
+    <title>OsmoSTP VTY Reference</title>
+
+    <copyright>
+      <year>2012-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>
+
diff --git a/OsmoSTP/vty/stp_vty_reference.xml b/OsmoSTP/vty/stp_vty_reference.xml
new file mode 100644
index 0000000..a4c675e
--- /dev/null
+++ b/OsmoSTP/vty/stp_vty_reference.xml
@@ -0,0 +1,2 @@
+<vtydoc xmlns='urn:osmocom:xml:libosmocore:vty:doc:1.0'>
+</vtydoc>
diff --git a/common/chapters/bibliography.adoc b/common/chapters/bibliography.adoc
index a3c6436..d5e1c1b 100644
--- a/common/chapters/bibliography.adoc
+++ b/common/chapters/bibliography.adoc
@@ -106,11 +106,29 @@
   https://tools.ietf.org/html/rfc1350
 - [[[ietf-rfc2131]]] IETF RFC 2131: Dynamic Host Configuration Protocol
   https://tools.ietf.org/html/rfc2131
+- [[[ietf-rfc2719]]] IETF RFC 2719: Signal Transport over IP
+  https://tools.ietf.org/html/rfc2719
+- [[[ietf-rfc3331]]] IETF RFC 3331: Message Transfer Part 2 User Adaptation Layer
+  https://tools.ietf.org/html/rfc3331
 - [[[ietf-rfc3550]]] IETF RFC 3550: RTP: A Transport protocol for Real-Time Applications
   https://tools.ietf.org/html/rfc3550
+- [[[ietf-rfc3868]]] IETF RFC 3868: SCCP User Adaptation Layer
+  https://tools.ietf.org/html/rfc3868
+- [[[ietf-rfc4165]]] IETF RFC 4165: Message Transfer Part 2 Peer-to-Peeer Adaptation Layer
+  https://tools.ietf.org/html/rfc4165
 - [[[ietf-rfc4251]]] IETF RFC 4251: The Secure Shell (SSH) Protocol Architecture
   https://tools.ietf.org/html/rfc4251
+- [[[ietf-rfc4666]]] IETF RFC 4666: Message Transfer Part 3 User Adaptation Layer
+  https://tools.ietf.org/html/rfc4666
 
+- [[[itu-t-q701]]] ITU-T Q.701: Functional Description of the Message Transfer Part (MTP)
+  https://www.itu.int/rec/T-REC-Q.701/en/
+- [[[itu-t-q711]]] ITU-T Q.711: Functional Description of the Signalling Connection Control Part
+  https://www.itu.int/rec/T-REC-Q.711/en/
+- [[[itu-t-q713]]] ITU-T Q.713: Signalling connection control part formats and codes
+  https://www.itu.int/rec/T-REC-Q.713/en/
+- [[[itu-t-q714]]] ITU-T Q.714: Signalling connection control part procedures
+  https://www.itu.int/rec/T-REC-Q.714/en/
 - [[[itu-t-q921]]] ITU-T Q.921: ISDN user-network interface -
   Data link layer specification
   https://www.itu.int/rec/T-REC-Q.921/en
diff --git a/common/chapters/glossary.adoc b/common/chapters/glossary.adoc
index c39d439..042fd3a 100644
--- a/common/chapters/glossary.adoc
+++ b/common/chapters/glossary.adoc
@@ -115,6 +115,8 @@
 GSMTAP::
   GSM tap; pseudo standard for encapsulating GSM protocol layers over
   UDP/IP for analysis
+GT::
+  Global Title; an address in SCCP
 GTP::
   GPRS Tunnel Protocol; used between SGSN and GGSN
 HLR::
@@ -143,6 +145,12 @@
   44.064_ <<3gpp-ts-44-064>>)
 Location Area::
   Location Area; a geographic area containing multiple BTS
+M2PA::
+  MTP2 Peer-to-Peer Adaptation; a SIGTRAN Variant (_RFC 4165_ <<ietf-rfc4165>>)
+M2UA::
+  MTP2 User Adaptation; a SIGTRAN Variant (_RFC 3331_ <<ietf-rfc3331>>)
+M3UA::
+  MTP3 User Adaptation; a SIGTRAN Variant (_RFC 4666_ <<ietf-rfc4666>>)
 MCC::
   Mobile Country Code; unique identifier of a country, e.g. 262 for Germany
 MFF::
@@ -163,6 +171,8 @@
   core network
 MSISDN::
   Mobile Subscriber ISDN Number; telephone number of the subscriber
+MTP::
+  Message Transfer Part; SS7 signaling protocol (_ITU-T Q.701_ <<itu-t-q701>>)
 MVNO::
   Mobile Virtual Network Operator; Operator without physical radio network
 NCC::
@@ -206,6 +216,8 @@
 OTA::
   Over-The-Air; Capability of operators to remotely
   reconfigure/reprogram ISM/USIM cards
+PC::
+  Point Code; an address in MTP
 PCH::
   Paging Channel on downlink Um interface; used by network to page an MS
 PCU::
@@ -249,11 +261,15 @@
 SACCH::
   Slow Associate Control Channel on Um interface; bundled to a TCH or
   SDCCH, used for signalling in parallel to active dedicated channel
+SCCP::
+  Signaling Connection Control Part; SS7 signaling protocol (_ITU-T Q.711_ <<itu-t-q711>>)
 SDCCH::
   Slow Dedicated Control Channel on Um interface; used for signalling
   and SMS transport in GSM
 SDK::
   Software Development Kit
+SIGTRAN::
+  Signaling Transport over IP (_IETF RFC 2719_ <<ietf-rfc2719>>)
 SIM::
   Subscriber Identity Module; small chip card storing subscriber identity
 Site::
@@ -264,8 +280,16 @@
   entities with an SMSC
 SMSC::
   Short Message Service Center; store-and-forward relay for short messages
+SS7::
+  Signaling System No. 7; Classic digital telephony signaling system
 SSH::
   Secure Shell; _IETF RFC 4250_ <<ietf-rfc4251>> to 4254
+SSN::
+  Sub-System Number; identifies a given SCCP Service such as MSC, HLR
+STP::
+  Signaling Transfer Point; A Router in SS7 Networks
+SUA::
+  SCCP User Adaptation; a SIGTRAN Variant (_RFC 3868_ <<ietf-rfc3868>>)
 syslog::
   System logging service of UNIX-like operating systems
 System Information::
diff --git a/common/chapters/sigtran-osmocom.adoc b/common/chapters/sigtran-osmocom.adoc
new file mode 100644
index 0000000..1e08733
--- /dev/null
+++ b/common/chapters/sigtran-osmocom.adoc
@@ -0,0 +1,432 @@
+== Osmocom SS7 + SIGTRAN support
+
+=== History / Background
+
+If you're upgrading from earlier releases of the Osmocom stack, this
+section will give you some background about the evolution.
+
+==== The Past (before 2017)
+
+In the original implementation of the GSM BSC inside Osmocom (the
+OsmoBSC program, part of OpenBSC), no SS7 support was included.
+
+This is despite the fact that ETSI/3GPP mandated the use of SCCP over
+MTP over E1/T1 TDM lines for the A interface at that time.
+
+Instead of going down to the TDM based legacy physical layers, OsmoBSC
+implemented someting called an IPA multiplex, which apparently some
+people also refer to as SCCPlite.  We have never seen any
+specifications for this interface, but implemented it from scratch
+using protocol traces.
+
+The IPA protocol stack is based on a minimal sub-set of SCCP
+(including connection oriented SCCP) wrapped into a 3-byte header to
+packetize a TCP stream.
+
+The IPA/SCCPlite based A interface existed at a time when the
+ETSI/3GPP specifications did not offer any IP based transport for the
+A interface.  An official as added only in Release FIXME of the 3GPP
+specifications.
+
+The A interface BSSMAP protocol refers to voice circuits (E1/T1
+timeslots) using circuit identity codes (CICs).  As there are no
+physical timeslots on a TCP/IP based transport layer, the CICs get
+mapped to RTP streams for circuit-switched data using out-of-band
+signaling via MGCP, the IETF-standardized Media Gateway Control
+Protocol.
+
+==== The present (2017)
+
+In 2017, sysmocom was tasked with implementing a 3GPP AoIP compliant A
+interface.  This meant that lot of things had to change in the
+existing code:
+
+* removal of the existing hard-wired SCCPlite/IPA code from OsmoBSC
+* introduction of a formal SCCP User SAP at the lower boundary of
+  BSSMAP
+* introduction of libosmo-sigtran, a comprehensive SS7 and SIGTRAN
+  library which includes a SCCP implementation for connectionless and
+  connection-oriented procedures, offering the SCCP User SAP towards
+  BSSAP
+* introduction of an A interface in OsmoMSC (which so far offered Iu
+  only)
+* port of the existing SUA-baesd IuCS and IuPS over to the SCCP User
+  SAP of libosmo-sigtran.
+* Implementation of ETSI M3UA as preferred/primary transport layer for
+  SCCP
+* Implementation of an IPA transport layer inside libosmo-sigtran, in
+  order to keep backwards-compatibility.
+
+This work enables the Osmocom universe to become more compliant
+with modern Releases of 3GPP specifications, which enables
+interoperability with other MSCs or even BSCs.  However, this comes at
+a price:  Increased complexity in set-up and configuration.
+
+Using SS7 or SIGTRAN based transport of the A interface adds an
+entirely new domain that needs to be understood by system and network
+administrators setting up cellular networks based on Osmocom.
+
+One of the key advantages of the Osmocom architecture with OsmoNITB
+was exactly this simplification and reduction of complexity, enabling
+more people to set-up and operate cellular networks.
+
+So we have put some thought into how we can achieve compatibility with
+SS7/SIGTRAN and the 3GPP specifications, while at the same time
+enabling some degree of auto-configuration where a small network can
+be set up without too many configuration related to the signaling
+network.  We have achieved this by "abusing" (or extending) the M3UA
+Routing Key Management slightly.
+
+=== Osmocom extensions to SIGTRAN
+
+Osmocom has implemented some extensions to the SIGTRAN protocol suite.
+Those extensions will be documented below.
+
+==== Osmocom M3UA Routing Key Management Extensions
+
+In classic M3UA, a peer identifies its remote peer based on IP address
+and port details.  So once an ASP connects to an SG, the SG will check
+if there is any configuration that matches the source IP (and possibly
+source port) of that connection in order to understand which routing
+context is used - and subsequently which traffic is to be routed to
+this M3UA peer.
+
+This is quite inflexible, as it means that every BSC in a GSM network
+needs to be manually pre-configured at the SG/STP, and that
+configuration on the BSC and MSC must match to enable communication.
+
+M3UA specifies an optional Routing Key Management (RKM) sub-protocol.
+Using RKM, an ASP can dynamically tell the SG/STP, which traffic it
+wants to receive.  However, the idea is still that the SG has some
+matching configuration.
+
+In OsmoSTP based on libosmo-sigtran, we decided to (optionally) enable
+fully dynamic registration.  This means that any ASP can simply
+connect to the SG and request the dynamic creation of an ASP and AS
+with a corresponding routing key for a given point code.  As long as
+the SG doesn't already have a route to this requested point code, The
+SG will simply trust any ASP and set a corresponding route.
+
+This is of course highly insecure and can only be used in trusted,
+internal newtworks.  However, it is quite elegant in reducing the
+amount of configuration complexity.  All that is needed, is that an
+unique point code is configured at each of the ASPs (application
+programs) that connect to the STP.
+
+To put things more concretely: Each BSC and MSC connecting to OsmoSTP
+simply needs to be configured to have a different point code, and to
+know to which IP/port of the STP to connect.  There's no other
+configuration required for a small, autonomous, self-contained
+network.  OsmoSTP will automatically insall ASP, AS and route
+definitions on demand, and route messages between all connected
+entities.
+
+The same above of course also applies to HNB-GW and OsmoSGSN in the
+case of Iu interfaces.
+
+==== IPA / SCCPlite backwards compatibility
+
+The fundamental problem with IPA/SCCPlite is that there's no MTP
+routing label surrounding the SCCP message.  This is generally
+problematic in the context of connection-oriented SCCP, as there is no
+addressing information inside the SCCP messages after the connection
+has been established.  Instead, the messages are routed based on the
+MTP label, containing point codes established during connection set-up
+time.
+
+This means that even if the SCCP messages did contain Called/Calling
+Party Addresses with point codes or global titles, it would only help
+us for routing connectionless SCCP.  The A interface, however, is
+connection-oriented.
+
+So in order to integrate IPA/SCCPlite with a new full-blown
+SS7/SIGTRAN stack, there are the following options:
+
+. implement SCCP connection coupling.  This is something like a proxy
+  for connection-oriented SCCP, and is what is used in SS7 to route
+  beyond a given MTP netwokr (e.g. at gateways between different MTP
+  networks)
+
+. consider all SCCP messages to be destined for the local point code
+  of the receiver.  This then means that the SG functionality must be
+  included inside the MSC, and the MSC be bound to the SSN on the
+  local point code.
+
+. hard-code some DPC when receiving a message from an IPA connection.
+  It could be any remote PC and we'd simply route the message towards
+  that point code.
+
+But then we also have the return direction:
+
+. We could "assign" a unique SPC to each connected IPA client (BSC),
+  and then announce that PC towards the SS7 side.  Return packets
+  would then end up at our IPA-server-bearing STP, which forwards them
+  to the respective IPA connection and thus BSC.  On the transmit
+  side, we'd simply strip the MTP routing label and send the raw SCCP
+  message over IPA.
+
+. If the IPA server / SGW resides within the MSC, one could also have
+  some kind of handle/reference to the specific TCP connection through
+  which the BSC connected.  All responses for a given peer would then
+  have to be routed back to the same connection.   This is quite ugly
+  as it completely breaks the concepts of the SCCP User SAP, where a
+  user has no information (nor to worry about ) any "physical"
+  signaling links.
+
+
+=== Minimal Osmocom SIGTRAN configurations for small networks
+
+If you're not an SS7 expert, and all you want is to run your own small
+self-contained cellular network, this section explains what you need
+to do.
+
+In general, you can consider OsmoSTP as something like an IP router.
+On the application layer (in our case the BSSAP/BSSMAP or RANAP
+protocols between Radio Access Network and Core Network), it is
+completely invisible/transparent.  The BSC connects via SCCP to the
+MSC.  It doesn't know that there's an STP in between, and that this
+STP is performing some routing function.  Compares this to your web
+browser not knowing about IP routers, it just establishes an http
+connection to a web server.
+
+This is also why most GSM nework architecture diagrams will not
+explicitly show an STP.  It is not part of the cellular network.
+Rather, one or many STPs are part of the underlying SS7 signaling
+transport network, on top of which the cellular network elements are
+built.
+
+==== A minimal 2G configuration to get started
+
+You will be running the following programs:
+
+* OsmoBSC as the base-station controller between your BTS (possibly
+  running OsmoBTS) and the MSC
+* OsmoMSC as the mobile switching center providing SMS and telephony
+  service to your subscribers
+* OsmoSTP as the signal transfer point, routing messages between one
+  or more BSCs and the MSC
+
+[[fig-sigtran-simple-2g]]
+.Simple signaling network for 2G (GSM)
+[graphviz]
+----
+include::sigtran-simple-2g.dot[]
+----
+
+You can use the OsmoSTP fully dynamic registration feature, so the BSCs
+and the MSC will simply register with their point codes to the STP,
+and the STP will create most configuration on the fly.
+
+All you need to make sure is:
+
+* to assign one unique point code to each BSC and MSC
+* to point all BSCs and the MSC to connect to the IP+Port of the STP
+* to configure the point code of the MSC in the BSCs
+
+==== A minimaal 3G configuration to get started
+
+You will be running the following programs:
+
+* OsmoHNBGW as the homeNodeB Gateway between your femtocells / small
+  cells  and the MSC+SGSN
+* OsmoMSC as the mobile switching center providing SMS and telephony
+  service to your subscribers
+* OsmoSGSN as the Serving GPRS Support Node, providing packet data
+  (internet) services to your subscribers
+* OsmoSTP as the signal transfer point, routing messages between one
+  or more HNBGWs and the MSC and SGSN
+
+[[fig-sigtran-simple-3g]]
+.Simple signaling network for 3G (UMTS)
+[graphviz]
+----
+include::sigtran-simple-3g.dot[]
+----
+
+You can use the OsmoSTP fully dynamic registration feature, so the
+HNBGWs, the SMC and the SGSNwill simply register with their point
+codes to the STP, and the STP will create most configuration on the
+fly.
+
+All you need to make sure is:
+
+* to assign one unique point code to each HNBGW, MSC and SGSN
+* to point all HNBGWs and the MSC and SGSN to connect to the IP+Port of STP
+* to configure the point code of the MSC in the HNBGWs
+* to configure the point code of the SGSN in the HNBGWs
+
+=== Osmocom SS7 Instances
+
+The entire SS7 stack can be operated multiple times within one
+application/program by means of so-called SS7 Instances.
+
+There can be any number of SS7 Instances, and each instance has its
+own set of XUA Servers, ASPs, ASs, Routes, etc.
+
+Each SS7 Instance can have different point code formats / lengths.
+
+.Major Attributes of an Osmocom SS7 Instance
+[options="header",cols="25%,35%,40%"]
+|====
+|Name|VTY Command|Description
+|ID|(config)# cs7 instance ID|The numeric identifier of this instance
+|Name|(config-cs7)# name NAME|A human-readable name for this instance
+|Description|(cnfig-cs7)# description DESC| More verbose description
+|Primary PC|(config-cs7)# point-code PC|Primary local point code
+|Network Indicator|(config-cs7)# network-indicator|Network Indicator used in MTP3 Routing Label
+|Point Code Format|(config-cs7)# point-code format|Point Code Format (Default: 3.8.3)
+|Point Code Delimiter|(config-cs7)# point-code delimiter|Point Code Delimiter: . or -
+|====
+
+=== Osmocom SS7 xUA Server
+
+A *xUA Server* is a server that binds + listens to a given SCTP
+(SIGTRAN) or TCP (IPA) port and accepts connections from remote peers
+(ASPs).
+
+There can be any number of xUA Servers within one SS7 Instance, as
+long as they all run on a different combination of IP address and
+port.
+
+.Major Attributes of an Osmocom SS7 xUA Server
+[options="header",cols="25%,75%"]
+|====
+|Name|Description
+|Local IP|Local Port Number to which the server shall bind/listen
+|Local Port|Local IP Address to which the server shall bind/listen
+|Protocol|Protocol (M3UA, SUA, IPA) to be operated by this server
+|Accept Dynamic ASPs|Should we accept connections from ASPs that are not explicitly pre-configured with their source IP and port?
+|====
+
+
+=== Osmocom SS7 Users
+
+A SS7 User is part of a program that binds to a given MTP-Layer
+Service Indicator (SI).  The Osmocom SS7 stack offers an API to
+register SS7 Users, as well as the VTY command ``show cs7 instance
+<0-15> users'' to list the currently registered users.
+
+=== Osmocom SS7 Links
+
+TBD.
+
+=== Osmocom SS7 Linksets
+
+TBD.
+
+=== Osmocom SS7 Application Servers
+
+This corresponds 1:1 to the SIGTRAN concept of an Application Server,
+i.e. a given external Application that interfaces the SS7 network via
+a SS7 protocol variant such as M3UA.
+
+In the context of Osmocom, for each program connecting to a STP (like
+a BSC or MSC), you will have one Application Server definition.
+
+An AS has the following properties:
+
+.Major Attributes of an Osmocom SS7 Application Server
+[options="header",cols="25%,75%"]
+|====
+|Name|Description
+|Name|A human-readable name for this instance
+|Description|More verbose description (for human user only)
+|Protocol|Protocol (M3UA, SUA, IPA) to be operated by this server
+|Routing Key|Routing Key (mostly Point Code) routed to this AS
+|Traffic Mode|Theoretically Bradcast, Load-Balance.  Currently only Ovverride
+|Recovery Timeout|Duration of the AS T(r) recovery timer.  During this time,
+                  outgoing messages are queued. If the AS is ACTIVE
+                  before timer expiration, the queue is drained.  At
+                  expriation, the queue is flushed.
+|State|Application Server State (Down, Inactive, Active, Pending)
+|ASPs|Which ASPs are permitted to transfer traffic for this AS
+|====
+
+=== Osmocom SS7 Application Server Processes
+
+An Application Server Process corresponds to a given SCTP (or TCP)
+connection.  From the STP/SG (Server) point-of-view, those are
+incoming connections from Application Servers such as the BSCs.  From
+the ASP (Client) Point of view, it has one ``osmo_ss7_asp'' object for
+each outbound SIGTARN connection.
+
+An ASP has the following properties:
+
+.Major Attributes of an Osmocom SS7 Application Server Process
+[options="header",cols="25%,75%"]
+|====
+|Name|Description
+|Name|A human-readable name for this instance
+|Description|More verbose description (for human user only)
+|Protocol|Protocol (M3UA, SUA, IPA) to be operated by this server
+|Role|Server (SG) or Client (ASP)?
+|Local Port|Port Number of the local end of the connection
+|Local IP|IP Address of the local end of the connection
+|Remote Port|Port Number of the remote end of the connection
+|Remote IP|IP Address of the remote end of the connection
+|State|ASP State (Down, Inactive, Active)
+|====
+
+=== Osmocom SS7 Routes
+
+An Osmocom SS7 Route routes traffic with a matching destination point
+code and point code mask (similar to IP Address + Netmask) towards a
+specified SS7 Linkset or Application Server.  The Linkset or
+Application Servers are identified by their name.
+
+.Major Attributes of an Osmocom SS7 Application Server Process
+[options="header",cols="25%,75%"]
+|====
+|Name|Description
+|Point Code|Destination Point Code for this route
+|Mask|Destination Mask for this route (like an IP netmask)
+|Linkset/AS Name|Destination Linkset or AS, identified by name
+|====
+
+
+=== Osmocom SCCP Instances
+
+An Osmocom SS7 Instance can be bound to an Osmocom SS7 Instance.  It
+will register/bind for the ITU-standard Service Indicator (SI).
+
+=== Osmocom SCCP User
+
+An Program (like a BSC) will _bind_ itself to a given well-known
+sub-system number (SSN) in order to receive SCCP messages destined for
+this SSN.
+
+There is an API to bind a program to a SSN, which implicitly generates
+an SCCP User object.
+
+The ``show cs7 instance <0-15> sccp users'' command can be used on the
+VTY to obtain a list of currently bound SCCP users, as well as their
+corresponding SSNs.
+
+=== Osmocom SCCP Connection
+
+This is how Osmocom represents each individual connection of
+connection-oriented SCCP.
+
+To illustrate the practical applicaiton: For the common use case of
+the A or Iu interfaces, this means that every dedicated radio channel
+that is currently active to any UE/MS has one SCCP connection to the
+MSC and/or SGSN.
+
+The ``show cs7 instance <0-15> sccp connections'' command can be used
+on the VTY to obtain a list of currently active SCCP connections, as
+well as their source/destination and current state.
+
+
+=== Osmocom SCCP User SAP
+
+The Osmocom SCCP User SAP (Service Access Point) is the programming
+interface between the SCCP Provider (libosmo-sigtran) and the SCCP
+User.  It follows primitives as laid out in <<itu-t-q711>>, encapsulated
+in ``osmo_prim'' structures.
+
+=== Osmocom MTP User SAP
+
+The Osmocom MTP User SAP (Service Access Point) is the programming
+interface betwen the MTP Provider and the MTP User (e.g. SCCP).  It
+follows primitives as laid out in <<itu-t-q711>>, encapsulated in
+``osmo_prim'' structures.
diff --git a/common/chapters/sigtran-simple-2g.dot b/common/chapters/sigtran-simple-2g.dot
new file mode 100644
index 0000000..28098fd
--- /dev/null
+++ b/common/chapters/sigtran-simple-2g.dot
@@ -0,0 +1,22 @@
+digraph G {
+        rankdir=LR;
+        MS0 [label="MS"];
+        MS1 [label="MS"];
+        MS2 [label="MS"];
+        MS3 [label="MS"];
+        BTS0 [label="BTS"];
+        BTS1 [label="BTS"];
+        BSC [label="OsmoBSC"];
+        MSC [label="OsmoMSC"];
+        STP [label="OsmoSTP"];
+
+	MS0 -> BTS0;
+	MS1 -> BTS0;
+	MS2 -> BTS1;
+	MS3 -> BTS1;
+	BTS0 -> BSC [label="Abis/IP"];
+	BTS1 -> BSC [label="Abis/IP"];
+	BSC -> STP [label="SCCP/M3UA"];
+	STP -> MSC [label="SCCP/M3UA", dir="back"];
+}
+
diff --git a/common/chapters/sigtran-simple-3g.dot b/common/chapters/sigtran-simple-3g.dot
new file mode 100644
index 0000000..eac363d
--- /dev/null
+++ b/common/chapters/sigtran-simple-3g.dot
@@ -0,0 +1,24 @@
+digraph G {
+        rankdir=LR;
+        UE0 [label="UE"];
+        UE1 [label="UE"];
+        UE2 [label="UE"];
+        UE3 [label="UE"];
+        HNB0 [label="hNodeB"];
+        HNB1 [label="hNodeB"];
+        HNBGW [label="OsmoHNBGW"];
+        MSC [label="OsmoMSC"];
+        SGSN [label="OsmoSGSN"];
+        STP [label="OsmoSTP"];
+
+	UE0 -> HNB0;
+	UE1 -> HNB0;
+	UE2 -> HNB1;
+	UE3 -> HNB1;
+	HNB0 -> HNBGW [label="Iuh (RUA)"];
+	HNB1 -> HNBGW [label="Iuh (RUA)"];
+	HNBGW -> STP [label="Iu (SCCP/M3UA)"];
+	STP -> MSC [label="Iu (SCCP/M3UA)", dir="back"];
+	STP -> SGSN [label="Iu (SCCP/M3UA)", dir="back"];
+}
+
diff --git a/common/chapters/sigtran.adoc b/common/chapters/sigtran.adoc
new file mode 100644
index 0000000..9d8e42e
--- /dev/null
+++ b/common/chapters/sigtran.adoc
@@ -0,0 +1,330 @@
+== Signaling Networks: SS7 and SIGTRAN
+
+Classic digital telephony networks (whether wired or wireless) use the
+ITU-T SS7 (Signaling System 7) to exchange signaling information
+between network elements.
+
+Most of the ETIS/3GPP interfaces in the GSM and UMTS network are also
+based on top of [parts of] SS7.  This includes, among others, the
+following interfaces:
+
+* _A_ interface between BSC and MSC
+* _IuCS_ interface between RNC (or HNB-GW) and MSC
+* _IuPS_ interface between RNC (or HNB-GW) and SGSN
+
+NOTE:: This does not include the A-bis interface between BTS and BSC.
+While Abis traditionally is spoken over the same physical TDM circuits
+as SS7, the protocol stack from L2 upwars is quite different (Abis
+uses LAPD, while SS7 uses MTP)!
+
+=== Physical Layer
+
+The traditional physical layer of SS7 is based on TDM (time division
+multiplex) links of the PDH/SDH family, as they were common in ISDN
+networks.  Some people may know their smallest incarnation as
+so-called E1/T1 links.  It can run either on individual 64kBps
+timeslots of such a link, or on entire 2Mbps/1.5MBps E1/T1 links.
+
+There are also specifications for SS7 over ATM, though it is unclear
+to the author if this is actually still used anywhere.
+
+On top of the Physical Layer is the Message Transfer Part (MTP).
+
+=== Message Transfer Part (MTP)
+
+MTP is the lower layer of the SS7 protocol stack.  It is comprised of
+two sub-layes, called MTP2 and MTP3.
+
+Nodes in a MTP network are addressed by their unique PC (Point Code).
+
+A _MTP Routing Label_ is in the MTP header and indicates the
+_Originationg Point Code_ (OPC) as well as the _Destination Point
+Code_ (DPC) and the _Service Indicator Octet_ (SIO).  The SIO is used
+to de-multiplex between different upper-layer protocol such as ISUP,
+TUP or SCCP.
+
+Routing is performed by means of routers with routing tables, similar
+to routing is performed in IP networks.  Even the concept of a _point
+code mask_ analogous to the _netmask_ exists.
+
+Routers are connected with one another over one or more _Link Sets_,
+each comprised of one or multiple _Links_.  Multiple Links in a
+Linkset exist both for load sharing as well as for fail over purposes.
+
+==== Point Codes
+
+The length of point codes depends on the particular MTP dialect that
+is used.  In the 1980ies, when international telephony signaling
+networks were established, most countries had their own national
+dialects with certain specifics.
+
+Today, mostly the ITU and ANSI variants survive.  The ITU variant uses
+14bit point codes, while the ANSI variant uses 24 bit point code
+length.
+
+Point Codes can be represented either as unsigned integers, or
+grouped.  Unfortunately there is no standard as to their
+representation.  In ITU networks, the _3.8.3_ notation is commonly
+used, i.e. one decimal for the first 3 bits, followed by one decimal
+for the center 8 bits, followed by another decimal for the final 3
+bits.
+
+Example:: The Point Code *1.5.3* (in 3.8.3 notation) is 1*2^11^ + 5*2^3^ + 3 = *2091 decimal*.
+
+=== Higher-Layer Protocols
+
+There are various higher-layer protocols used on top of MTP3, such as
+TUP, ISUP, BICC as well as SCCP.   Those protocols exist side-by-side
+on top of MTP3, similar to e.g. ICMP, TCP and UDP existing
+side-by-side on top of IP.
+
+In the context of cellular networks, SCCP is the most relevant part.
+
+=== Signaling Connection Control Part (SCCP)
+
+SCCP runs on top of MTP3 and creates something like an overlay network
+on top of it.  SCCP communication can e.g. span multiple different
+isolated MTP networks, each with their own MTP dialect and addressing.
+
+SCCP provides both connectionless (datagram) and connection-oriented
+services.  Both are used in the context of cellular networks.
+
+==== SCCP Adresses
+
+SCCP Adresses are quite complex.  This is due to the fact that it is
+not simply one address format, but in fact a choice of one or multiple
+different types of addresses.
+
+SCCP Addresses exist as _Calling Party_ and _Called Party_ addresses.
+In the context of connectionless datagram services, the sender is
+always the Calling Party, and the receiver the Called Party.  In
+connection-oriented SCCP, they resemble the initiator and recipient of
+the connection.
+
+.SCCP Address Parts
+[options="header",cols="10%,20%,70%"]
+|====
+|Acronym|Name|Description
+|SSN|Sub-System Number|Describes a given application such as e.g. a
+                       GSM MSC, BSC or HLR.  Can be compared to port
+                       numbers on the Internet
+|PC|Point Code        |The Point Code of the underlying MTP network
+|GT|Global Title      |What most people would call a "phone number".
+                       However, Global Titles come in many different
+                       numbering plans, and only one of them (E.164)
+                       resembles actual phone numbers.
+|RI|Routing Indicator |Determines if message shall be routed on PC+SSN
+                       or on GT basis
+|====
+
+==== Global Titles
+
+A Global Title is a (typically) globally unique address in the global
+telephony network.  The body of the Global Title consists of a series
+of BCD-encoded digits similar to what everyone knows as phone numbers.
+
+A GT is however not only the digits of the "phone number", but also
+some other equally important information, such as the _Numbering Plan_
+as well as the _Nature of Address Indication_.
+
+.Global Title Parts
+[options="header",cols="10%,20%,70%"]
+|====
+|Acronym|Name|Description
+|GTI|Global Title Indicator|Determines the GT Format. Ranges from no
+                            GT (0) to GT+TT+NP+ES+NAI (4)
+|NAI|Nature of Address Indicator|Exists in GTI=1 and is sort of a mixture of TON + NPI
+|TT|Translation Type      |Used as a look-up key in Global Title Translation Tables
+|NP|Numbering Plan        |Indicates ITU Numbering Plan, such as E.164, E.212, E.214
+|ES|Encoding Scheme       |Just a peculiar way to idicate the length of the digits
+|- |Signals               |The actual "phone number digits"
+|====
+
+For more information about SCCP Adresses and Global Titles, please
+refer to <<itu-t-q713>>
+
+
+==== Global Title Translation (GTT)
+
+Global Title Translation is a process of re-writing the Global Title
+on-the-fly while a signaling message passes a STP.
+
+Basically, a SCCP message is first transported by MTP3 on the MTP
+level to the Destination Point Code indicated in the MTP Routing
+Label.  This process uses MTP routing and is transparent to SCCP.
+
+Once the SCCP message arrives at the MTP End-Node identified by the
+Destination Point Code, the message is handed up to the local SCCP
+stack, which then may implement Global Title Translation.
+
+The input to the GTT process is
+* the destination address of the SCCP message
+* a local list/database of Global Title Translation Rules
+
+The successful output of he GTT includes
+* A new Routing Indicator
+* The Destination Point Code to which the message is forwarded on MTP
+  level
+* a Sub-system Number (if RI is set to "Route on SSN")
+* a new Global Title (if RI is set to "Route on GT"), e.g. with translated digits.
+
+Between sender and recipient of a signaling message, there can be many
+instances of Global Title Translation (up to 15 as per the hop
+counter).
+
+For more information on Global Title Translation, please refer to
+<<itu-t-q714>>.
+
+
+==== Peculiarities of Connection Oriented SCCP
+
+Interestingly, Connection-Oriented SCCP messages carry SCCP Adresses
+*only during connection establishment*.  All data messages during
+an ongoing connection do not contain a Called or Calling Party
+Address.  Instead, they are routed only by the MTP label, which is
+constructed from point code information saved at the time the
+connection is established.
+
+This means that connection-oriented SCCP can not be routed across MTP
+network boundaries the same way as connectionless SCCP messages.
+Instead, an STP would have to perform _connection coupling_, whic is
+basically the equivalent of an application-level proxy between two
+SCCP connections, each over one of the two MTP networks.
+
+This is probably mostly of theoretical relevance, as
+connection-oriented SCCP is primarily used betwen RAN and CN of
+cellular network inside one operator, i.e. not across multiple MTP
+networks.
+
+=== SIGTRAN - SS7 over IP Networks
+
+At some point, IP based networks became more dominant than classic
+ISDN networks, and 3GPP as well as IETF were working out methods in
+which telecom signaling traffic can be adapted over IP based
+networks.
+
+Initially, only the edge of the network (i.e. the applications talking
+to the network, such as HLR or MSC) were attached to the existing old
+SS7 backbone by means as SUA and M3UA.  Over time, even the links of
+the actual network backbone networks became more and more IP based.
+
+In order to replace existing TDM-based SS7 links/liksets with SIGTRAN,
+the M2UA or M2PA variants are used as a kind of drop-in replacement
+for physical links.
+
+All SIGTRAN share that while they use IP, they don't use TCP or UDP
+but operate over a (then) newly-introduced Layer 4 transport protocol
+on top of IP: SCTP (Stream Control Transmission Protocol).
+
+Despite first being specified in October 2000 as IETF RFC 2960, it
+took a long time until solid implementations of SCTP ended up in
+general-purpose operating systems.  SCTP is not used much outside the
+context of SIGTAN, which means implementations often suffer from bugs,
+and many parts of the public Internet do not carry SCTP traffic due to
+restrictive firewalls and/or ignorant network administrators.
+
+==== SIGTRAN Concepts / Terminology
+
+Like every protocol or technologoy, SIGTRAN brings with it its own
+terminologyand concepts.  This section tries to briefly introduce
+them.  For more information, please see the related IETF RFCs.
+
+===== Signaling Gateway (SG)
+
+The Signaling Gateway (SG) interconnects the SS7 network wit external
+applications.  It translates (parts of) the SS7 protocol stack into an
+IP based SIGTRAN protocol stack.  Which parts at whcih level of the
+protocol stack are translated to what depends on the specific SIGTRAN
+dialect.
+
+A SG is traditionally attached to the TDM-Based SS7 network and offers
+SIGTRAN/IP based applications a way to remotely attach to the SS7
+network.
+
+A SG typically has STP functionality built-in, but it is not
+mandatory.
+
+===== Application Server (AS)
+
+An Application Server is basically a logical entity representing one
+particular external application (from the SS7 point of view) which is
+interfaced with the SS7 network by means of one of the SIGTRAN
+protocols.
+
+An Application Server can have one or more Application Server Processes
+associated with it.  This functionality (currently not implemented in
+Osmocom) can be used for load-balancing or fail-over scenarios.
+
+===== Application Server Process (ASP)
+
+An Application Server Process represents one particular SCTP
+connection used for SIGTRAN signaling between an external application
+(e.g. a BSC) and the Signaling Gateway (SG).
+
+One Application Server Process can route traffic for multiple
+Application Servers.  In order to differentiate traffic for different
+Application Servers, the Routing Context header is used.
+
+==== SIGTRAN variants / stackings
+
+SIGTRAN is the name of an IETF working group, which has released an
+entire group of different protocol specifications.  So rather than one
+way of transporting classic telecom signaling over IP, there are now
+half a dozen different ones, and all can claim to be an official IETF
+standard.
+
+FIXME: Overview picture comparing the different stackings
+
+===== MTP3 User Adaptation (M3UA)
+
+M3UA basically "chops off" everything up to and including the MTP3
+protocol layer of the SS7 protocol stack and replaces it with a stack
+comprised of M3UA over SCTP over IP.
+
+M3UA is specified in <<ietf-rfc4666>>.
+
+===== SCCP User Adaptation (SUA)
+
+SUA basically "chops off" everything up to and including the SCCP
+protocol layer of the SS7 protocol stack and replaces it with a stack
+comprised of SUA over SCTP over IP.
+
+This means that SUA can only be used for SCCP based signaling, but not
+for other SS7 protocols like e.g. TUP and ISUP.
+
+SUA is specified in <<ietf-rfc3868>>.
+
+===== MTP2 User Adaptation (M2UA)
+
+M2UA is specified in <<ietf-rfc3331>>.
+
+NOTE:: M2UA is not supported in Osmocom SIGTRAN up to this point.  Let
+us know if we can implement it for you!
+
+===== MTP2-User Peer-to-Peer Adaptation (M2PA)
+
+M2PA is specified in <<ietf-rfc4165>>.
+
+NOTE:: M2PA is not supported in Osmocom SIGTRAN up to this point.  Let
+us know if we can implement it for you!
+
+
+==== SIGTRAN security
+
+There simply is none.  There are some hints that TLS shall be used
+over SCTP in order to provide authenticity and/or confidentiality for
+SIGTRAN, but this is not widely used.
+
+As telecom signaling is not generally carried over public networks,
+private networks/links by means of MPLS, VLANs or VPNs such as IPsec
+are often used to isolate and/or secure SIGTRAN.
+
+Under no circumstances should you use unsecured SIGTRAN with
+production data over the public internet!
+
+==== IPv6 support
+
+SCTP (and thus all the higher layer protocols of the various SIGTRAN
+stackings) operates on top of both IPv4 and IPv6.  As the entire
+underlying IP transport is transparent to the SS7/SCCP applcations,
+there is no restriction on whether to use SIGTRAN over IPv4 or IPv6.

-- 
To view, visit https://gerrit.osmocom.org/2371
To unsubscribe, visit https://gerrit.osmocom.org/settings

Gerrit-MessageType: newpatchset
Gerrit-Change-Id: I450bfac7444ac9cb7f50c086d87cf7157c2e2a31
Gerrit-PatchSet: 2
Gerrit-Project: osmo-gsm-manuals
Gerrit-Branch: master
Gerrit-Owner: Harald Welte <laforge at gnumonks.org>
Gerrit-Reviewer: Jenkins Builder



More information about the gerrit-log mailing list