1The Linux kernel GTP tunneling module 2====================================================================== 3Documentation by Harald Welte <laforge@gnumonks.org> 4 5In 'drivers/net/gtp.c' you are finding a kernel-level implementation 6of a GTP tunnel endpoint. 7 8== What is GTP == 9 10GTP is the Generic Tunnel Protocol, which is a 3GPP protocol used for 11tunneling User-IP payload between a mobile station (phone, modem) 12and the interconnection between an external packet data network (such 13as the internet). 14 15So when you start a 'data connection' from your mobile phone, the 16phone will use the control plane to signal for the establishment of 17such a tunnel between that external data network and the phone. The 18tunnel endpoints thus reside on the phone and in the gateway. All 19intermediate nodes just transport the encapsulated packet. 20 21The phone itself does not implement GTP but uses some other 22technology-dependent protocol stack for transmitting the user IP 23payload, such as LLC/SNDCP/RLC/MAC. 24 25At some network element inside the cellular operator infrastructure 26(SGSN in case of GPRS/EGPRS or classic UMTS, hNodeB in case of a 3G 27femtocell, eNodeB in case of 4G/LTE), the cellular protocol stacking 28is translated into GTP *without breaking the end-to-end tunnel*. So 29intermediate nodes just perform some specific relay function. 30 31At some point the GTP packet ends up on the so-called GGSN (GSM/UMTS) 32or P-GW (LTE), which terminates the tunnel, decapsulates the packet 33and forwards it onto an external packet data network. This can be 34public internet, but can also be any private IP network (or even 35theoretically some non-IP network like X.25). 36 37You can find the protocol specification in 3GPP TS 29.060, available 38publicly via the 3GPP website at http://www.3gpp.org/DynaReport/29060.htm 39 40A direct PDF link to v13.6.0 is provided for convenience below: 41http://www.etsi.org/deliver/etsi_ts/129000_129099/129060/13.06.00_60/ts_129060v130600p.pdf 42 43== The Linux GTP tunnelling module == 44 45The module implements the function of a tunnel endpoint, i.e. it is 46able to decapsulate tunneled IP packets in the uplink originated by 47the phone, and encapsulate raw IP packets received from the external 48packet network in downlink towards the phone. 49 50It *only* implements the so-called 'user plane', carrying the User-IP 51payload, called GTP-U. It does not implement the 'control plane', 52which is a signaling protocol used for establishment and teardown of 53GTP tunnels (GTP-C). 54 55So in order to have a working GGSN/P-GW setup, you will need a 56userspace program that implements the GTP-C protocol and which then 57uses the netlink interface provided by the GTP-U module in the kernel 58to configure the kernel module. 59 60This split architecture follows the tunneling modules of other 61protocols, e.g. PPPoE or L2TP, where you also run a userspace daemon 62to handle the tunnel establishment, authentication etc. and only the 63data plane is accelerated inside the kernel. 64 65Don't be confused by terminology: The GTP User Plane goes through 66kernel accelerated path, while the GTP Control Plane goes to 67Userspace :) 68 69The official homepge of the module is at 70https://osmocom.org/projects/linux-kernel-gtp-u/wiki 71 72== Userspace Programs with Linux Kernel GTP-U support == 73 74At the time of this writing, there are at least two Free Software 75implementations that implement GTP-C and can use the netlink interface 76to make use of the Linux kernel GTP-U support: 77 78* OpenGGSN (classic 2G/3G GGSN in C): 79 https://osmocom.org/projects/openggsn/wiki/OpenGGSN 80 81* ergw (GGSN + P-GW in Erlang): 82 https://github.com/travelping/ergw 83 84== Userspace Library / Command Line Utilities == 85 86There is a userspace library called 'libgtpnl' which is based on 87libmnl and which implements a C-language API towards the netlink 88interface provided by the Kernel GTP module: 89 90http://git.osmocom.org/libgtpnl/ 91 92== Protocol Versions == 93 94There are two different versions of GTP-U: v0 and v1. Both are 95implemented in the Kernel GTP module. Version 0 is a legacy version, 96and deprecated from recent 3GPP specifications. 97 98There are three versions of GTP-C: v0, v1, and v2. As the kernel 99doesn't implement GTP-C, we don't have to worry about this. It's the 100responsibility of the control plane implementation in userspace to 101implement that. 102 103== IPv6 == 104 105The 3GPP specifications indicate either IPv4 or IPv6 can be used both 106on the inner (user) IP layer, or on the outer (transport) layer. 107 108Unfortunately, the Kernel module currently supports IPv6 neither for 109the User IP payload, nor for the outer IP layer. Patches or other 110Contributions to fix this are most welcome! 111 112== Mailing List == 113 114If yo have questions regarding how to use the Kernel GTP module from 115your own software, or want to contribute to the code, please use the 116osmocom-net-grps mailing list for related discussion. The list can be 117reached at osmocom-net-gprs@lists.osmocom.org and the mailman 118interface for managign your subscription is at 119https://lists.osmocom.org/mailman/listinfo/osmocom-net-gprs 120 121== Issue Tracker == 122 123The Osmocom project maintains an issue tracker for the Kernel GTP-U 124module at 125https://osmocom.org/projects/linux-kernel-gtp-u/issues 126 127== History / Acknowledgements == 128 129The Module was originally created in 2012 by Harald Welte, but never 130completed. Pablo came in to finish the mess Harald left behind. But 131doe to a lack of user interest, it never got merged. 132 133In 2015, Andreas Schultz came to the rescue and fixed lots more bugs, 134extended it with new features and finally pushed all of us to get it 135mainline, where it was merged in 4.7.0. 136