[PATCH] osmo-gsm-manuals[master]: GGSN: Document how 'tunctl' is used for non-root; call netde...

Harald Welte gerrit-no-reply at lists.osmocom.org
Thu Oct 12 13:39:21 UTC 2017


Review at  https://gerrit.osmocom.org/4233

GGSN: Document how 'tunctl' is used for non-root; call netdev 'apn0'

* Some people want to manually create/configure their tun devices,
  show them how to do this using tunctl with the correct parameters
* Let's not call the network device 'ggsn' but rather 'apn0', as
  the device has a 1:1 correspondence to the APN, not to the GGSN.

Change-Id: I2fef818bfcb8cb521397136539f492922d5f6def
---
M OsmoGGSN/chapters/configuration.adoc
1 file changed, 46 insertions(+), 8 deletions(-)


  git pull ssh://gerrit.osmocom.org:29418/osmo-gsm-manuals refs/changes/33/4233/1

diff --git a/OsmoGGSN/chapters/configuration.adoc b/OsmoGGSN/chapters/configuration.adoc
index 9e07fb6..a7b2c36 100644
--- a/OsmoGGSN/chapters/configuration.adoc
+++ b/OsmoGGSN/chapters/configuration.adoc
@@ -246,26 +246,64 @@
 
 It's possible to run OsmoGGSN without root privileges if the tun devices are already configured.
 
-.Example: device config via systemd-networkd using ggsn.netdev
+The interface creation + configuration must then happen before osmo-ggsn starting up.  This can be
+achieved by mans such as
+
+* a custom shell script run as root before starting osmo-ggsn (e.g. as init script)
+* systemd .netdev and .netwrork files
+
+==== Manual TUN device creation / configuration
+
+If you chose to go for custom shell/init scripts, you may use the `tunctl` program which is
+available in major distributions as part of the `uml-utilities` package.  In order to create
+a tun device, you must call it like this:
+
+.Example: tunctl command to create a tun device
+----
+tunctl -3 -u username -g groupname -t apn0
+----
+
+Where _username_ and _groupname_ correspond to the User and Group that will have ownership over the
+device, i.e. the privileges using which you intend to run osmo-ggsn under, and _apn0_ will be the
+name of the network device created.  Don't forget the `-3` option, without it, `tunctl` will create
+TAP (Ethernet) devices and not TUN (IP) devices.  After creating the interface, you can configure
+its addresses using standard means like `ifconfig`, `ip` or your distribution-specific
+utilities/tools.
+
+
+==== 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=ggsn
+Name=apn0 <1>
 Kind=tun
 
 [Tun]
-User=username
-Group=username
+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=ggsn
+Name=apn0 <1>
 
 [Network]
-Address=192.168.7.1
-IPMasquerade=yes
+Address=192.168.7.1 <2>
+IPMasquerade=yes <3>
 ----
+<1> The netowrk device name, which must match the one in the apn0.netdev script 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.
 
 The pair of the configuration files above allows you to create and configure tun device which can be
 used by OsmoGGSN as follows.
@@ -277,7 +315,7 @@
  gtp bind-ip 127.0.0.6
  apn internet
   gtpu-mode tun
-  tun-device ggsn
+  tun-device apn0
   type-support v4
   ip prefix dynamic 192.168.7.0/24
   ip dns 0 192.168.100.1

-- 
To view, visit https://gerrit.osmocom.org/4233
To unsubscribe, visit https://gerrit.osmocom.org/settings

Gerrit-MessageType: newchange
Gerrit-Change-Id: I2fef818bfcb8cb521397136539f492922d5f6def
Gerrit-PatchSet: 1
Gerrit-Project: osmo-gsm-manuals
Gerrit-Branch: master
Gerrit-Owner: Harald Welte <laforge at gnumonks.org>


More information about the gerrit-log mailing list