gtp.rst 9.4 KB

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