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 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 <<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
+[options="header",width="100%",cols="20%,5%,5%,50%,20%"]
+|===
+|Name|Access|Trap|Value|Comment
+|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]]
+=== 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 <<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 000000000..29bb2aa74
--- /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@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 000000000..c4e0b9d0b
--- /dev/null
+++ b/doc/manuals/osmogbproxy-usermanual.adoc
@@ -0,0 +1,34 @@
+:gfdl-enabled:
+
+OsmoGbPROXY User Manual
+=======================
+Harald Welte <hwelte@sysmocom.de>
+
+
+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[]