Merge branch 'for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/dtor/input
[platform/kernel/linux-starfive.git] / Documentation / networking / gtp.rst
1 .. SPDX-License-Identifier: GPL-2.0
2
3 =====================================
4 The Linux kernel GTP tunneling module
5 =====================================
6
7 Documentation by
8                  Harald Welte <laforge@gnumonks.org> and
9                  Andreas Schultz <aschultz@tpip.net>
10
11 In 'drivers/net/gtp.c' you are finding a kernel-level implementation
12 of a GTP tunnel endpoint.
13
14 What is GTP
15 ===========
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
50 The Linux GTP tunnelling module
51 ===============================
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
77 The official homepage of the module is at
78 https://osmocom.org/projects/linux-kernel-gtp-u/wiki
79
80 Userspace Programs with Linux Kernel GTP-U support
81 ==================================================
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
93 Userspace Library / Command Line Utilities
94 ==========================================
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
102 Protocol Versions
103 =================
104
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.
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
118 IPv6
119 ====
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
128 Mailing List
129 ============
130
131 If you have questions regarding how to use the Kernel GTP module from
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
135 interface for managing your subscription is at
136 https://lists.osmocom.org/mailman/listinfo/osmocom-net-gprs
137
138 Issue Tracker
139 =============
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
145 History / Acknowledgements
146 ==========================
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.
155
156 Architectural Details
157 =====================
158
159 Local GTP-U entity and tunnel identification
160 --------------------------------------------
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
165 There is only one GTP-U entity (and therefor SGSN/GGSN/S-GW/PDN-GW
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
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
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
202 APN vs. Network Device
203 ======================
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
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
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
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
242 Therefore for a given UE the mapping in IP to PDN network is:
243
244   * network device + MS IP -> Peer IP + Peer TEID,
245
246 and from PDN to IP network:
247
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.