doc/manuals/chapters/configuration.adoc

== Configuring OsmoGGSN

All configuration of OsmoGGSN is performed using the VTY. For more
general information on the VTY interface, see <<vty>>.

=== 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
<<unshutdown_apn>> 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
_OsmoGGSN VTY reference manual_ <<vty-ref-osmoggsn>>.

----
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 <<unshutdown_apn>> 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 <<ggsn_no_root>> 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`

[[unshutdown_apn]]
==== 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

[[ggsn_no_root]]
=== Configuring for running without root privileges

It's possible to run OsmoGGSN without root privileges if the tun devices are already configured.

The interface creation + configuration must then happen before osmo-ggsn starting up.  This can be
achieved by means such as

* a custom shell script run as root before starting osmo-ggsn (e.g. as init script)
* systemd .netdev and .network files, if your system is using systemd-networkd (see `networkctl status`).

==== Manual TUN device creation / configuration

If you chose to go for custom shell/init scripts, you may use the `ip` program which is the standard
tool for network interface configuration on Linux, part of the `iproute2` package.  In order to
create a tun device, you must call it like this:

.Example: iproute2 command to create a tun device
----
# ip tuntap add dev apn0 mode tun user username group groupname
----

Where _username_ and _groupname_ correspond to the User and Group that will have ownership over the
device, i.e. the privileges which you intend to run osmo-ggsn under, and _apn0_ will be the
name of the network device created.  After creating the interface, you can configure its addresses
using standard means like `ip addr add` or your distribution-specific utilities/tools
to match the `ip prefix dynamic` config item, and activate the link, for example:

----
# ip addr add 192.168.7.0/24 dev apn0
# ip link set apn0 up
----

==== systemd based TUN device creation+configuration

If you want to have systemd take care of creating and configuring a tun device for you,
you can use the below example config files.

.Example: device config via systemd-networkd using apn0.netdev
----
[NetDev]
Name=apn0 <1>
Kind=tun

[Tun]
User=username <2>
Group=username <3>
----
<1> The network interface name of the newly-created device
<2> The username under which you will run OsmoGGSN
<3> The group name under which you will run OsmoGGSN

.Example: network settings via systemd-networkd using ggsn.network
----
[Match]
Name=apn0 <1>

[Network]
Address=192.168.7.1 <2>
IPMasquerade=yes <3>
----
<1> The netowrk device name, which must match the one in the apn0.netdev unit file above
<2> The local IP address configured on the device
<3> Requesting systemd to configure IP masquerading for this interface.  Depending on your needs,
    You may not want this if you have proper end-to-end routing set up, and want to have transparent
    inbound IP access to your GPRS-attached devices.

==== Config Changes

With the tun device pre-configured in one of the ways outlined above, the main
changes in your osmo-ggsn.cfg file are:

* remove `ip ifconfig` directive,
* make sure that `no shutdown` is present in the `apn` section as well as
  `no shutdown ggsn` in the `ggsn` section.

.Example: using externally configured tun device `apn0` as non-root
----
ggsn ggsn0
 gtp state-dir /tmp
 gtp bind-ip 127.0.0.6
 apn internet
  gtpu-mode tun
  tun-device apn0
  type-support v4
  ip prefix dynamic 192.168.7.0/24
  ip dns 0 192.168.100.1
  ip dns 1 8.8.8.8
  no shutdown
 default-apn internet
 no shutdown ggsn
----