summaryrefslogtreecommitdiffstats
path: root/OsmoGGSN/chapters/configuration.adoc
diff options
context:
space:
mode:
Diffstat (limited to 'OsmoGGSN/chapters/configuration.adoc')
-rw-r--r--OsmoGGSN/chapters/configuration.adoc335
1 files changed, 0 insertions, 335 deletions
diff --git a/OsmoGGSN/chapters/configuration.adoc b/OsmoGGSN/chapters/configuration.adoc
deleted file mode 100644
index 657a014..0000000
--- a/OsmoGGSN/chapters/configuration.adoc
+++ /dev/null
@@ -1,335 +0,0 @@
-== 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
-----