1.. SPDX-License-Identifier: GPL-2.0 2 3===================================== 4The Linux kernel GTP tunneling module 5===================================== 6 7Documentation by 8 Harald Welte <laforge@gnumonks.org> and 9 Andreas Schultz <aschultz@tpip.net> 10 11In 'drivers/net/gtp.c' you are finding a kernel-level implementation 12of a GTP tunnel endpoint. 13 14What is GTP 15=========== 16 17GTP is the Generic Tunnel Protocol, which is a 3GPP protocol used for 18tunneling User-IP payload between a mobile station (phone, modem) 19and the interconnection between an external packet data network (such 20as the internet). 21 22So when you start a 'data connection' from your mobile phone, the 23phone will use the control plane to signal for the establishment of 24such a tunnel between that external data network and the phone. The 25tunnel endpoints thus reside on the phone and in the gateway. All 26intermediate nodes just transport the encapsulated packet. 27 28The phone itself does not implement GTP but uses some other 29technology-dependent protocol stack for transmitting the user IP 30payload, such as LLC/SNDCP/RLC/MAC. 31 32At some network element inside the cellular operator infrastructure 33(SGSN in case of GPRS/EGPRS or classic UMTS, hNodeB in case of a 3G 34femtocell, eNodeB in case of 4G/LTE), the cellular protocol stacking 35is translated into GTP *without breaking the end-to-end tunnel*. So 36intermediate nodes just perform some specific relay function. 37 38At some point the GTP packet ends up on the so-called GGSN (GSM/UMTS) 39or P-GW (LTE), which terminates the tunnel, decapsulates the packet 40and forwards it onto an external packet data network. This can be 41public internet, but can also be any private IP network (or even 42theoretically some non-IP network like X.25). 43 44You can find the protocol specification in 3GPP TS 29.060, available 45publicly via the 3GPP website at http://www.3gpp.org/DynaReport/29060.htm 46 47A direct PDF link to v13.6.0 is provided for convenience below: 48http://www.etsi.org/deliver/etsi_ts/129000_129099/129060/13.06.00_60/ts_129060v130600p.pdf 49 50The Linux GTP tunnelling module 51=============================== 52 53The module implements the function of a tunnel endpoint, i.e. it is 54able to decapsulate tunneled IP packets in the uplink originated by 55the phone, and encapsulate raw IP packets received from the external 56packet network in downlink towards the phone. 57 58It *only* implements the so-called 'user plane', carrying the User-IP 59payload, called GTP-U. It does not implement the 'control plane', 60which is a signaling protocol used for establishment and teardown of 61GTP tunnels (GTP-C). 62 63So in order to have a working GGSN/P-GW setup, you will need a 64userspace program that implements the GTP-C protocol and which then 65uses the netlink interface provided by the GTP-U module in the kernel 66to configure the kernel module. 67 68This split architecture follows the tunneling modules of other 69protocols, e.g. PPPoE or L2TP, where you also run a userspace daemon 70to handle the tunnel establishment, authentication etc. and only the 71data plane is accelerated inside the kernel. 72 73Don't be confused by terminology: The GTP User Plane goes through 74kernel accelerated path, while the GTP Control Plane goes to 75Userspace :) 76 77The official homepage of the module is at 78https://osmocom.org/projects/linux-kernel-gtp-u/wiki 79 80Userspace Programs with Linux Kernel GTP-U support 81================================================== 82 83At the time of this writing, there are at least two Free Software 84implementations that implement GTP-C and can use the netlink interface 85to make use of the Linux kernel GTP-U support: 86 87* OpenGGSN (classic 2G/3G GGSN in C): 88 https://osmocom.org/projects/openggsn/wiki/OpenGGSN 89 90* ergw (GGSN + P-GW in Erlang): 91 https://github.com/travelping/ergw 92 93Userspace Library / Command Line Utilities 94========================================== 95 96There is a userspace library called 'libgtpnl' which is based on 97libmnl and which implements a C-language API towards the netlink 98interface provided by the Kernel GTP module: 99 100http://git.osmocom.org/libgtpnl/ 101 102Protocol Versions 103================= 104 105There are two different versions of GTP-U: v0 [GSM TS 09.60] and v1 106[3GPP TS 29.281]. Both are implemented in the Kernel GTP module. 107Version 0 is a legacy version, and deprecated from recent 3GPP 108specifications. 109 110GTP-U uses UDP for transporting PDUs. The receiving UDP port is 2151 111for GTPv1-U and 3386 for GTPv0-U. 112 113There are three versions of GTP-C: v0, v1, and v2. As the kernel 114doesn't implement GTP-C, we don't have to worry about this. It's the 115responsibility of the control plane implementation in userspace to 116implement that. 117 118IPv6 119==== 120 121The 3GPP specifications indicate either IPv4 or IPv6 can be used both 122on the inner (user) IP layer, or on the outer (transport) layer. 123 124Unfortunately, the Kernel module currently supports IPv6 neither for 125the User IP payload, nor for the outer IP layer. Patches or other 126Contributions to fix this are most welcome! 127 128Mailing List 129============ 130 131If you have questions regarding how to use the Kernel GTP module from 132your own software, or want to contribute to the code, please use the 133osmocom-net-grps mailing list for related discussion. The list can be 134reached at osmocom-net-gprs@lists.osmocom.org and the mailman 135interface for managing your subscription is at 136https://lists.osmocom.org/mailman/listinfo/osmocom-net-gprs 137 138Issue Tracker 139============= 140 141The Osmocom project maintains an issue tracker for the Kernel GTP-U 142module at 143https://osmocom.org/projects/linux-kernel-gtp-u/issues 144 145History / Acknowledgements 146========================== 147 148The Module was originally created in 2012 by Harald Welte, but never 149completed. Pablo came in to finish the mess Harald left behind. But 150doe to a lack of user interest, it never got merged. 151 152In 2015, Andreas Schultz came to the rescue and fixed lots more bugs, 153extended it with new features and finally pushed all of us to get it 154mainline, where it was merged in 4.7.0. 155 156Architectural Details 157===================== 158 159Local GTP-U entity and tunnel identification 160-------------------------------------------- 161 162GTP-U uses UDP for transporting PDU's. The receiving UDP port is 2152 163for GTPv1-U and 3386 for GTPv0-U. 164 165There is only one GTP-U entity (and therefor SGSN/GGSN/S-GW/PDN-GW 166instance) per IP address. Tunnel Endpoint Identifier (TEID) are unique 167per GTP-U entity. 168 169A specific tunnel is only defined by the destination entity. Since the 170destination port is constant, only the destination IP and TEID define 171a tunnel. The source IP and Port have no meaning for the tunnel. 172 173Therefore: 174 175 * when sending, the remote entity is defined by the remote IP and 176 the tunnel endpoint id. The source IP and port have no meaning and 177 can be changed at any time. 178 179 * when receiving the local entity is defined by the local 180 destination IP and the tunnel endpoint id. The source IP and port 181 have no meaning and can change at any time. 182 183[3GPP TS 29.281] Section 4.3.0 defines this so:: 184 185 The TEID in the GTP-U header is used to de-multiplex traffic 186 incoming from remote tunnel endpoints so that it is delivered to the 187 User plane entities in a way that allows multiplexing of different 188 users, different packet protocols and different QoS levels. 189 Therefore no two remote GTP-U endpoints shall send traffic to a 190 GTP-U protocol entity using the same TEID value except 191 for data forwarding as part of mobility procedures. 192 193The definition above only defines that two remote GTP-U endpoints 194*should not* send to the same TEID, it *does not* forbid or exclude 195such a scenario. In fact, the mentioned mobility procedures make it 196necessary that the GTP-U entity accepts traffic for TEIDs from 197multiple or unknown peers. 198 199Therefore, the receiving side identifies tunnels exclusively based on 200TEIDs, not based on the source IP! 201 202APN vs. Network Device 203====================== 204 205The GTP-U driver creates a Linux network device for each Gi/SGi 206interface. 207 208[3GPP TS 29.281] calls the Gi/SGi reference point an interface. This 209may lead to the impression that the GGSN/P-GW can have only one such 210interface. 211 212Correct is that the Gi/SGi reference point defines the interworking 213between +the 3GPP packet domain (PDN) based on GTP-U tunnel and IP 214based networks. 215 216There is no provision in any of the 3GPP documents that limits the 217number of Gi/SGi interfaces implemented by a GGSN/P-GW. 218 219[3GPP TS 29.061] Section 11.3 makes it clear that the selection of a 220specific Gi/SGi interfaces is made through the Access Point Name 221(APN):: 222 223 2. each private network manages its own addressing. In general this 224 will result in different private networks having overlapping 225 address ranges. A logically separate connection (e.g. an IP in IP 226 tunnel or layer 2 virtual circuit) is used between the GGSN/P-GW 227 and each private network. 228 229 In this case the IP address alone is not necessarily unique. The 230 pair of values, Access Point Name (APN) and IPv4 address and/or 231 IPv6 prefixes, is unique. 232 233In order to support the overlapping address range use case, each APN 234is mapped to a separate Gi/SGi interface (network device). 235 236.. note:: 237 238 The Access Point Name is purely a control plane (GTP-C) concept. 239 At the GTP-U level, only Tunnel Endpoint Identifiers are present in 240 GTP-U packets and network devices are known 241 242Therefore for a given UE the mapping in IP to PDN network is: 243 244 * network device + MS IP -> Peer IP + Peer TEID, 245 246and from PDN to IP network: 247 248 * local GTP-U IP + TEID -> network device 249 250Furthermore, before a received T-PDU is injected into the network 251device the MS IP is checked against the IP recorded in PDP context. 252