initial version of OsmoGGSN user manual

Closes: OS#1721
Change-Id: I7cdf150e8dd4f9dfc5e6d28e780d05dc1e1e5458

6 files changed, 517 insertions, 0 deletions

diff --git a/doc/manuals/Makefile b/doc/manuals/Makefile
new file mode 100644
index 0000000..daf3597
--- /dev/null
+++ b/doc/manuals/Makefile
@@ -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)
diff --git a/doc/manuals/chapters/configuration.adoc b/doc/manuals/chapters/configuration.adoc
new file mode 100644
index 0000000..e37b709
--- /dev/null
+++ b/doc/manuals/chapters/configuration.adoc
@@ -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
+
diff --git a/doc/manuals/chapters/overview.adoc b/doc/manuals/chapters/overview.adoc
new file mode 100644
index 0000000..632db5e
--- /dev/null
+++ b/doc/manuals/chapters/overview.adoc
@@ -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.
diff --git a/doc/manuals/chapters/running.adoc b/doc/manuals/chapters/running.adoc
new file mode 100644
index 0000000..cff3f8d
--- /dev/null
+++ b/doc/manuals/chapters/running.adoc
@@ -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
+----
diff --git a/doc/manuals/osmoggsn-usermanual-docinfo.xml b/doc/manuals/osmoggsn-usermanual-docinfo.xml
new file mode 100644
index 0000000..c93d5e1
--- /dev/null
+++ b/doc/manuals/osmoggsn-usermanual-docinfo.xml
@@ -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>
diff --git a/doc/manuals/osmoggsn-usermanual.adoc b/doc/manuals/osmoggsn-usermanual.adoc
new file mode 100644
index 0000000..efa2c8f
--- /dev/null
+++ b/doc/manuals/osmoggsn-usermanual.adoc
@@ -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[]