From 8a1e7b8658a8dc65950c15b716f4ebaaa66a58c2 Mon Sep 17 00:00:00 2001 From: Harald Welte Date: Wed, 6 Sep 2017 12:35:04 +0200 Subject: initial version of OsmoGGSN user manual Closes: OS#1721 Change-Id: I7cdf150e8dd4f9dfc5e6d28e780d05dc1e1e5458 --- doc/manuals/Makefile | 13 ++ doc/manuals/chapters/configuration.adoc | 243 ++++++++++++++++++++++++++++ doc/manuals/chapters/overview.adoc | 145 +++++++++++++++++ doc/manuals/chapters/running.adoc | 41 +++++ doc/manuals/osmoggsn-usermanual-docinfo.xml | 46 ++++++ doc/manuals/osmoggsn-usermanual.adoc | 29 ++++ 6 files changed, 517 insertions(+) create mode 100644 doc/manuals/Makefile create mode 100644 doc/manuals/chapters/configuration.adoc create mode 100644 doc/manuals/chapters/overview.adoc create mode 100644 doc/manuals/chapters/running.adoc create mode 100644 doc/manuals/osmoggsn-usermanual-docinfo.xml create mode 100644 doc/manuals/osmoggsn-usermanual.adoc 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 @@ + + + 1 + August 2017 + HW + + Initial version. + + + + + + + Harald + Welte + hwelte@sysmocom.de + HW + + sysmocom + sysmocom - s.f.m.c. GmbH + Managing Director + + + + + + 2013-2017 + 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 + + http://git.osmocom.org/osmo-gsm-manuals/ + + + 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 + + +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[] -- cgit v1.2.3