package
0.8.11
Repository: https://github.com/wmnsk/go-gtp.git
Documentation: pkg.go.dev

# README

gtpv2: GTPv2 in Golang

Package v2 provides simple and painless handling of GTPv2-C protocol in pure Golang.

Getting Started

Working examples are available in example directory, which might be the better instruction for developers.

Opening a connection

Client

Dial opens a connection between the specified peer by confirming the peer is alive by Echo Request/Response exchange. If you don't need Echo, see Server section.

// Note that the conn is not bound to raddr. to let a Conn to be able to communicate with multiple peers.
// Interface type is required here to let Conn know which is the local interface type.
conn, err := gtpv2.Dial(ctx, laddr, raddr, gtpv2.IFTypeS11MMEGTPC, 0)
if err != nil {
    // ...
}

Server

Retrieve Conn with NewConn, and ListenAndServe to start listening.

// Interface type is required here to let Conn know which is the local interface type.
srvConn := gtpv2.NewConn(srvAddr, gtpv2.IFTypeS11MMEGTPC, 0)
if err := srvConn.ListenAndServe(ctx); err != nil {
    // ...
}

Handling incoming messages

Prepare functions that comform to HandlerFunc, and register them to Conn with AddHandler. This should be done as soon as you get Conn not to miss the incoming messages.

HandlerFunc is to handle the incoming messages by message type. See example for how it is like.
Also consider using AddHandlers when you have many HandlerFuncs.

// write what you expect to do on receiving a message. Handlers should be added per message type.
// by default, Echo Request/Response and Version Not Supported Indication is handled automatically.
conn.AddHandler(
    // first param is the type of message. give number in uint8 or use gtpgtpv2.MsgTypeXXX.
    messages.MsgTypeCreateSessionResponse,
    // second param is the HandlerFunc to describe how you handle the message coming from peer.
    func(c *gtpv2.Conn, senderAddr net.Addr, msg messages.Message) error {
        // Do what you want with CreateSessionResponse message here.
        // see examples directly for functional examples
    },
)

Manipulating sessions

With Conn, you can create, modify, delete GTPv2-C sessions and bearers with the built-in methods.

Session creation

CreateSession creates a Session, while storing values given as IEs and creating a default bearer. In the following call, for example, IMSI and TEID for S1-U eNB is stored in the created Session.

session, err := c.CreateSession(
    // put IEs required for your implementation here.
    // it is easier to use constructors in ie package.
    ie.NewIMSI("123451234567890"),
    
    // or, you can use ie.New() to create an IE without type-specific constructor.
    // put the type of IE, flags/instance, and payload as the parameters.
    ie.New(ie.ExtendedTraceInformation, 0x00, []byte{0xde, 0xad, 0xbe, 0xef}),
    
    // to set the instance to IE created with message-specific constructor, WithInstance()
    // may be your help.
    ie.NewIMSI("123451234567890").WithInstance(1), // no one wants to set instance to IMSI, though.

    // don't forget to contain the Sender F-TEID, as it is used to distinguish the incoming
    // message by Conn.
    //
    // to be secure, TEID should be generated with random values, without conflicts in a Conn.
    // to achieve that, gtpv2 provides NewFTEID() which returns F-TEID in *ie.IE.
    s11Conn.NewFTEID(gtpv2.IFTypeS11MMEGTPC, mmeIP, ""),
)
if err != nil {
    // ...
}

Session deletion / Bearer modification

DeleteSession and ModifyBearer methods are provided to send each message as easy as possible. Unlike CreateSession, they don't manipulate the Session information automatically.

Opening a U-Plane connection

See v1/README.md.

Supported Features

The following Messages marked with "Yes" are currently available with their own useful constructors.

Even there are some missing Messages, you can create any kind of Message by using messages.NewGeneric().

Messages

IDNameSupported
0(Spare/Reserved)-
1Echo RequestYes
2Echo ResponseYes
3Version Not Supported IndicationYes
4-16(Spare/Reserved)-
17-24(Spare/Reserved)-
25-31(Spare/Reserved)-
32Create Session RequestYes
33Create Session ResponseYes
34Modify Bearer RequestYes
35Modify Bearer ResponseYes
36Delete Session RequestYes
37Delete Session ResponseYes
38Change Notification Request
39Change Notification Response
40Remote UE Report Notification
41Remote UE Report Acknowledge
42-63(Spare/Reserved)-
64Modify Bearer CommandYes
65Modify Bearer Failure IndicationYes
66Delete Bearer CommandYes
67Delete Bearer Failure IndicationYes
68Bearer Resource Command
69Bearer Resource Failure Indication
70Downlink Data Notification Failure IndicationYes
71Trace Session Activation
72Trace Session Deactivation
73Stop Paging IndicationYes
74-94(Spare/Reserved)-
95Create Bearer RequestYes
96Create Bearer ResponseYes
97Update Bearer RequestYes
98Update Bearer ResponseYes
99Delete Bearer RequestYes
100Delete Bearer ResponseYes
101Delete PDN Connection Set RequestYes
102Delete PDN Connection Set ResponseYes
103PGW Downlink Triggering Notification
104PGW Downlink Triggering Acknowledge
105-127(Spare/Reserved)-
128Identification Request
129Identification Response
130Context RequestYes
131Context ResponseYes
132Context AcknowledgeYes
133Forward Relocation Request
134Forward Relocation Response
135Forward Relocation Complete Notification
136Forward Relocation Complete Acknowledge
137Forward Access Context Notification
138Forward Access Context Acknowledge
139Relocation Cancel Request
140Relocation Cancel Response
141Configuration Transfer Tunnel
142-148(Spare/Reserved)-
149Detach NotificationYes
150Detach AcknowledgeYes
151CS Paging Indication
152RAN Information Relay
153Alert MME Notification
154Alert MME Acknowledge
155UE Activity Notification
156UE Activity Acknowledge
157ISR Status Indication
158UE Registration Query Request
159UE Registration Query Response
160Create Forwarding Tunnel Request
161Create Forwarding Tunnel Response
162Suspend NotificationYes
163Suspend AcknowledgeYes
164Resume NotificationYes
165Resume AcknowledgeYes
166Create Indirect Data Forwarding Tunnel Request
167Create Indirect Data Forwarding Tunnel Response
168Delete Indirect Data Forwarding Tunnel Request
169Delete Indirect Data Forwarding Tunnel Response
170Release Access Bearers RequestYes
171Release Access Bearers ResponseYes
172-175(Spare/Reserved)-
176Downlink Data NotificationYes
177Downlink Data Notification AcknowledgeYes
178(Spare/Reserved)-
179PGW Restart NotificationYes
180PGW Restart Notification AcknowledgeYes
181-199(Spare/Reserved)-
200Update PDN Connection Set RequestYes
201Update PDN Connection Set ResponseYes
202-210(Spare/Reserved)-
211Modify Access Bearers RequestYes
212Modify Access Bearers ResponseYes
213-230(Spare/Reserved)-
231MBMS Session Start Request
232MBMS Session Start Response
233MBMS Session Update Request
234MBMS Session Update Response
235MBMS Session Stop Request
236MBMS Session Stop Response
237-239(Spare/Reserved)-
240-247(Spare/Reserved)-
248-255(Spare/Reserved)-

Information Elements

The following Information Elements marked with "Yes" are currently available with their own useful constructors.

Even there are some missing IEs, you can create any kind of IEs by using ie.New() function or by initializing ie.IE directly.

IDNameSupported
0(Spare/Reserved)-
1International Mobile Subscriber Identity (IMSI)Yes
2CauseYes
3Recovery (Restart Counter)Yes
4-34(Spare/Reserved)-
35-50(Spare/Reserved)-
51STN-SR
52-70(Spare/Reserved)-
71Access Point Name (APN)Yes
72Aggregate Maximum Bit Rate (AMBR)Yes
73EPS Bearer ID (EBI)Yes
74IP AddressYes
75Mobile Equipment Identity (MEI)Yes
76MSISDNYes
77IndicationYes
78Protocol Configuration Options (PCO)Yes
79PDN Address Allocation (PAA)Yes
80Bearer Level Quality of Service (Bearer QoS)Yes
81Flow Quality of Service (Flow QoS)Yes
82RAT TypeYes
83Serving NetworkYes
84EPS Bearer Level Traffic Flow Template (Bearer TFT)Yes
85Traffic Aggregation Description (TAD)
86User Location Information (ULI)Yes
87Fully Qualified Tunnel Endpoint Identifier (F-TEID)Yes
88TMSIYes
89Global CN-IdYes
90S103 PDN Data Forwarding Info (S103PDF)Yes
91S1-U Data Forwarding Info (S1UDF)Yes
92Delay ValueYes
93Bearer ContextYes
94Charging IDYes
95Charging CharacteristicsYes
96Trace Information
97Bearer FlagsYes
98(Spare/Reserved)-
99PDN TypeYes
100Procedure Transaction IDYes
101(Spare/Reserved)-
102(Spare/Reserved)-
103MM Context (GSM Key and Triplets)
104MM Context (UMTS Key, Used Cipher and Quintuplets)
105MM Context (GSM Key, Used Cipher and Quintuplets)
106MM Context (UMTS Key and Quintuplets)
107MM Context (EPS Security Context, Quadruplets and Quintuplets)
108MM Context (UMTS Key, Quadruplets and Quintuplets)
109PDN Connection
110PDU Numbers
111Packet TMSIYes
112P-TMSI SignatureYes
113Hop CounterYes
114UE Time ZoneYes
115Trace ReferenceYes
116Complete Request Message
117GUTIYes
118F-Container
119F-Cause
120PLMN IDYes
121Target Identification
122(Spare/Reserved)-
123Packet Flow ID
124RAB Context
125Source RNC PDCP Context Info
126Port NumberYes
127APN RestrictionYes
128Selection ModeYes
129Source Identification
130(Spare/Reserved)-
131Change Reporting Action
132Fully Qualified PDN Connection Set Identifier (FQ-CSID)Yes
133Channel Needed
134eMLPP Priority
135Node TypeYes
136Fully Qualified Domain Name (FQDN)Yes
137Transaction Identifier (TI)
138MBMS Session Duration
139MBMS Service Area
140MBMS Session Identifier
141MBMS Flow Identifier
142MBMS IP Multicast Distribution
143MBMS Distribution Acknowledge
144RFSP Index
145User CSG Information (UCI)Yes
146CSG Information Reporting Action
147CSG IDYes
148CSG Membership Indication (CMI)Yes
149Service IndicatorYes
150Detach TypeYes
151Local Distinguished Name (LDN)Yes
152Node FeaturesYes
153MBMS Time to Data Transfer
154ThrottlingYes
155Allocation/Retention Priority (ARP)Yes
156EPC TimerYes
157Signalling Priority Indication
158Temporary Mobile Group Identity (TMGI)
159Additional MM context for SRVCC
160Additional flags for SRVCC
161(Spare/Reserved)-
162MDT Configuration
163Additional Protocol Configuration Options (APCO)
164Absolute Time of MBMS Data Transfer
165H(e)NB Information Reporting
166IPv4 Configuration Parameters (IP4CP)
167Change to Report Flags
168Action Indication
169TWAN Identifier
170ULI TimestampYes
171MBMS Flags
172RAN/NAS CauseYes
173CN Operator Selection Entity
174Trusted WLAN Mode Indication
175Node Number
176Node Identifier
177Presence Reporting Area Action
178Presence Reporting Area Information
179TWAN Identifier Timestamp
180Overload Control Information
181Load Control Information
182Metric
183Sequence Number
184APN and Relative Capacity
185WLAN Offloadability Indication
186Paging and Service InformationYes
187Integer NumberYes
188Millisecond Time Stamp
189Monitoring Event Information
190ECGI List
191Remote UE Context
192Remote User ID
193Remote UE IP information
194CIoT Optimizations Support Indication
195SCEF PDN Connection
196Header Compression Configuration
197Extended Protocol Configuration Options (ePCO)
198Serving PLMN Rate Control
199Counter
200Mapped UE Usage Type
201Secondary RAT Usage Data Report
202UP Function Selection Indication Flags
203Maximum Packet Loss Rate
204APN Rate Control Status
205Extended Trace Information
206Monitoring Event Extension Information
207Additional RRM Policy Index
208V2X Context
209PC5 QoS Parameters
210Services Authorized
211Bit Rate
212PC5 QoS Flow
213-253(Spare/Reserved)-
254(Spare/Reserved)-
255Private ExtensionYes

# Packages

Package ie provides encoding/decoding feature of GTPv2 Information Elements.
Package message provides encoding/decoding feature of GTPv2 protocol.
Package testutils is an internal package to be used for unit tests.

# Functions

Dial sends Echo Request to raddr to check if the endpoint is alive and returns Conn.
DisableLogging disables the logging from the package.
EnableLogging enables the logging from the package.
NewBearer creates a new Bearer.
NewConn creates a new Conn used for server.
NewSession creates a new Session with subscriber information.
PassMessageTo passes the message (typically "triggerred message") to the session expecting to receive it.
SetLogger replaces the standard logger with arbitrary *log.Logger.

# Constants

Access Mode definitions.
Access Mode definitions.
APN Restriction definitions.
APN Restriction definitions.
APN Restriction definitions.
APN Restriction definitions.
APN Restriction definitions.
Cause definitions.
Cause definitions.
Cause definitions.
Cause definitions.
Cause definitions.
Cause definitions.
Cause definitions.
Cause definitions.
Cause definitions.
Cause definitions.
Cause definitions.
Cause definitions.
Cause definitions.
Cause definitions.
Cause definitions.
Cause definitions.
Cause definitions.
Cause definitions.
Cause definitions.
Cause definitions.
Cause definitions.
Cause definitions.
Cause definitions.
Cause definitions.
Cause definitions.
Cause definitions.
Cause definitions.
Cause definitions.
Cause definitions.
Cause definitions.
Cause definitions.
Cause definitions.
Cause definitions.
Cause definitions.
Cause definitions.
Cause definitions.
Cause definitions.
Cause definitions.
Cause definitions.
Cause definitions.
Cause definitions.
Cause definitions.
Cause definitions.
Cause definitions.
Cause definitions.
Cause definitions.
Cause definitions.
Cause definitions.
Cause definitions.
Cause definitions.
Cause definitions.
Cause definitions.
Cause definitions.
Cause definitions.
Cause definitions.
Cause definitions.
Cause definitions.
Cause definitions.
Cause definitions.
Cause definitions.
Cause definitions.
Cause definitions.
Cause definitions.
Cause definitions.
Cause definitions.
Cause definitions.
Cause definitions.
Cause definitions.
Cause Type definitions.
Cause Type definitions.
Cause Type definitions.
Cause Type definitions.
Cause Type definitions.
Cause definitions.
Cause definitions.
Cause definitions.
Cause definitions.
Cause definitions.
Cause definitions.
Cause definitions.
Cause definitions.
Cause definitions.
Cause definitions.
CSG Membership Indication definitions.
CSG Membership Indication definitions.
Configuration Protocol definitions.
Container ID definitions.
ContID3GPPPSDataOffUEstatus.
Container ID definitions.
Container ID definitions.
Container ID definitions.
Container ID definitions.
Container ID definitions.
Container ID definitions.
Container ID definitions.
Container ID definitions.
Container ID definitions.
Container ID definitions.
Container ID definitions.
Container ID definitions.
ContIDIPaddressAllocationViaNASSignalling.
Container ID definitions.
ContIDIPv4addressAllocationViaDHCPv4.
Container ID definitions.
Container ID definitions.
Container ID definitions.
Container ID definitions.
ContIDMSSupportofNetworkRequestedBearerControlIndicator.
Container ID definitions.
Container ID definitions.
Container ID definitions.
Container ID definitions.
Container ID definitions.
Container ID definitions.
Container ID definitions.
Container ID definitions.
Container ID definitions.
Container ID definitions.
Daylight Saving Time definitions.
Daylight Saving Time definitions.
Daylight Saving Time definitions.
Detach Type definitions.
Detach Type definitions.
Registered UDP ports.
Registered UDP ports.
InterfaceType definitions.
InterfaceType definitions.
InterfaceType definitions.
InterfaceType definitions.
InterfaceType definitions.
InterfaceType definitions.
InterfaceType definitions.
InterfaceType definitions.
InterfaceType definitions.
InterfaceType definitions.
InterfaceType definitions.
InterfaceType definitions.
InterfaceType definitions.
InterfaceType definitions.
InterfaceType definitions.
InterfaceType definitions.
InterfaceType definitions.
InterfaceType definitions.
InterfaceType definitions.
InterfaceType definitions.
InterfaceType definitions.
InterfaceType definitions.
InterfaceType definitions.
InterfaceType definitions.
InterfaceType definitions.
InterfaceType definitions.
InterfaceType definitions.
InterfaceType definitions.
InterfaceType definitions.
InterfaceType definitions.
InterfaceType definitions.
InterfaceType definitions.
InterfaceType definitions.
InterfaceType definitions.
InterfaceType definitions.
InterfaceType definitions.
InterfaceType definitions.
InterfaceType definitions.
InterfaceType definitions.
InterfaceType definitions.
Node-ID Type definitions.
Node-ID Type definitions.
Node-ID Type definitions.
Node Type definitions.
Node Type definitions.
PDN Type definitions.
PDN Type definitions.
PDN Type definitions.
PDN Type definitions.
Protocol ID definitions.
Protocol ID definitions.
Protocol ID definitions.
Protocol ID definitions.
Protocol Type definitions.
Protocol Type definitions.
Protocol Type definitions.
Protocol Type definitions.
Protocol Type definitions.
RAT Type definitions.
RAT Type definitions.
RAT Type definitions.
RAT Type definitions.
RAT Type definitions.
RAT Type definitions.
RAT Type definitions.
RAT Type definitions.
RAT Type definitions.
RAT Type definitions.
SelectionMode definitions.
SelectionModeMSorNetworkProvidedAPNSubscribedVerified.
SelectionMode definitions.
SelectionMode definitions.
Service Indicator definitions.
Service Indicator definitions.

# Variables

ErrTEIDNotFound indicates that TEID is not registered for the interface specified.
ErrTimeout indicates that a handler failed to complete its work due to the absence of message expected to come from another endpoint.

# Structs

Bearer represents a GTPv2 bearer.
BearerNotFoundError indicates that no Bearer found by lookup methods.
CauseNotOKError indicates that the value in Cause IE is not OK.
Conn represents a GTPv2-C connection.
HandlerNotFoundError indicates that the handler func is not registered in *Conn for the incoming GTPv2 message.
InvalidSequenceError indicates that the Sequence Number is invalid.
InvalidSessionError indicates that something went wrong with Session.
InvalidTEIDError indicates that the TEID value is different from expected one or not registered in TEIDMap.
InvalidVersionError indicates that the version of the message specified by the user is not acceptable for the receiver.
Location is a subscriber's location.
QoSProfile represents a QoS-related information that belongs to a Bearer.
RequiredIEMissingError indicates that the IE required is missing.
RequiredParameterMissingError indicates that no Bearer found by lookup methods.
Session is a GTPv2 Session.
Subscriber is a subscriber that belongs to a GTPv2 session.
UnexpectedIEError indicates that the type of incoming message is not expected.
UnexpectedTypeError indicates that the type of incoming message is not expected.
UnknownAPNError indicates that the APN is different from expected one.
UnknownIMSIError indicates that the IMSI is different from expected one.

# Type aliases

HandlerFunc is a handler for specific GTPv2-C message.