[[osmoggsn_configuring]] == Configuring OsmoGGSN All configuration of OsmoGGSN is performed using the VTY. For more general information on the VTY interface, see <>. === 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 /var/lib/osmocom/osmo-ggsn gtp bind-ip 127.0.0.6 apn internet gtpu-mode tun tun-device tun4 type-support v4 mtu default apply 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 <> 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/osmocom/osmo-ggsn <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_ <>. ---- 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 node 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 node 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 <> 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)# mtu 1420 apply <3> OsmoGGSN(config-ggsn-apn)# ip prefix dynamic 176.16.222.0/24 <4> OsmoGGSN(config-ggsn-apn)# ip dns 0 192.168.100.1 <5> OsmoGGSN(config-ggsn-apn)# ip dns 1 8.8.8.8 <6> OsmoGGSN(config-ggsn-apn)# ip ifconfig 176.16.222.0/24 <7> ---- <1> Use the userspace GTP-U handling using a TUN device <2> Support (only) IPv4 Addresses <3> Specify MTU to announce to MS. Apply the MTU on the tunnel interface. <4> Specify the pool of dynamic IPv4 addresses to be allocated to PDP contexts <5> Specify the primary DNS server to be provided using IPCP/PCO <6> Specify the secondary DNS server to be provided using IPCP/PCO <7> 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 <> 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 node of the GGSN instance `ggsn0` <4> Enter the config node 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 node of the GGSN instance `ggsn0` <4> Enter the config node 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.1/24 dev apn0 # ip link set mtu 1420 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> [Link] MTUBytes=1420 <2> [Network] Address=192.168.7.1/24 <3> IPMasquerade=yes <4> ---- <1> The network device name, which must match the one in the apn0.netdev unit file above <2> Requesting systemd to set the MTU for this interface. The MTU of the tun interface should be lower than regular, since it must accommodate the extra IP/UDP/GTPv1U headers. <3> The local IP address configured on the device <4> 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 mtu 1420 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 ----