Documentation/networking/gtp.txt

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