About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / networking / gtp.txt




Custom Search

Based on kernel version 4.16.1. Page generated on 2018-04-09 11:53 EST.

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

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.