From 1fd50d9abe024b6caf221a0ea67b555b31e42f8e Mon Sep 17 00:00:00 2001 From: Harald Welte Date: Thu, 21 Mar 2019 22:52:44 +0100 Subject: 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 --- doc/manuals/Makefile.am | 4 +- doc/manuals/chapters/gbproxy-configuration.adoc | 6 ++ doc/manuals/chapters/gbproxy-control.adoc | 29 ++++++ doc/manuals/chapters/gbproxy-overview.adoc | 127 ++++++++++++++++++++++++ doc/manuals/chapters/gbproxy-running.adoc | 39 ++++++++ doc/manuals/osmogbproxy-usermanual-docinfo.xml | 46 +++++++++ doc/manuals/osmogbproxy-usermanual.adoc | 34 +++++++ 7 files changed, 284 insertions(+), 1 deletion(-) create mode 100644 doc/manuals/chapters/gbproxy-configuration.adoc create mode 100644 doc/manuals/chapters/gbproxy-control.adoc create mode 100644 doc/manuals/chapters/gbproxy-overview.adoc create mode 100644 doc/manuals/chapters/gbproxy-running.adoc create mode 100644 doc/manuals/osmogbproxy-usermanual-docinfo.xml create mode 100644 doc/manuals/osmogbproxy-usermanual.adoc diff --git a/doc/manuals/Makefile.am b/doc/manuals/Makefile.am index 4c6b847bb..72e8c77e4 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 \ 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-configuration.adoc b/doc/manuals/chapters/gbproxy-configuration.adoc new file mode 100644 index 000000000..599b3f7ba --- /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 000000000..afe23adfe --- /dev/null +++ b/doc/manuals/chapters/gbproxy-control.adoc @@ -0,0 +1,29 @@ +[[control]] +== Control interface + +The actual protocol is described in <>, the variables +common to all programs using it are described in <>. Here we +describe variables specific to OsmoGbPROXY. + +.Variables available over control interface +[options="header",width="100%",cols="20%,5%,5%,50%,20%"] +|=== +|Name|Access|Trap|Value|Comment +|nsvc-state|RO|No|",,,,,,"|See <> for details. +|gbproxy-state|RO|No|",,,,,,"|See <> for details. +|number-of-peers|RO|No|""|Count of concurrent BSS(BTS) peers. +|=== + +[[nsvc_state]] +=== 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]] +=== 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 000000000..580afae61 --- /dev/null +++ b/doc/manuals/chapters/gbproxy-overview.adoc @@ -0,0 +1,127 @@ +[[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 + +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 +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/chapters/gbproxy-running.adoc b/doc/manuals/chapters/gbproxy-running.adoc new file mode 100644 index 000000000..cac54bef4 --- /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 +options: + + +=== SYNOPSIS + +*osmo-gbproxy* [-h|-V] [-d 'DBGMASK'] [-D] [-c 'CONFIGFILE'] [-s] [-e 'LOGLEVEL'] [-T] + + +=== OPTIONS + +*-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 <> 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 <> + 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 + <> 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 + <> for more information. diff --git a/doc/manuals/osmogbproxy-usermanual-docinfo.xml b/doc/manuals/osmogbproxy-usermanual-docinfo.xml new file mode 100644 index 000000000..29bb2aa74 --- /dev/null +++ b/doc/manuals/osmogbproxy-usermanual-docinfo.xml @@ -0,0 +1,46 @@ + + + 1 + March 21, 2019 + HW + + Initial version. + + + + + + + Harald + Welte + hwelte@sysmocom.de + HW + + sysmocom + sysmocom - s.f.m.c. GmbH + Managing Director + + + + + + 2013-2019 + sysmocom - s.f.m.c. GmbH + + + + + 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". + + + The Asciidoc source code of this manual can be found at + + https://git.osmocom.org/osmo-sgsn/doc/ + + + diff --git a/doc/manuals/osmogbproxy-usermanual.adoc b/doc/manuals/osmogbproxy-usermanual.adoc new file mode 100644 index 000000000..c4e0b9d0b --- /dev/null +++ b/doc/manuals/osmogbproxy-usermanual.adoc @@ -0,0 +1,34 @@ +:gfdl-enabled: + +OsmoGbPROXY User Manual +======================= +Harald Welte + + +include::./common/chapters/preface.adoc[] + +include::{srcdir}/chapters/gbproxy-overview.adoc[] + +include::{srcdir}/chapters/gbproxy-running.adoc[] + +include::{srcdir}/chapters/gbproxy-control.adoc[] + +include::./common/chapters/vty.adoc[] + +include::./common/chapters/logging.adoc[] + +include::{srcdir}/chapters/gbproxy-configuration.adoc[] + +include::./common/chapters/gb.adoc[] + +include::./common/chapters/control_if.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[] -- cgit v1.2.3