Change in osmo-sgsn[master]: WIP: OsmoGbPROXY user manual

Harald Welte gerrit-no-reply at
Tue Apr 23 20:49:13 UTC 2019

Harald Welte has uploaded this change for review. (

Change subject: WIP: OsmoGbPROXY user manual

WIP: OsmoGbPROXY user manual

Change-Id: I80d4ea016376c59995ccfcd8685c7c0e86745bd2
M doc/manuals/
A doc/manuals/chapters/gbproxy.adoc
A doc/manuals/osmogbproxy-usermanual-docinfo.xml
A doc/manuals/osmogbproxy-usermanual.adoc
4 files changed, 212 insertions(+), 1 deletion(-)

  git pull ssh:// refs/changes/63/13763/1

diff --git a/doc/manuals/ b/doc/manuals/
index 00a08c8..f11acb3 100644
--- a/doc/manuals/
+++ b/doc/manuals/
@@ -1,11 +1,13 @@
 EXTRA_DIST = osmosgsn-usermanual.adoc \
     osmosgsn-usermanual-docinfo.xml \
     osmosgsn-vty-reference.xml \
+    osmogbproxy-usermanual.adoc \
+    osmogbproxy-usermanual-docinfo.xml \
     chapters \
-  ASCIIDOC = osmosgsn-usermanual.adoc
+  ASCIIDOC = osmosgsn-usermanual.adoc osmogbproxy-usermanual.adoc
   ASCIIDOC_DEPS = $(srcdir)/chapters/*.adoc
   include $(OSMO_GSM_MANUALS_DIR)/build/
diff --git a/doc/manuals/chapters/gbproxy.adoc b/doc/manuals/chapters/gbproxy.adoc
new file mode 100644
index 0000000..41debe2
--- /dev/null
+++ b/doc/manuals/chapters/gbproxy.adoc
@@ -0,0 +1,125 @@
+== Overview
+== About OsmoGbPROXY
+OsmoGbPROXY is the Osmocom proxy for the 3GPP Gb interface.  The Gb
+interface is defined by 3GPP as the protocol between the BSS and the
+SGSN inside the 2G/2.5G/2.75G packet switched network domain.
+As Osmocom implements a BTS-colocated PCU, there are potentially many
+Gb interface connections between all those many PCUs in the network
+and the SGSN.  This can be cumbersome to configure/maintain at the
+SGSN sine.
+OsmoGbPROXY aggregates many PCU-facing Gb connections into one Gb
+connection to the SGSN.  This is achieved by
+* maintaining sepaate NS-VCs on the PCU side and on the SGSN side
+* more or less transparently routing BSSGP peer-to-peer Virtual Circuits
+  (BVCs) through the proxy
+* having some special handling for the signaling BVC (BVCI=0) which is
+  shared among all the PCUs connected to the proxy
+== Data Model
+=== gbproxy_config
+=== gproxy_peer
+A "peer" is any remote NS-entity that the proxy interacts with.  A peer
+includes information about:
+* the [unique] NSEI of the peer
+* the [unique] BVCI of the peer
+* the Routeing Area (RA) of the peer
+=== gbproxy_tlli_state
+One of the (unique) TLLI of any of the subscribers/UEs attached to any of
+the BTSs/PCUs served by the proxy.
+=== gbproxy_link_info
+One of the [unique] subscribers/connections that are served through this
+proxy.  The information includes
+* the TLLI on BSS side
+* the TLLI on SGSN side (may be different due to P-TMSI rewriting)
+* the NSEI of the SGSN for this link
+* a timestamp when we last conversed with this subscriber
+* state related to IMSI acquisition
+** a temporary queue of stored messages (until IMSI acquisition succeeds)
+** N(U) rewriting state (inserting IDENTTIY REQ changes LLC sequence numbers)
+=== gbproxy_match
+A single matching rule against which IMSIs are matched.  The matching rule
+is expressed as regular expression.  There can be one such matching rule for
+* routing between two different SGSNs, see below
+* patching of messages (e.g. APN, PLMN)
+== Advanced Features
+=== PLMN patching
+This feature permits to modify the PLMN inside any BSSGP messages
+containing the Routing Area ID (RAID).
+The configured core-mcc and core-mnc will be used towards the SGSN,
+irrespective of which MCC/MNC the PCU is using/reporting on Gb.
+=== APN patching
+This will transparently re-write the APN name inside SM ACTIVATE PDP
+REQUEST messages on the way from the MS to the SGSN.  The patching is
+performed based on matching on the IMSI of the subscriber.
+The configured core-apn will be used towards the SGSN, irrespective
+of which APN the MS is requesting in its Layer3 signaling.
+APN patching can only be performed if no GPRS encryption is enabled in
+the network!
+APN patching is useful in case a valid APN cannot reliably be
+provisioned via other means, such as via the SIM Card, OTA-DM or via
+CAMEL rewriting in the SGSN.
+=== P-TMSI patching
+This feature transparently rewrite the P-TMSI between MS and SGSN.  This
+is required when using the Secondary SGSN support, as both SGSNs could
+allocate overlapping TMSIs and we must make sure they're unique across
+both SGSNs.
+P-TMSI patching is required by (and hence automatically enablede if
+secondary SGSN support is enabled.
+P-TMSI patching can only be performed if no GPRS encryption is enabled in
+the network!
+=== IMSI Acquisition
+This is a special feature where the proxy will by itself inject GMM IDENTITY
+REQUEST messages for the IMSI into the downlink BSSGP traffic in order
+to establish the IMSI of subscribers for which it is not otherwise known
+IMSI acquisition is automatically enabled if secondary SGSN support is
+=== Secondary SGSN Support
+This allows the proxy to connect not only to one SGSN, but to two
+different SGSNs.  IMSI matching rules are applied to determine which of
+the SGSNs is to be used for traffic of this subscriber.
+One possible use case of this feature is to have a "local break-out" for
+subscribers who are native to this network (and hence save
+latencies/overhead of back-hauling all related traffic via the
+SGSN+GGSN) while at the same time maintaining the classic behavior for
+inbound roaming subscribers, where the roaming agreements mandate that
+data traffic is brought back to the GGSN in the HPLMN via the SGSN of
+the VPLMN.
diff --git a/doc/manuals/osmogbproxy-usermanual-docinfo.xml b/doc/manuals/osmogbproxy-usermanual-docinfo.xml
new file mode 100644
index 0000000..29bb2aa
--- /dev/null
+++ b/doc/manuals/osmogbproxy-usermanual-docinfo.xml
@@ -0,0 +1,46 @@
+  <revision>
+    <revnumber>1</revnumber>
+    <date>March 21, 2019</date>
+    <authorinitials>HW</authorinitials>
+    <revremark>
+      Initial version.
+    </revremark>
+  </revision>
+  <author>
+    <firstname>Harald</firstname>
+    <surname>Welte</surname>
+    <email>hwelte at</email>
+    <authorinitials>HW</authorinitials>
+    <affiliation>
+      <shortaffil>sysmocom</shortaffil>
+      <orgname>sysmocom - s.f.m.c. GmbH</orgname>
+      <jobtitle>Managing Director</jobtitle>
+    </affiliation>
+  </author>
+  <year>2013-2019</year>
+  <holder>sysmocom - s.f.m.c. GmbH</holder>
+  <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 no Invariant Sections, 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="">
+	</ulink>
+  </para>
diff --git a/doc/manuals/osmogbproxy-usermanual.adoc b/doc/manuals/osmogbproxy-usermanual.adoc
new file mode 100644
index 0000000..0b5bed9
--- /dev/null
+++ b/doc/manuals/osmogbproxy-usermanual.adoc
@@ -0,0 +1,38 @@
+OsmoGbPROXY User Manual
+Harald Welte <hwelte at>

To view, visit
To unsubscribe, or for help writing mail filters, visit

Gerrit-Project: osmo-sgsn
Gerrit-Branch: master
Gerrit-MessageType: newchange
Gerrit-Change-Id: I80d4ea016376c59995ccfcd8685c7c0e86745bd2
Gerrit-Change-Number: 13763
Gerrit-PatchSet: 1
Gerrit-Owner: Harald Welte <laforge at>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <>

More information about the gerrit-log mailing list