initial version of OsmoGGSN user manual

Closes: OS#1721
Change-Id: I7cdf150e8dd4f9dfc5e6d28e780d05dc1e1e5458
This commit is contained in:
Harald Welte 2017-09-06 12:35:04 +02:00 committed by Neels Hofmeyr
parent b7782d4d41
commit 8a1e7b8658
6 changed files with 517 additions and 0 deletions

13
doc/manuals/Makefile Normal file
View File

@ -0,0 +1,13 @@
# XSL stylesheets downloaded from http://docbook.sourceforge.net/release/xsl/current/html/
# Makefile from BitBake/OpenEmbedded manuals
TOPDIR := ..
ASCIIDOCS := osmoggsn-usermanual
include $(TOPDIR)/build/Makefile.asciidoc.inc
include $(TOPDIR)/build/Makefile.inc
osmoggsn-usermanual.pdf: chapters/*.adoc
clean:
rm -rf $(cleanfiles)

View File

@ -0,0 +1,243 @@
== Configuring OsmoGGSN
All configuration of OsmoGGSN is performed using the VTY. For more
general information on the VTY interface, see FIXME.
=== Configuring a virtual GGSN instance
OsmoGGSN can run multiple GGSN instances inside one program/process.
Each GGSN instance binds to its own transport-layer GTP IP address and
has its own set of APNs and associated IP address pools + tun/gtp
devices.
In most usage cases, yo will only have a single GGSN instance inside
your configuration file, like in below example:
.Example: Single GGSN configuration section
----
ggsn ggsn0
gtp state-dir /tmp
gtp bind-ip 127.0.0.6
apn internet
gtpu-mode tun
tun-device tun4
type-support v4
ip prefix dynamic 176.16.222.0/24
ip dns 0 192.168.100.1
ip dns 1 8.8.8.8
ip ifconfig 176.16.222.0/24
no shutdown
----
==== Creating/Editing a GGSN instance
Creating/Editing a GGSN instance can be done by the following sequence
of VTY commands:
----
OsmoGGSN> enable <1>
OsmoGGSN# configure terminal <2>
OsmoGGSN(config)# ggsn ggsn0 <3>
OsmoGGSN(config-ggsn)# <4>
----
<1> Change into privileged mode
<2> Enter the interactive configuration mode
<3> Create or edit the GGSN instance `ggsn0`. The name can be any ASCII
string, its significance is only to the local user.
<4> Your prompt is now in the `ggsn` config node, where you can
configure the properties of this GGSN instance.
NOTE:: After creating a new GGSN instance, it is in `shutdown` mode. See
FIXME to take it out of shutdown, but make sure to configure it fully
before taking it out of shutdown.
==== Configuring a GGSN instance
The following two mandatory configuration statements have to be given
for every GGSN instance:
----
OsmoGGSN(config-ggsn)# gtp state-dir /var/lib/ggsn/ggsn0 <1>
OsmoGGSN(config-ggsn)# gtp bind-ip 127.0.0.6 <2>
----
<1> Store the GSN restart state in the specified directory
<2> Bind the GGSN instance to the specified local IPv4 address
There are some further configuration statements that can be used at the
GGSN node, some examples are given below. For a full list, see the
OpenGGSN VTY reference manual (FIXME).
----
OsmoGGSN(config-ggsn)# default-apn foobar <1>
----
<1> Configure a default APN to be used if the user-requested APN is not
found. The named APN must previously be configured
==== Deleting a GGSN instance
A GGSN instance can be removed like this
.Example: Deleting a GGSN instance
----
OsmoGGSN> enable <1>
OsmoGGSN# configure terminal <2>
OsmoGGSN(config)# no ggsn ggsn0 <3>
----
<1> Change into privileged mode
<2> Enter the interactive configuration mode
<3> Delete the GGSN instance
==== Taking a GGSN instance out of shutdown
.Example: Taking a GGSN instance out of shutdown
----
OsmoGGSN> enable <1>
OsmoGGSN# configure terminal <2>
OsmoGGSN(config)# ggsn ggsn0 <3>
OsmoGGSN(config-ggsn)# no shutdown ggsn <4>
----
<1> Change into privileged mode
<2> Enter the interactive configuration mode
<3> Enter the config ndoe of the GGSN instance `ggsn0`
<4> Take the GGSN instance out of shutdown
==== Shutting a GGSN instance down
If you would like to take a GGSN instance out of service, you can
put it into shutdown mode. This will make the entire GGSN unavailable
to user traffic and permit you to e.g. reconfigure it before taking it
out of shutdown again.
.Example: Shutting down a GGSN instance
----
OsmoGGSN> enable <1>
OsmoGGSN# configure terminal <2>
OsmoGGSN(config)# ggsn ggsn0 <3>
OsmoGGSN(config-ggsn)# shutdown ggsn <4>
----
<1> Change into privileged mode
<2> Enter the interactive configuration mode
<3> Enter the config ndoe of the GGSN instance `ggsn0`
<4> Shut down the GGSN instance
=== Configuring an Access Point Name
An Access Point Name (APN) represents a connection to an external packet
data network, such as the public Internet or private corporate networsk.
APNs are selected by terminals (MS/UE) when establishing PDP contexts.
Each OsmoGGSN GGSN instance can have any number of APNs configured.
Each APN is identified by a string name.
==== Creating/Editing an APN
.Example: Creating a new APN
----
OsmoGGSN> enable <1>
OsmoGGSN# configure terminal <2>
OsmoGGSN(config)# ggsn ggsn0 <3>
OsmoGGSN(config-ggsn)# apn internet <4>
OsmoGGSN(config-ggsn-apn)# <5>
----
<1> Change into privileged mode
<2> Enter the interactive configuration mode
<3> Enter the config node of the GGSN instance `ggsn0`
<4> Create or Edit an APN called `internet`
<5> Your prompt is now in the `ggsn` config node, where you can
configure the properties of this GGSN instance.
NOTE:: The newly-create APN is created in `shutdown` mode. See FIXME to take it
out of shutdown.
==== Configuring an APN
.Example: Configuring an APN
----
OsmoGGSN(config-ggsn-apn)# gtpu-mode tun <1>
OsmoGGSN(config-ggsn-apn)# type-support v4 <2>
OsmoGGSN(config-ggsn-apn)# ip prefix dynamic 176.16.222.0/24 <3>
OsmoGGSN(config-ggsn-apn)# ip dns 0 192.168.100.1 <4>
OsmoGGSN(config-ggsn-apn)# ip dns 1 8.8.8.8 <5>
OsmoGGSN(config-ggsn-apn)# ip ifconfig 176.16.222.0/24 <6>
----
<1> Use the userspace GTP-U handling using a TUN device
<2> Support (only) IPv4 Addresses
<3> Specify the pool of dynamic IPv4 addresses to be allocated to PDP
contexts
<4> Specify the primary DNS server to be provided using IPCP/PCO
<5> Specify the secondary DNS server to be provided using IPCP/PCO
<6> Request OsmoGGSN to configure the `tun4` device network/netmask
NOTE:: If you use the optional `ip ifconfig` command to set the network
device address/mask, OsmoGGSN must run with root or `CAP_NET_ADMIN`
support. It might be better to configure related tun devices at system
startup and run OsmoGGSN as non-privileged user. See FIXME for more
details.
==== Deleting an APN
An APN configuration can be removed like this
.Example: Deleting an APN
----
OsmoGGSN> enable <1>
OsmoGGSN# configure terminal <2>
OsmoGGSN(config)# ggsn ggsn0 <3>
OsmoGGSN(config-ggsn)# no apn internet <4>
----
<1> Change into privileged mode
<2> Enter the interactive configuration mode
<3> Enter the config node of the GGSN instance `ggsn0`
<4> Delete the APN `internet`
==== Taking an APN out of shutdown
In order to bring a deactived APN in `shutdown` state into active
operation, use the `no shutdown` command at the APN node as explained in
the following example:
.Example: Taking an APN out of shutdown
----
OsmoGGSN> enable <1>
OsmoGGSN# configure terminal <2>
OsmoGGSN(config)# ggsn ggsn0 <3>
OsmoGGSN(config-ggsn)# apn internet <4>
OsmoGGSN(config-ggsn-apn)# no shutdown <5>
----
<1> Change into privileged mode
<2> Enter the interactive configuration mode
<3> Enter the config ndoe of the GGSN instance `ggsn0`
<4> Enter the config ndoe of the APN `internet`
<5> Take the APN out of shutdown
==== Shutting an APN down
If you would like to take an APN instance out of service, you can
put it into shutdown mode. This will make the APN unavailable
to user traffic and permit you to e.g. reconfigure it before taking it
out of shutdown again.
.Example: Shutting down an APN
----
OsmoGGSN> enable <1>
OsmoGGSN# configure terminal <2>
OsmoGGSN(config)# ggsn ggsn0 <3>
OsmoGGSN(config-ggsn)# apn internet <4>
OsmoGGSN(config-ggsn-apn)# shutdown <5>
----
<1> Change into privileged mode
<2> Enter the interactive configuration mode
<3> Enter the config ndoe of the GGSN instance `ggsn0`
<4> Enter the config ndoe of the APN `internet`
<5> Shut down the APN

View File

@ -0,0 +1,145 @@
[[chapter_introduction]]
== Overview
[[intro_overview]]
=== About OsmoGGSN
OsmoGGSN is a Free / Open Source Software implementation of the GPRS
GGSN (Gateway GPRS support node) element in side the packet switched
core network of 2G and 3G cellular networks.
The GGSN function is the tunnel endpoint on the core network side,
from where the external (IP) packet data network
=== Software Components
==== GTP Implementation (libgtp)
The OsmoGGSN source code includes a shared library implementation of
the GTP protocol used on the GGSN-SGSN interface. This library
and associated header files are installed system-wide and are
available to other programs/applications.
In fact, libgtp is what the OsmoSGSN also uses for its use of GTP.
==== sgsnemu
In order to test OsmoGGSN without running a SGSN and other elements
of a cellular network, there is a small command-line utility called
*sgsnemu* which is able to simulate the customary operations of a SGSN
towards the GGSN, such as a PDP Context Activation.
*sgsnemu* can even be used for testing against other GGSNs, as the GTP
protocol is standardized across implementations.
==== osmo-ggsn
*osmo-ggsn* is the actual name of the OsmoGGSN executable program. It
implements the GGSN functionality. All parameters are set using the
configuration file, by default located in *./osmo-ggsn.cfg*
==== systemd service file
In *contrib/osmo-ggsn.service* you can find a sample service file for
OsmoGGSN which can be used with systemd.
==== init script
In *contrib/osmo-ggsn.init* you can find a sample init script to be used
on systems with classic init process.
=== Limitations
OsmoGGSN supports both GTP0 (GSM 09.60) and GTP1 (3GPP 29.060). In the
following tables the support of each individual message type is
detailed. The numbers before each feature indicates the relevant
section in the standard.
==== GSM 09.60 (GTPv0)
[options="header",cols="50%,15%,15%,15%,5%"]
|===
| Feature | gtplib | osmo-ggsn | sgsnemu | notes
5+<|*7.4 Path Management Messages*
|7.4.1 Echo Request |Supported |Supported |Supported |
|7.4.2 Echo Response |Supported |Supported |Supported |
|7.4.3 Version Not Supported |Supported |Supported |Supported |
5+<| *7.5 Tunnel Management Messages*
|7.5.1 Create PDP Context Request|Supported |Supported |Supported |
|7.5.2 Create PDP Context Response|Supported |Supported |Supported |
|7.5.3 Update PDP Context Request|Supported |Supported |Not |
|7.5.4 Update PDP Context Response|Supported |Supported |Not |
|7.5.5 Delete PDP Context Request|Supported |Supported |Supported |
|7.5.6 Delete PDP Context Response|Supported |Supported |Supported |
|7.5.7 Create AA PDP Context Request|Unsupported |Unsupported |Unsupported |
|7.5.8 Create AA PDP Response|Unsupported |Unsupported |Unsupported |
|7.5.9 Delete AA PDP Context Request|Unsupported |Unsupported |Unsupported |
|7.5.10 Delete AA PDP Context Response|Unsupported |Unsupported |Unsupported |
|7.5.11 Error Indication |Supported |Supported |Supported |
|7.5.12 PDU Notification Request|Unsupported |Unsupported |Unsupported |
|7.5.13 PDU Notification Response|Unsupported |Unsupported |Unsupported |
|7.5.14 PDU Notification Reject Request|Unsupported |Unsupported |Unsupported |
|7.5.15 PDU Notification Reject Response|Unsupported |Unsupported |Unsupported |
5+<| *7.6 Location Management Messages*
|7.6.1 Send Routeing Information for GPRS Request|Unsupported |Unsupported |Not applicable |
|7.6.2 Send Routeing Information for GPRS Response|Unsupported |Unsupported |Not applicable |
|7.6.3 Failure Report Request|Unsupported |Unsupported |Not applicable |
|7.6.3 Failure Report Response|Unsupported |Unsupported |Not applicable |
|7.6.5 Note MS GPRS Present Request|Unsupported |Unsupported |Not applicable|
|7.6.6 Note MS GPRS Present Response|Unsupported |Unsupported |Not applicable|
5+<| *7.5 Mobility Management Messages*
|7.5.1 Identification Request|Unsupported |Not applicable|Not applicable|
|7.5.2 Identification Response|Unsupported |Not applicable|Not applicable |
|7.5.3 SGSN Context Request|Unsupported |Not applicable|Not applicable|
|7.5.4 SGSN Context Response|Unsupported |Not applicable|Not applicable|
|7.5.5 SGSN Context Acknowledge|Unsupported |Not applicable|Not applicable|
|===
==== 3GPP 29.060 (GTPv1)
[options="header",cols="50%,15%,15%,15%,5%"]
|===
|Feature |gtplib |osmo-ggsn |sgsnemu |notes
5+<|*7.2 Path Management Messages*
|7.2.1 Echo Request |Supported |Supported |Supported |
|7.2.2 Echo Response |Supported |Supported |Supported |
|7.2.3 Version Not Supported|Supported |Supported |Supported |
|7.2.4 Extension Headers Notification|Supported |Supported |Supported |
5+<|*7.3 Tunnel Management Messages*
|7.3.1 Create PDP Context Request|Supported |Supported |Supported |1
|7.3.2 Create PDP Context Response|Supported |Supported |Supported |
|7.3.3 Update PDP Context Request|Supported |Supported |Not applicable|1
|7.3.4 Update PDP Context Response|Supported |Supported |Not applicable|
|7.3.5 Delete PDP Context Request|Supported |Supported |Supported |
|7.3.6 Delete PDP Context Response|Supported |Supported |Supported |
|7.3.7 Error Indication |Supported |Supported |Supported |
|7.3.8 PDU Notification Request|Unsupported |Unsupported |Unsupported |
|7.3.9 PDU Notification Response|Unsupported |Unsupported |Unsupported |
|7.3.10 PDU Notification Reject Request|Unsupported |Unsupported |Unsupported |
|7.3.10 PDU Notification Reject Response|Unsupported |Unsupported |Unsupported |
5+<|*7.4 Location Management Messages*
|7.4.1 Send Routeing Information for GPRS Request|Unsupported |Unsupported |Not applicable |
|7.4.2 Send Routeing Information for GPRS Response|Unsupported |Unsupported |Not applicable |
|7.4.3 Failure Report Request|Unsupported |Unsupported |Not applicable|
|7.4.3 Failure Report Response|Unsupported |Unsupported |Not applicable|
|7.4.5 Note MS GPRS Present Request|Unsupported |Unsupported |Not applicable|
|7.4.6 Note MS GPRS Present Response|Unsupported |Unsupported |Not applicable|
5+<|*7.5 Mobility Management Messages*
|7.5.1 Identification Request|Unsupported |Not applicable|Not applicable|
|7.5.2 Identification Response|Unsupported |Not applicable |Not applicable|
|7.5.3 SGSN Context Request|Unsupported |Not applicable|Not applicable|
|7.5.4 SGSN Context Response|Unsupported |Not applicable |Not applicable|
|7.5.5 SGSN Context Acknowledge|Unsupported |Not applicable|Not applicable|
|7.5.6 Forward Relocation Request|Unsupported |Not applicable|Not applicable|
|7.5.7 Forward Relocation Response|Unsupported |Not applicable|Not applicable|
|7.5.8 Forward Relocation Complete|Unsupported |Not applicable|Not applicable|
|7.5.9 Relocation Cancel Request|Unsupported |Not applicable|Not applicable|
|7.5.10 Relocation Cancel Response|Unsupported |Not applicable|Not applicable|
|7.5.11 Forward Relocation Complete |Unsupported |Not applicable |Not applicable |
|7.5.12 Forward SRNS Context Acknowledge|Unsupported |Not applicable|Not applicable|
|7.5.13 Forward SRNS Context|Unsupported |Not applicable|Not applicable|
|===
Notes
1) The "Secondary PDP Context Activation Procedure" is not supported.

View File

@ -0,0 +1,41 @@
== Running OsmoNITB
The OsmoGGSN executable (`osmo-ggsn`) offers the following command-line
arguments:
=== SYNOPSIS
*osmo-ggsn* [-h|-V] [-D] [-c 'CONFIGFILE']
=== OPTIONS
*-h, --help*::
Print a short help message about the supported options
*-V, --version*::
Print the compile-time version number of the OsmoBTS program
*-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-ggsn.cfg` in the current
working directory.
=== Multiple instances
Running multiple instances of `osmo-ggsn` is possible if all GGSN instances
are binding to different local IP addresse and all other interfaces (VTY,
OML) are separated using the appropriate configuration options. The IP based
interfaces are binding to local host by default. In order to separate the
processes, the user has to bind those services to specific but different
IP addresses.
The VTY and the control interface can be bound to IP addresses from the loopback
address range.
.Example: Binding VTY and control interface to a specific ip-address
----
line vty
bind 127.0.0.2
ctrl
bind 127.0.0.2
----

View File

@ -0,0 +1,46 @@
<revhistory>
<revision>
<revnumber>1</revnumber>
<date>August 2017</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-2017</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="http://git.osmocom.org/osmo-gsm-manuals/">
http://git.osmocom.org/osmo-gsm-manuals/
</ulink>
</para>
</legalnotice>

View File

@ -0,0 +1,29 @@
OsmoGGSN User Manual
====================
Harald Welte <hwelte@sysmocom.de>
include::../common/chapters/preface.adoc[]
include::chapters/overview.adoc[]
include::chapters/running.adoc[]
//include::chapters/control.adoc[]
include::../common/chapters/vty.adoc[]
include::../common/chapters/logging.adoc[]
include::chapters/configuration.adoc[]
include::../common/chapters/control_if.adoc[]
include::../common/chapters/port_numbers.adoc[]
include::../common/chapters/bibliography.adoc[]
include::../common/chapters/glossary.adoc[]
include::../common/chapters/gfdl.adoc[]