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