1 files changed, 82 insertions, 0 deletions
diff --git a/doc/manuals/chapters/running.adoc b/doc/manuals/chapters/running.adoc
new file mode 100644
index 0000000..83470e8
--- /dev/null
+++ b/doc/manuals/chapters/running.adoc
@@ -0,0 +1,82 @@
+== 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 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.
+
+=== 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
+----