== Running OsmoGGSN

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 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.

=== Routing

Operating the OpenGGSN tun device naturally creates a network setup with
multiple interfaces. Consider:

* Typical Linux setups prevent forwarding of packets between separate
  interfaces by default. To let subscribers reach the internet uplink from the
  tun device, it may be required to enable IP forwarding.

* Having a locally defined address range assigned to the tun device requires
  either sensible routing for this address range, or that masquerading is
  enabled to allow your single uplink IP address to "proxy" for the tun.

These are decisions to be made on a network administration level.

In a trivial case where you have a single box serving GPRS to few subscribers
on an arbitrary IP address range not known in the larger network, the easiest
way to enable GPRS uplink would be to enable IP forwarding and masquerading.

To manually enable IPv4 forwarding and masquerading ad-hoc, you can do:

----
sh -c "echo 1 > /proc/sys/net/ipv4/ip_forward"
iptables -t nat -A POSTROUTING -o '*' -j MASQUERADE
----

(You may want to replace `*` with the network device name, like `-o eth0`)

There are various ways to enable these settings persistently, please refer to
your distribution's documentation -- e.g. look for @net.ipv4.ip_forward=1@ in
@/etc/sysctl.d/@, and https://wiki.debian.org/iptables for masquerading.

=== 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
----

Also make sure to place each instance's GTP bind on a separate IP address (GTP
uses a port number that is fixed in the GTP specifications, so it will not be
possible to pick differing ports on the same IP address), like:

----
ggsn ggsn0
 gtp bind-ip 127.0.0.2
----

=== GTP-U kernel module

WARNING: As of writing, IPv6 support for the kernel module has not been
         upstreamed yet (OS#1952).

WARNING: As of writing, it is not possible to configure multiple APNs with
         gtpu-mode kernel-gpt. This is a limitation in OsmoGGSN, not in the
         kernel module (OS#6106).

OsmoGGSN has support to use the Linux kernel GTP-U tunnel driver to accelerate
the data/user plane while still implementing the control plane (GTP-C) in
userspace in OsmoGGSN. The kernel module is included in Linux 4.7.0 and higher.
Notably the Debian GNU/Linux distribution has it enabled by default.

In order to use this feature, make sure that your Linux kernel was configured
to support it (`CONFIG_GTP=m` or `=y`). Furthermore, `osmo-ggsn` must have been
built with `./configure` argument `--enable-gtp-linux` (which requires libgtpnl
to be installed).

Load the kernel module with:

----
$ sudo modprobe gtp
----

Then start OsmoGGSN with a configuration file that uses `gtpu-mode kernel-gtp`.

A full example configuration is in `osmo-ggsn-kernel-gtp.cfg`.

----
$ sudo osmo-ggsn -c /usr/share/doc/osmo-ggsn/examples/osmo-ggsn-kernel-gtp.cfg
----

.Example: APN with kernel-gtp
----
ggsn ggsn0
 gtp state-dir /tmp
 gtp bind-ip 127.0.0.2
 apn internet
  gtpu-mode kernel-gtp
  tun-device tun4
  type-support v4
  ip prefix dynamic 172.16.222.0/24
  ip dns 0 8.8.8.8
  ip dns 1 8.8.4.4
  ip ifconfig 172.16.222.0/24
  no shutdown
----