diff options
authorHarald Welte <laforge@gnumonks.org>2019-03-21 22:52:44 +0100
committerlaforge <laforge@osmocom.org>2019-12-01 12:42:58 +0000
commit1fd50d9abe024b6caf221a0ea67b555b31e42f8e (patch)
parent4146121cc996bed1fb1707a2ab8bca6786cd054d (diff)
Initial OsmoGbPROXY user manual
This adds a very basic manual consisting of nothing more than the common chapters and a high-level description of what it is all about. Change-Id: I80d4ea016376c59995ccfcd8685c7c0e86745bd2
7 files changed, 284 insertions, 1 deletions
diff --git a/doc/manuals/Makefile.am b/doc/manuals/Makefile.am
index 4c6b847b..72e8c77e 100644
--- a/doc/manuals/Makefile.am
+++ b/doc/manuals/Makefile.am
@@ -1,12 +1,14 @@
EXTRA_DIST = osmosgsn-usermanual.adoc \
osmosgsn-usermanual-docinfo.xml \
osmosgsn-vty-reference.xml \
+ osmogbproxy-usermanual.adoc \
+ osmogbproxy-usermanual-docinfo.xml \
regen_doc.sh \
chapters \
- 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-configuration.adoc b/doc/manuals/chapters/gbproxy-configuration.adoc
new file mode 100644
index 00000000..599b3f7b
--- /dev/null
+++ b/doc/manuals/chapters/gbproxy-configuration.adoc
@@ -0,0 +1,6 @@
+== Configuring OsmoGbPROXY
+TBD. Unfortunately this chapter of the manual still needs to be written.
+Osmocom has very limited funding and support resources; Feel free to help
+us completing this documentation by contributing with code, documentation
+or by supporting the developers financially.
diff --git a/doc/manuals/chapters/gbproxy-control.adoc b/doc/manuals/chapters/gbproxy-control.adoc
new file mode 100644
index 00000000..afe23adf
--- /dev/null
+++ b/doc/manuals/chapters/gbproxy-control.adoc
@@ -0,0 +1,29 @@
+== 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>>. Here we
+describe variables specific to OsmoGbPROXY.
+.Variables available over control interface
+|nsvc-state|RO|No|"<nsei>,<nsvci>,<local-alive>,<local-blocked>,<remote-role>,<remote-alive>,<remote-blocked>"|See <<nsvc_state>> for details.
+|gbproxy-state|RO|No|"<nsei>,<bvci>,<mcc>,<mnc>,<lac>,<rac>,<blocked>"|See <<gbproxy_state>> for details.
+|number-of-peers|RO|No|"<num-of-bss>"|Count of concurrent BSS(BTS) peers.
+=== nsvc-state
+Return the list of active NS-VCs (NS Virtual Circuits), including information
+on the key parameters, such as NSEI, NSVCI and the local + remote ALIVE
+and BLOCKED state.
+=== gbproxy-state
+Return the list of active Peers, including information on the key
+parameters, such as NSEI, BVCI, and the MCC-MNC-LAC-RAC of the attached
+BSS, as well as the overall state (BLOCKED or UNBLOCKED).
diff --git a/doc/manuals/chapters/gbproxy-overview.adoc b/doc/manuals/chapters/gbproxy-overview.adoc
new file mode 100644
index 00000000..580afae6
--- /dev/null
+++ b/doc/manuals/chapters/gbproxy-overview.adoc
@@ -0,0 +1,127 @@
+== 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
+This contains the parsed configuration of the OsmoGbPROXY.
+==== 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/chapters/gbproxy-running.adoc b/doc/manuals/chapters/gbproxy-running.adoc
new file mode 100644
index 00000000..cac54bef
--- /dev/null
+++ b/doc/manuals/chapters/gbproxy-running.adoc
@@ -0,0 +1,39 @@
+== Running OsmoGbPROXY
+The OsmoGbPROXY executable (`osmo-gbproxy`) offers the following command-line
+*osmo-gbproxy* [-h|-V] [-d 'DBGMASK'] [-D] [-c 'CONFIGFILE'] [-s] [-e 'LOGLEVEL'] [-T]
+*-h, --help*::
+ Print a short help message about the supported options
+*-V, --version*::
+ Print the compile-time version number of the OsmoSGSN 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 `osmo_sgsn.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.
+*-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.
+*-T, --timestamp*::
+ Enable prefixing each log line on stderr with a timestamp. This
+ has mostly been deprecated by VTY based logging configuration, see
+ <<logging>> for more information.
diff --git a/doc/manuals/osmogbproxy-usermanual-docinfo.xml b/doc/manuals/osmogbproxy-usermanual-docinfo.xml
new file mode 100644
index 00000000..29bb2aa7
--- /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@sysmocom.de</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="https://git.osmocom.org/osmo-sgsn/doc/">
+ https://git.osmocom.org/osmo-sgsn/doc/
+ </ulink>
+ </para>
diff --git a/doc/manuals/osmogbproxy-usermanual.adoc b/doc/manuals/osmogbproxy-usermanual.adoc
new file mode 100644
index 00000000..c4e0b9d0
--- /dev/null
+++ b/doc/manuals/osmogbproxy-usermanual.adoc
@@ -0,0 +1,34 @@
+OsmoGbPROXY User Manual
+Harald Welte <hwelte@sysmocom.de>