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
This commit is contained in:
parent
d334be24fa
commit
a5ad7a41c4
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
@ -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).
|
||||
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
|
|
@ -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>
|
||||
|
|
@ -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[]
|
||||
Loading…
Reference in New Issue