diff options
Diffstat (limited to 'doc/manuals/chapters/configuration.adoc')
| -rw-r--r-- | doc/manuals/chapters/configuration.adoc | 335 |
1 files changed, 335 insertions, 0 deletions
diff --git a/doc/manuals/chapters/configuration.adoc b/doc/manuals/chapters/configuration.adoc new file mode 100644 index 0000000..657a014 --- /dev/null +++ b/doc/manuals/chapters/configuration.adoc @@ -0,0 +1,335 @@ +== 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 +---- |