Interfaces and Hardware Component Configuration Guide for Cisco 8000 Series Routers, Cisco IOS XR Releases

PDF

Interfaces and Hardware Component Configuration Guide for Cisco 8000 Series Routers, Cisco IOS XR Releases

Generic UDP encapsulation

Updated: July 31, 2026

Want to summarize with AI?

This topic describes Generic UDP Encapsulation (GUE) on the Cisco 8000 Series Router, which encapsulates IPv4 and IPv6 packets in UDP to provide load-balancing entropy and efficient transport across networks.

Generic UDP Encapsulation (GUE) is a UDP-based network encapsulation protocol that

encapsulates IPv4 and IPv6 packets in User Datagram Protocol (UDP),
defines an additional header that helps determine the payload carried by the IP packet, and
leverages the UDP source port to provide entropy for Equal Cost Multipath (ECMP) hashing and load balancing.

The additional header can include items, such as

a virtual networking identifier
security data for validating or authenticating the GUE header, and
congestion control data

In GUE, the payload is encapsulated in an IP packet that can be IPv4 or IPv6 carrier. The UDP header is added to provide extra hashing parameters and optional payload demultiplexing. At the decapsulation node, the carrier IP and UDP headers are removed, and the packet is forwarded based on the inner payload.

A GUE packet has the general format:

For example, in this scenario, if the data stream is sent from Host 1 to Host 2. The server acts as a GUE encapsulator that sends the packets from Host 1. The server, on the other end receiving the data, validates the data for the valid carrier IP and UDP header and decapsulates the data.

UDP encapsulation is a technique of adding network headers to packets and then encapsulating the packets within UDP. Encapsulating packets using UDP facilitates efficient transport across networks. By leveraging Receive Side Scaling (RSS) and Equal Cost Multipath (ECMP) routing, UDP provides significant performance benefits for load-balancing. The use of the UDP source port provides entropy to ECMP hashing and provides the ability to use the IP source or destination, and the L4 port for load-balancing entropy. Traditional mechanisms like Generic Routing Encapsulation (GRE) can handle only the outer Source IP address and parts of the destination address. They may not provide sufficient load balancing entropy.

GUE has various variants, but variant 1 of GUE allows direct encapsulation of IPv4 and IPv6 in UDP. This technique saves encapsulation overhead on links for the use of IP encapsulation, and does not need to allocate a separate UDP port number for IP-over-UDP encapsulation. Variant 1 has no GUE header, but a UDP packet carries an IP packet. The first two bits of the UDP payload is the GUE variant field and match with the first two bits of the version number in the IP header.

Starting from Cisco IOS XR Release 25.4.1, you can use a single UDP port for both IPv4 and IPv6 packets in GUE encapsulation and decapsulation. The default UDP port for IPv4 and IPv6 is 6080. You can modify the default UDP ports by using the nve overlay-encap guev1 udp-port destination command.

Note

The hw-module profile gue udp-dest-port command used to configure the UDP ports individually for IPv4, IPv6, and MPLS is deprecated from Cisco IOS XR Release 25.4.1.

Table 1. Feature History Table
Feature Name	Release Information	Feature Description
Single UDP port for IPv4 and IPv6 packets	Release 25.4.1	Introduced in this release on: Fixed Systems (8200 [ASIC: Q200]) This feature enhances memory and network performance by using a single UDP port for both IPv4 and IPv6 packets in GUE variant 1 UDP encapsulation and decapsulation. The default UDP port for IPv4 and IPv6 is 6080. As part of this enhancement, the hw-module profile gue udp-dest-port command is deprecated. This feature introduces these changes: CLI: nve overlay-encap guev1 show cef global udp-ports gue-v1
Generic UDP Decapsulation for IPv6 Traffic	Release 25.4.1	Introduced in this release on: Fixed Systems (8010 [ASIC: A100])(select variants only) This feature is supported on: 8011-32Y8L2H2FH 8011-12G12X4Y-A/D
Generic UDP Decapsulation for IPv6 Traffic	Release 25.1.1	Introduced in this release on: Fixed Systems (8700 [ASIC: K100], 8010 [ASIC: A100])(select variants only) This feature is supported on: 8712-MOD-M 8011-4G24Y4H-I
Generic UDP Decapsulation for IPv6 Traffic	Release 24.4.1	Introduced in this release on: Fixed Systems (8200 [ASIC: P100], 8700 [ASIC: P100])(select variants only); Modular Systems (8800 [LC ASIC: P100])(select variants only) *This feature is now supported on: 8212-48FH-M 8711-32FH-M 88-LC1-12TH24FH-E 88-LC1-36EH 88-LC1-52Y8H-EM
Generic UDP Decapsulation for IPv6 Traffic	Release 24.1.1	Starting from this release, you can decapsulate GUEv6 packets by adding an additional header to packets that identifies or authenticates the data by using User Datagram Protocol (UDP). In GUE, the payload is encapsulated in an IP packet that can be an IPv6 carrier. The UDP header is added to provide extra hashing parameters and optional payload demultiplexing. At the decapsulation node, the carrier IP and UDP headers are removed, and the packet is forwarded based on the inner payload.

Benefits of using GUE

Allows direct encapsulation of payloads, such as IPv4 and IPv6, in the UDP packet. You can use the UDP port for demultiplexing payloads, and you can use a single UDP port that allows systems to employ parsing models to identify payloads.
Leverages the UDP header for entropy labels by encoding a tuple-based source port.
Leverages source IP addresses for load-balance encoding. The destination too can be terminated based on a subnet, providing additional bits for entropy.
Avoids special handling for transit nodes because they only see an IP-UDP packet with some payload.
Eases implementation of UDP tunneling with GUE because of the direct encapsulation method of the payloads into UDP.

Benefits of single UDP port for IPv4 and IPv6 packets

Uses a single class map per IP header.
Allocates one counter per class map.
Uses simpler logic to reduce duplication of end-to-end objects.

Configuration guidelines for GUE

These usage guidelines apply for GUE:

Receives IPv4 packets with the defined GUE port of 6080.
Receives MPLS packets with the UDP over MPLS (UDPoMPLS) port of 6635.
GUE for IPv6 traffic is supported only on the Cisco 8202-32FH-M router, and 88-LC0-36FH-M and 88-LC0-36FH line cards.
GUE IPv6 decapsulation is supported only on Layer 3 ports.

Restrictions for GUE

These restrictions apply to GUE:

Supports Generic UDP decapsulation for only variant 1.
Range of source or destination ports is not supported.
Range, source, or destination addresses are not supported, but subnet mask entries are allowed.
Terminating GRE after GUE or GUE after GRE is not supported.
Terminating a label such as a VPN de-aggregation after GUE termination is not supported.
Slow path support is not available. To resolve the inner IP adjacency, use the cef proactive-arp-nd enable command.
Running the clear all command does not clear the interface of all its existing configurations.
GUE IPv6 is not supported over BVI interfaces.

Note

To use only the outer IP header (L3 and L4) for calculating the hashing for incoming GUE packets, use the hw-module profile gue underlay-hash enable command. Otherwise, by default, both the outer IP header (L3 and L4) and the inner IP header (L3 and L4) are considered for calculating the hashing for incoming GUE packets.

The hw-module profile gue underlay-hash enable command is not supported on the P100-based and Q100-based ASICs.

Configure GUE for IPv4

Configure GUE variant 1 for IPv4 by defining the UDP destination port, creating a traffic class to match GUE-encapsulated IPv4 packets, defining a policy map that decapsulates matched traffic, and applying the policy to the VRF.

Procedure

	1.	Configure the GUE variant 1 UDP destination port for IPv4 using the nve overlay-encapsulation guev1 command. Example: `Router# configure Router(config-if)# nve overlay-encapsulation guev1 Router(config-nve-encap-guev1)# udp-port destination ipv4 8000 Router(config-nve-encap-guev1)# commit`
	2.	Create a traffic class and specify the criteria for classifying GUE-encapsulated IPv4 packets. Example: `Router# configure Router(config)# class-map type traffic match-all gue-v4-udp Router(config-cmap)# match destination-address ipv4 220.100.20.0 255.255.255.255 Router(config-cmap)# match source-address ipv4 210.100.20.0 255.255.255.255 Router(config-cmap)# match protocol udp Router(config-cmap)# end-class-map Router(config)# commit`
	3.	Define a policy map and associate the traffic class with the traffic policy. Example: `Router(config)# policy-map type pbr magic-decap Router(config-pmap)# class type traffic gue-v4-udp Router(config-pmap-c)# decapsulate gue variant 1 Router(config-pmap-c)# exit Router(config-pmap)# class type traffic class-default Router(config-pmap-c)# exit Router(config-pmap)# end-policy-map Router(config)# commit`
	4.	Apply the policy for each VRF and apply this policy on all the interfaces that are part of the VRF. Example: `Router# configure Router(config)# vrf-policy Router(config-vrf-policy)# vrf default address-family ipv4 policy type pbr input magic-decap Router(config-vrf-policy)# commit`
	5.	Run the show policy-map type pbr addr-family ipv4 statistics command to view the counter values accumulated for the packets that match the class-map. Example: `Router# show policy-map type pbr addr-family ipv4 statistics VRF Name: default Policy-Name: pmap Policy Type: pbr Addr Family: IPv4 Class: cmap-loop3 Classification statistics (packets/bytes) Matched : 198325306/17849277540 Transmitted statistics (packets/bytes) Total Transmitted : 198325306/17849277540`
	6.	Run the show nve global command to view the default configuration if the GUE variant 1 encapsulation is not configured for IPv4 packets. Example: `Router# show nve global NVE Global details VNI Scope Local : No VxLAN l3vni bring up mode: V1 GUEv1 UDP Destination Port (IPv4): 6080 GUEv1 UDP Destination Port (IPv6): 6615 GUEv1 UDP Destination Port (mpls): 6635 Count of NVE interfaces with mpls-udp encap: 0 Global system mac: 0033.3ebe.8f00`
	7.	Run the show cef global udp-ports gue-v1 command to view the UDP ports for IPv4, IPv6, and MPLS packets in GUE variant 1 encapsulation. Example: `Router# show cef global udp-ports gue-v1 UDP ports for gue-v1 [0x309c3a70f8] IPv4: 6080 (default) IPv6: 6080 (default) MPLS: 6635 (default) Policy update time: Not Yet Recorded Platform update time: Not Yet Recorded`
	8.	Run the clear vrf command to clear the policy-map counters for each class-map rule. Example: `Router# clear vrf default address-family ipv4 statistics`

Configure GUE for IPv6

Configure GUE variant 1 for IPv6 by defining the UDP destination port, creating a traffic class to match GUE-encapsulated IPv6 packets, defining a policy map that decapsulates matched traffic, and applying the policy to the VRF.

Procedure

	1.	Configure the GUE variant 1 UDP destination port for IPv6 using the nve overlay-encapsulation guev1 command. Example: `Router# configure Router(config-if)# nve overlay-encapsulation guev1 Router(config-nve-encap-guev1)# udp-port destination ipv6 9000 Router(config-nve-encap-guev1)# commit`
	2.	Create a traffic class and specify the criteria for classifying GUE-encapsulated IPv6 packets. Example: `Router# configure Router(config)# class-map type traffic match-all gue-v6-udp Router(config-cmap)# match protocol udp Router(config-cmap)# match destination-address ipv6 11:1:1::1/128 Router(config-cmap)# end-class-map Router(config)# commit`
	3.	Define a policy map and associate the traffic class with the traffic policy. Example: `Router(config)# policy-map type pbr guev6_decap Router(config-pmap)# class type traffic gue-v6-udp Router(config-pmap-c)# decapsulate gue variant 1 Router(config-pmap-c)# exit Router(config-pmap)# class type traffic class-default Router(config-pmap-c)# exit Router(config-pmap)# end-policy-map Router(config)# commit`
	4.	Apply the policy for each VRF. Example: `Router# configure Router(config)# vrf-policy Router(config-vrf-policy)# vrf default address-family ipv6 policy type pbr input guev6_decap Router(config-vrf-policy)# commit`
	5.	Run the show policy-map type pbr vrf default addr-family ipv6 statistics command to view the counter values accumulated for the packets that match the class-map. Example: `Router# show policy-map type pbr vrf default addr-family ipv6 statistics VRF Name: default Policy-Name: guev6_decap Policy Type: pbr Addr Family: IPv6 Class: gue-v6-udp Classification statistics (packets/bytes) Matched : 190/24320 Transmitted statistics (packets/bytes) Total Transmitted : 190/24320 Class: class-default Classification statistics (packets/bytes) Matched : 0/0 Transmitted statistics (packets/bytes) Total Transmitted : 0/0`
	6.	Run the show nve global command to view the default configuration if the GUE variant 1 encapsulation is not configured for IPv6 packets. Example: `Router# show nve global NVE Global details VNI Scope Local : No VxLAN l3vni bring up mode: V1 GUEv1 UDP Destination Port (IPv4): 6080 GUEv1 UDP Destination Port (IPv6): 6615 GUEv1 UDP Destination Port (mpls): 6635 Count of NVE interfaces with mpls-udp encap: 0 Global system mac: 0033.3ebe.8f00`
	7.	Run the show cef global udp-ports gue-v1 command to view the UDP ports for IPv4, IPv6, and MPLS packets in GUE variant 1 encapsulation. Example: `Router# show cef global udp-ports gue-v1 UDP ports for gue-v1 [0x309c3a70f8] IPv4: 6080 (default) IPv6: 6080 (default) MPLS: 6635 (default) Policy update time: Not Yet Recorded Platform update time: Not Yet Recorded`

Outer IP header-driven hash computation for incoming GUE packets

When multiple paths with the same cost are available for forwarding traffic, Equal Cost Multipath (ECMP) hashing is used to determine the path to select for each packet. Each packet that needs to be forwarded is processed using a hashing algorithm. The hashing algorithm considers specific packet fields such as source IP, destination IP, source port, and destination port, and generates a hash value. The generated hash value is then mapped to one of the available paths. The selected path is used to forward the packet to its destination. The goal is to distribute the traffic evenly across the available paths to prevent congestion and utilize the network resources efficiently.

You can use only the outer IP header (L3 and L4) for calculating the hash value for incoming GUE packets and completely ignore the inner IP header. This functionality is configurable using the hw-module profile gue underlay-hash command. It is supported for both GUE termination (decapsulation) and GUE transit (pass-through) nodes. By default, the feature is disabled, and both the outer IP header (L3 and L4) and the inner IP header (L3 and L4) are used for calculating the hashing for GUE packets.

Benefits

Load balancing efficiency: By hashing only on the outer IP and L4 information, the packets with the same source and destination IP addresses and L4 ports consistently follow the same path in a load-balanced environment. This helps maintain session affinity or stickiness because the inner IP addresses or L4 port numbers can change dynamically within the encapsulated packets.
Network security: Ignoring the inner IP helps preserve privacy and confidentiality within the encapsulated packets. By focusing on the outer IP and L4 headers, the network device does not have visibility into the inner IP addressing scheme or the specific content encapsulated within the packet, which enhances security.
Network scalability: Ignoring the inner IP reduces the complexity and overhead of packet processing, and improves overall network performance and scalability, especially in high-throughput environments.

Configure outer IP header-driven hash computation for incoming GUE packets

Use the hw-module profile gue underlay-hash enable command to configure hashing that uses only the outer IP header for GUE packets.

Procedure

Enter global configuration mode and enable outer IP header-driven hash computation for GUE packets.

Example:

Router# configure
Router(config)# hw-module profile gue underlay-hash enable
Router(config)# commit

Verify the running configuration.

Example:

Router(config)# show running-config
hw-module profile gue underlay-hash enable
end

Verify the configuration takes effect by comparing the show dpa objects sys output before and after enabling the feature.

Example:

Output before enabling hashing with only the outer IP header for GUE packets:

Router# show dpa objects sys location 0/RP0/CPU0 | include gue
  uint32_t gue_ipv4_port => 0
  uint32_t gue_ipv6_port => 0
  uint32_t gue_mpls_port => 0
  ofa_bool_t gue_underlay_hash => FALSE

Example:

Output after enabling hashing with only the outer IP header for GUE packets:

Router# show dpa objects sys location 0/RP0/CPU0 | include gue
  uint32_t gue_ipv4_port => 0
  uint32_t gue_ipv6_port => 0
  uint32_t gue_mpls_port => 0
  ofa_bool_t gue_underlay_hash => TRUE

Need help?

Open a support case

(Requires a Cisco Service Contract)

The documentation set for this product strives to use bias-free language. For the purposes of this documentation set, bias-free is defined as language that does not imply discrimination based on age, disability, gender, racial identity, ethnic identity, sexual orientation, socioeconomic status, and intersectionality. Exceptions may be present in the documentation due to language that is hardcoded in the user interfaces of the product software, language used based on RFP documentation, or language that is used by a referenced third-party product. Learn more about how Cisco is using Inclusive Language.