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