Date:   Sun, 19 Feb 2017 15:43:09 +0100 (CET)
From:   Andreas Schultz <aschultz@...p.net>
To:     laforge <laforge@...monks.org>
Cc:     netdev <netdev@...r.kernel.org>
Subject: Re: [PATCH net-next] GTP: Add some basic documentation about
 drivers/net/gtp.c

----- On Feb 18, 2017, at 1:58 PM, laforge laforge@...monks.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 <laforge@...monks.org>
Acked-by: Andreas Schultz <aschultz@...p.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 <laforge@...monks.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-gprs@...ts.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

Powered by blists - more mailing lists