----- On Feb 18, 2017, at 1:58 PM, laforge lafo...@gnumonks.org wrote: > In order to clarify what the module actually does, and how to use it, > let's add some basic documentation to the kernel tree, together with > pointers to related specs and projects. > > Signed-off-by: Harald Welte <lafo...@gnumonks.org> Acked-by: Andreas Schultz <aschu...@tpip.net>
> --- > Documentation/networking/gtp.txt | 135 +++++++++++++++++++++++++++++++++++++++ > 1 file changed, 135 insertions(+) > create mode 100644 Documentation/networking/gtp.txt > > diff --git a/Documentation/networking/gtp.txt > b/Documentation/networking/gtp.txt > new file mode 100644 > index 000000000000..93e96750f103 > --- /dev/null > +++ b/Documentation/networking/gtp.txt > @@ -0,0 +1,135 @@ > +The Linux kernel GTP tunneling module > +====================================================================== > +Documentation by Harald Welte <lafo...@gnumonks.org> > + > +In 'drivers/net/gtp.c' you are finding a kernel-level implementation > +of a GTP tunnel endpoint. > + > +== What is GTP == > + > +GTP is the Generic Tunnel Protocol, which is a 3GPP protocol used for > +tunneling User-IP payload between a mobile station (phone, modem) > +and the interconnection between an external packet data network (such > +as the internet). > + > +So when you start a 'data connection' from your mobile phone, the > +phone will use the control plane to signal for the establishment of > +such a tunnel between that external data network and the phone. The > +tunnel endpoints thus reside on the phone and in the gateway. All > +intermediate nodes just transport the encapsulated packet. > + > +The phone itself does not implement GTP but uses some other > +technology-dependent protocol stack for transmitting the user IP > +payload, such as LLC/SNDCP/RLC/MAC. > + > +At some network element inside the cellular operator infrastructure > +(SGSN in case of GPRS/EGPRS or classic UMTS, hNodeB in case of a 3G > +femtocell, eNodeB in case of 4G/LTE), the cellular protocol stacking > +is translated into GTP *without breaking the end-to-end tunnel*. So > +intermediate nodes just perform some specific relay function. > + > +At some point the GTP packet ends up on the so-called GGSN (GSM/UMTS) > +or P-GW (LTE), which terminates the tunnel, decapsulates the packet > +and forwards it onto an external packet data network. This can be > +public internet, but can also be any private IP network (or even > +theoretically some non-IP network like X.25). > + > +You can find the protocol specification in 3GPP TS 29.060, available > +publicly via the 3GPP website at http://www.3gpp.org/DynaReport/29060.htm > + > +A direct PDF link to v13.6.0 is provided for convenience below: > +http://www.etsi.org/deliver/etsi_ts/129000_129099/129060/13.06.00_60/ts_129060v130600p.pdf > + > +== The Linux GTP tunnelling module == > + > +The module implements the function of a tunnel endpoint, i.e. it is > +able to decapsulate tunneled IP packets in the uplink originated by > +the phone, and encapsulate raw IP packets received from the external > +packet network in downlink towards the phone. > + > +It *only* implements the so-called 'user plane', carrying the User-IP > +payload, called GTP-U. It does not implement the 'control plane', > +which is a signaling protocol used for establishment and teardown of > +GTP tunnels (GTP-C). > + > +So in order to have a working GGSN/P-GW setup, you will need a > +userspace program that implements the GTP-C protocol and which then > +uses the netlink interface provided by the GTP-U module in the kernel > +to configure the kernel module. > + > +This split architecture follows the tunneling modules of other > +protocols, e.g. PPPoE or L2TP, where you also run a userspace daemon > +to handle the tunnel establishment, authentication etc. and only the > +data plane is accelerated inside the kernel. > + > +Don't be confused by terminology: The GTP User Plane goes through > +kernel accelerated path, while the GTP Control Plane goes to > +Userspace :) > + > +The official homepge of the module is at > +https://osmocom.org/projects/linux-kernel-gtp-u/wiki > + > +== Userspace Programs with Linux Kernel GTP-U support == > + > +At the time of this writing, there are at least two Free Software > +implementations that implement GTP-C and can use the netlink interface > +to make use of the Linux kernel GTP-U support: > + > +* OpenGGSN (classic 2G/3G GGSN in C): > + https://osmocom.org/projects/openggsn/wiki/OpenGGSN > + > +* ergw (GGSN + P-GW in Erlang): > + https://github.com/travelping/ergw > + OpenAir5G also seems to have support: https://gitlab.eurecom.fr/oai/openair-cn/tree/master/SRC/GTPV1-U > +== Userspace Library / Command Line Utilities == > + > +There is a userspace library called 'libgtpnl' which is based on > +libmnl and which implements a C-language API towards the netlink > +interface provided by the Kernel GTP module: > + > +http://git.osmocom.org/libgtpnl/ > + > +== Protocol Versions == > + > +There are two different versions of GTP-U: v0 and v1. Both are > +implemented in the Kernel GTP module. Version 0 is a legacy version, > +and deprecated from recent 3GPP specifications. > + > +There are three versions of GTP-C: v0, v1, and v2. As the kernel > +doesn't implement GTP-C, we don't have to worry about this. It's the > +responsibility of the control plane implementation in userspace to > +implement that. > + > +== IPv6 == > + > +The 3GPP specifications indicate either IPv4 or IPv6 can be used both > +on the inner (user) IP layer, or on the outer (transport) layer. > + > +Unfortunately, the Kernel module currently supports IPv6 neither for > +the User IP payload, nor for the outer IP layer. Patches or other > +Contributions to fix this are most welcome! > + > +== Mailing List == > + > +If yo have questions regarding how to use the Kernel GTP module from > +your own software, or want to contribute to the code, please use the > +osmocom-net-grps mailing list for related discussion. The list can be > +reached at osmocom-net-g...@lists.osmocom.org and the mailman > +interface for managign your subscription is at > +https://lists.osmocom.org/mailman/listinfo/osmocom-net-gprs > + > +== Issue Tracker == > + > +The Osmocom project maintains an issue tracker for the Kernel GTP-U > +module at > +https://osmocom.org/projects/linux-kernel-gtp-u/issues > + > +== History / Acknowledgements == > + > +The Module was originally created in 2012 by Harald Welte, but never > +completed. Pablo came in to finish the mess Harald left behind. But > +doe to a lack of user interest, it never got merged. > + > +In 2015, Andreas Schultz came to the rescue and fixed lots more bugs, > +extended it with new features and finally pushed all of us to get it > +mainline, where it was merged in 4.7.0. > -- > 2.11.0
