Change in osmo-sgsn[master]: WIP: OsmoGbPROXY user 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
Tue Apr 23 20:49:13 UTC 2019 

Harald Welte has uploaded this change for review. ( https://gerrit.osmocom.org/13763


Change subject: WIP: OsmoGbPROXY user manual
......................................................................

WIP: OsmoGbPROXY user manual

Change-Id: I80d4ea016376c59995ccfcd8685c7c0e86745bd2
---
M doc/manuals/Makefile.am
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://gerrit.osmocom.org:29418/osmo-sgsn refs/changes/63/13763/1

diff --git a/doc/manuals/Makefile.am b/doc/manuals/Makefile.am
index 00a08c8..f11acb3 100644
--- a/doc/manuals/Makefile.am
+++ b/doc/manuals/Makefile.am
@@ -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 \
     vty
 
 if BUILD_MANUALS
-  ASCIIDOC = osmosgsn-usermanual.adoc
+  ASCIIDOC = osmosgsn-usermanual.adoc osmogbproxy-usermanual.adoc
   ASCIIDOC_DEPS = $(srcdir)/chapters/*.adoc
   include $(OSMO_GSM_MANUALS_DIR)/build/Makefile.asciidoc.inc
 
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 @@
+[[chapter_overview]]
+== 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
+each
+
+* 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
+enabled.
+
+=== 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 @@
+<revhistory>
+  <revision>
+    <revnumber>1</revnumber>
+    <date>March 21, 2019</date>
+    <authorinitials>HW</authorinitials>
+    <revremark>
+      Initial version.
+    </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>2013-2019</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 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="https://git.osmocom.org/osmo-sgsn/doc/">
+		https://git.osmocom.org/osmo-sgsn/doc/
+	</ulink>
+  </para>
+</legalnotice>
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 @@
+:gfdl-enabled:
+
+OsmoGbPROXY User Manual
+====================
+Harald Welte <hwelte at sysmocom.de>
+
+
+include::./common/chapters/preface.adoc[]
+
+//include::{srcdir}/chapters/overview.adoc[]
+
+//include::{srcdir}/chapters/running.adoc[]
+
+//include::{srcdir}/chapters/control.adoc[]
+
+include::./common/chapters/vty.adoc[]
+
+include::./common/chapters/logging.adoc[]
+
+//include::{srcdir}/chapters/configuration.adoc[]
+
+include::./common/chapters/gb.adoc[]
+
+include::./common/chapters/control_if.adoc[]
+
+//include::./common/chapters/oap.adoc[]
+
+//include::./common/chapters/gsup.adoc[]
+
+//include::{srcdir}/chapters/counters.adoc[]
+
+include::./common/chapters/port_numbers.adoc[]
+
+include::./common/chapters/bibliography.adoc[]
+
+include::./common/chapters/glossary.adoc[]
+
+include::./common/chapters/gfdl.adoc[]

-- 
To view, visit https://gerrit.osmocom.org/13763
To unsubscribe, or for help writing mail filters, visit https://gerrit.osmocom.org/settings

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 gnumonks.org>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osmocom.org/pipermail/gerrit-log/attachments/20190423/fd4a5d77/attachment.htm>

More information about the gerrit-log mailing list