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