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