| 1 | |
| 2 |
|
| 3 | =====================================
|
| 4 | The Linux kernel GTP tunneling module
|
| 5 | =====================================
|
| 6 |
|
| 7 | Documentation by
|
| 8 | Harald Welte <[email protected]> and
|
| 9 | Andreas Schultz <[email protected]>
|
| 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 [email protected] 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 therefore 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.
|