Harald Welte | 8a1e7b8 | 2017-09-06 12:35:04 +0200 | [diff] [blame] | 1 | == Configuring OsmoGGSN |
| 2 | |
| 3 | All configuration of OsmoGGSN is performed using the VTY. For more |
Max | a4cb026 | 2017-09-22 14:36:51 +0200 | [diff] [blame^] | 4 | general information on the VTY interface, see <<vty>>. |
Harald Welte | 8a1e7b8 | 2017-09-06 12:35:04 +0200 | [diff] [blame] | 5 | |
| 6 | === Configuring a virtual GGSN instance |
| 7 | |
| 8 | OsmoGGSN can run multiple GGSN instances inside one program/process. |
| 9 | Each GGSN instance binds to its own transport-layer GTP IP address and |
| 10 | has its own set of APNs and associated IP address pools + tun/gtp |
| 11 | devices. |
| 12 | |
| 13 | In most usage cases, yo will only have a single GGSN instance inside |
| 14 | your configuration file, like in below example: |
| 15 | |
| 16 | .Example: Single GGSN configuration section |
| 17 | ---- |
| 18 | ggsn ggsn0 |
| 19 | gtp state-dir /tmp |
| 20 | gtp bind-ip 127.0.0.6 |
| 21 | apn internet |
| 22 | gtpu-mode tun |
| 23 | tun-device tun4 |
| 24 | type-support v4 |
| 25 | ip prefix dynamic 176.16.222.0/24 |
| 26 | ip dns 0 192.168.100.1 |
| 27 | ip dns 1 8.8.8.8 |
| 28 | ip ifconfig 176.16.222.0/24 |
| 29 | no shutdown |
| 30 | ---- |
| 31 | |
| 32 | |
| 33 | ==== Creating/Editing a GGSN instance |
| 34 | |
| 35 | Creating/Editing a GGSN instance can be done by the following sequence |
| 36 | of VTY commands: |
| 37 | |
| 38 | ---- |
| 39 | OsmoGGSN> enable <1> |
| 40 | OsmoGGSN# configure terminal <2> |
| 41 | OsmoGGSN(config)# ggsn ggsn0 <3> |
| 42 | OsmoGGSN(config-ggsn)# <4> |
| 43 | ---- |
| 44 | <1> Change into privileged mode |
| 45 | <2> Enter the interactive configuration mode |
| 46 | <3> Create or edit the GGSN instance `ggsn0`. The name can be any ASCII |
| 47 | string, its significance is only to the local user. |
| 48 | <4> Your prompt is now in the `ggsn` config node, where you can |
| 49 | configure the properties of this GGSN instance. |
| 50 | |
| 51 | NOTE:: After creating a new GGSN instance, it is in `shutdown` mode. See |
Max | a4cb026 | 2017-09-22 14:36:51 +0200 | [diff] [blame^] | 52 | <<unshutdown_apn>> to take it out of shutdown, but make sure to configure it fully |
Harald Welte | 8a1e7b8 | 2017-09-06 12:35:04 +0200 | [diff] [blame] | 53 | before taking it out of shutdown. |
| 54 | |
| 55 | ==== Configuring a GGSN instance |
| 56 | |
| 57 | The following two mandatory configuration statements have to be given |
| 58 | for every GGSN instance: |
| 59 | |
| 60 | ---- |
| 61 | OsmoGGSN(config-ggsn)# gtp state-dir /var/lib/ggsn/ggsn0 <1> |
| 62 | OsmoGGSN(config-ggsn)# gtp bind-ip 127.0.0.6 <2> |
| 63 | ---- |
| 64 | <1> Store the GSN restart state in the specified directory |
| 65 | <2> Bind the GGSN instance to the specified local IPv4 address |
| 66 | |
| 67 | There are some further configuration statements that can be used at the |
| 68 | GGSN node, some examples are given below. For a full list, see the |
Max | a4cb026 | 2017-09-22 14:36:51 +0200 | [diff] [blame^] | 69 | _OsmoGGSN VTY reference manual_ <<vty-ref-osmoggsn>>. |
Harald Welte | 8a1e7b8 | 2017-09-06 12:35:04 +0200 | [diff] [blame] | 70 | |
| 71 | ---- |
| 72 | OsmoGGSN(config-ggsn)# default-apn foobar <1> |
| 73 | ---- |
| 74 | <1> Configure a default APN to be used if the user-requested APN is not |
| 75 | found. The named APN must previously be configured |
| 76 | |
| 77 | |
| 78 | ==== Deleting a GGSN instance |
| 79 | |
| 80 | A GGSN instance can be removed like this |
| 81 | |
| 82 | .Example: Deleting a GGSN instance |
| 83 | ---- |
| 84 | OsmoGGSN> enable <1> |
| 85 | OsmoGGSN# configure terminal <2> |
| 86 | OsmoGGSN(config)# no ggsn ggsn0 <3> |
| 87 | ---- |
| 88 | <1> Change into privileged mode |
| 89 | <2> Enter the interactive configuration mode |
| 90 | <3> Delete the GGSN instance |
| 91 | |
| 92 | |
| 93 | ==== Taking a GGSN instance out of shutdown |
| 94 | |
| 95 | .Example: Taking a GGSN instance out of shutdown |
| 96 | ---- |
| 97 | OsmoGGSN> enable <1> |
| 98 | OsmoGGSN# configure terminal <2> |
| 99 | OsmoGGSN(config)# ggsn ggsn0 <3> |
| 100 | OsmoGGSN(config-ggsn)# no shutdown ggsn <4> |
| 101 | ---- |
| 102 | <1> Change into privileged mode |
| 103 | <2> Enter the interactive configuration mode |
| 104 | <3> Enter the config ndoe of the GGSN instance `ggsn0` |
| 105 | <4> Take the GGSN instance out of shutdown |
| 106 | |
| 107 | |
| 108 | ==== Shutting a GGSN instance down |
| 109 | |
| 110 | If you would like to take a GGSN instance out of service, you can |
| 111 | put it into shutdown mode. This will make the entire GGSN unavailable |
| 112 | to user traffic and permit you to e.g. reconfigure it before taking it |
| 113 | out of shutdown again. |
| 114 | |
| 115 | .Example: Shutting down a GGSN instance |
| 116 | ---- |
| 117 | OsmoGGSN> enable <1> |
| 118 | OsmoGGSN# configure terminal <2> |
| 119 | OsmoGGSN(config)# ggsn ggsn0 <3> |
| 120 | OsmoGGSN(config-ggsn)# shutdown ggsn <4> |
| 121 | ---- |
| 122 | <1> Change into privileged mode |
| 123 | <2> Enter the interactive configuration mode |
| 124 | <3> Enter the config ndoe of the GGSN instance `ggsn0` |
| 125 | <4> Shut down the GGSN instance |
| 126 | |
| 127 | |
| 128 | === Configuring an Access Point Name |
| 129 | |
| 130 | An Access Point Name (APN) represents a connection to an external packet |
| 131 | data network, such as the public Internet or private corporate networsk. |
| 132 | |
| 133 | APNs are selected by terminals (MS/UE) when establishing PDP contexts. |
| 134 | |
| 135 | Each OsmoGGSN GGSN instance can have any number of APNs configured. |
| 136 | Each APN is identified by a string name. |
| 137 | |
| 138 | ==== Creating/Editing an APN |
| 139 | |
| 140 | .Example: Creating a new APN |
| 141 | ---- |
| 142 | OsmoGGSN> enable <1> |
| 143 | OsmoGGSN# configure terminal <2> |
| 144 | OsmoGGSN(config)# ggsn ggsn0 <3> |
| 145 | OsmoGGSN(config-ggsn)# apn internet <4> |
| 146 | OsmoGGSN(config-ggsn-apn)# <5> |
| 147 | ---- |
| 148 | <1> Change into privileged mode |
| 149 | <2> Enter the interactive configuration mode |
| 150 | <3> Enter the config node of the GGSN instance `ggsn0` |
| 151 | <4> Create or Edit an APN called `internet` |
| 152 | <5> Your prompt is now in the `ggsn` config node, where you can |
| 153 | configure the properties of this GGSN instance. |
| 154 | |
Max | a4cb026 | 2017-09-22 14:36:51 +0200 | [diff] [blame^] | 155 | NOTE:: The newly-create APN is created in `shutdown` mode. See <<unshutdown_apn>> to take it |
Harald Welte | 8a1e7b8 | 2017-09-06 12:35:04 +0200 | [diff] [blame] | 156 | out of shutdown. |
| 157 | |
| 158 | |
| 159 | ==== Configuring an APN |
| 160 | |
| 161 | .Example: Configuring an APN |
| 162 | ---- |
| 163 | OsmoGGSN(config-ggsn-apn)# gtpu-mode tun <1> |
| 164 | OsmoGGSN(config-ggsn-apn)# type-support v4 <2> |
| 165 | OsmoGGSN(config-ggsn-apn)# ip prefix dynamic 176.16.222.0/24 <3> |
| 166 | OsmoGGSN(config-ggsn-apn)# ip dns 0 192.168.100.1 <4> |
| 167 | OsmoGGSN(config-ggsn-apn)# ip dns 1 8.8.8.8 <5> |
| 168 | OsmoGGSN(config-ggsn-apn)# ip ifconfig 176.16.222.0/24 <6> |
| 169 | ---- |
| 170 | <1> Use the userspace GTP-U handling using a TUN device |
| 171 | <2> Support (only) IPv4 Addresses |
| 172 | <3> Specify the pool of dynamic IPv4 addresses to be allocated to PDP |
| 173 | contexts |
| 174 | <4> Specify the primary DNS server to be provided using IPCP/PCO |
| 175 | <5> Specify the secondary DNS server to be provided using IPCP/PCO |
| 176 | <6> Request OsmoGGSN to configure the `tun4` device network/netmask |
| 177 | |
| 178 | NOTE:: If you use the optional `ip ifconfig` command to set the network |
| 179 | device address/mask, OsmoGGSN must run with root or `CAP_NET_ADMIN` |
| 180 | support. It might be better to configure related tun devices at system |
Max | a4cb026 | 2017-09-22 14:36:51 +0200 | [diff] [blame^] | 181 | startup and run OsmoGGSN as non-privileged user. See <<ggsn_no_root>> for more |
Harald Welte | 8a1e7b8 | 2017-09-06 12:35:04 +0200 | [diff] [blame] | 182 | details. |
| 183 | |
| 184 | |
| 185 | ==== Deleting an APN |
| 186 | |
| 187 | An APN configuration can be removed like this |
| 188 | |
| 189 | .Example: Deleting an APN |
| 190 | ---- |
| 191 | OsmoGGSN> enable <1> |
| 192 | OsmoGGSN# configure terminal <2> |
| 193 | OsmoGGSN(config)# ggsn ggsn0 <3> |
| 194 | OsmoGGSN(config-ggsn)# no apn internet <4> |
| 195 | ---- |
| 196 | <1> Change into privileged mode |
| 197 | <2> Enter the interactive configuration mode |
| 198 | <3> Enter the config node of the GGSN instance `ggsn0` |
| 199 | <4> Delete the APN `internet` |
| 200 | |
Max | a4cb026 | 2017-09-22 14:36:51 +0200 | [diff] [blame^] | 201 | [[unshutdown_apn]] |
Harald Welte | 8a1e7b8 | 2017-09-06 12:35:04 +0200 | [diff] [blame] | 202 | ==== Taking an APN out of shutdown |
| 203 | |
| 204 | In order to bring a deactived APN in `shutdown` state into active |
| 205 | operation, use the `no shutdown` command at the APN node as explained in |
| 206 | the following example: |
| 207 | |
| 208 | .Example: Taking an APN out of shutdown |
| 209 | ---- |
| 210 | OsmoGGSN> enable <1> |
| 211 | OsmoGGSN# configure terminal <2> |
| 212 | OsmoGGSN(config)# ggsn ggsn0 <3> |
| 213 | OsmoGGSN(config-ggsn)# apn internet <4> |
| 214 | OsmoGGSN(config-ggsn-apn)# no shutdown <5> |
| 215 | ---- |
| 216 | <1> Change into privileged mode |
| 217 | <2> Enter the interactive configuration mode |
| 218 | <3> Enter the config ndoe of the GGSN instance `ggsn0` |
| 219 | <4> Enter the config ndoe of the APN `internet` |
| 220 | <5> Take the APN out of shutdown |
| 221 | |
| 222 | |
| 223 | ==== Shutting an APN down |
| 224 | |
| 225 | If you would like to take an APN instance out of service, you can |
| 226 | put it into shutdown mode. This will make the APN unavailable |
| 227 | to user traffic and permit you to e.g. reconfigure it before taking it |
| 228 | out of shutdown again. |
| 229 | |
| 230 | .Example: Shutting down an APN |
| 231 | ---- |
| 232 | OsmoGGSN> enable <1> |
| 233 | OsmoGGSN# configure terminal <2> |
| 234 | OsmoGGSN(config)# ggsn ggsn0 <3> |
| 235 | OsmoGGSN(config-ggsn)# apn internet <4> |
| 236 | OsmoGGSN(config-ggsn-apn)# shutdown <5> |
| 237 | ---- |
| 238 | <1> Change into privileged mode |
| 239 | <2> Enter the interactive configuration mode |
| 240 | <3> Enter the config ndoe of the GGSN instance `ggsn0` |
| 241 | <4> Enter the config ndoe of the APN `internet` |
| 242 | <5> Shut down the APN |
| 243 | |
Max | a4cb026 | 2017-09-22 14:36:51 +0200 | [diff] [blame^] | 244 | [[ggsn_no_root]] |
| 245 | === Configuring for running without root priveleges |
| 246 | |
| 247 | It's possible to run OsmoGGSN without root privileges if the tun devices are already configured. |
| 248 | |
| 249 | .Example: device config via systemd-networkd using ggsn.netdev |
| 250 | ---- |
| 251 | [NetDev] |
| 252 | Name=ggsn |
| 253 | Kind=tun |
| 254 | |
| 255 | [Tun] |
| 256 | User=username |
| 257 | Group=username |
| 258 | ---- |
| 259 | |
| 260 | .Example: network settings via systemd-networkd using ggsn.network |
| 261 | ---- |
| 262 | [Match] |
| 263 | Name=ggsn |
| 264 | |
| 265 | [Network] |
| 266 | Address=192.168.7.1 |
| 267 | IPMasquerade=yes |
| 268 | ---- |
| 269 | |
| 270 | The pair of the configuration files above allows you to create and configure tun device which can be |
| 271 | used by OsmoGGSN as follows. |
| 272 | |
| 273 | .Example: using externally configured tun device as non-root |
| 274 | ---- |
| 275 | ggsn ggsn0 |
| 276 | gtp state-dir /tmp |
| 277 | gtp bind-ip 127.0.0.6 |
| 278 | apn internet |
| 279 | gtpu-mode tun |
| 280 | tun-device ggsn |
| 281 | type-support v4 |
| 282 | ip prefix dynamic 192.168.7.0/24 |
| 283 | ip dns 0 192.168.100.1 |
| 284 | ip dns 1 8.8.8.8 |
| 285 | no shutdown |
| 286 | default-apn internet |
| 287 | no shutdown ggsn |
| 288 | ---- |