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

ECMP hashing support for load balancing

Updated: July 31, 2026

Want to summarize with AI?

Log in

This topic describes Equal-Cost Multi-Path (ECMP) hashing support for load balancing on the Cisco 8000 Series Router, which uses an n-tuple hash algorithm to distribute traffic across multiple equal-cost paths.

The system inherently supports the n-tuple hash algorithm. The first inner header in the n-tuple hashing includes the source port and the destination port of UDP or TCP protocol headers.

The load balancing performs these functions:

  • Incoming data traffic is distributed over multiple equal-cost connections.

  • Incoming data traffic is distributed over multiple equal-cost connections member links within a bundle interface.

  • Layer 2 bundle and Layer 3 (network layer) load-balancing decisions are taken on IPv4 and IPv6. If it is an IPv4 or an IPv6 payload, then an n-tuple hashing is done.

  • An n-tuple hash algorithm provides more granular load balancing and is used for load balancing over multiple equal-cost Layer 3 (network layer) paths. The Layer 3 (network layer) path is on a physical interface or on a bundle interface.

The n-tuple load-balance hash calculation contains:

  • Source IP address

  • Destination IP address

  • IP protocol type

  • Router ID

  • Source port

  • Destination port

  • Input interface

  • Flow-label (for IPv6 only)

User-defined fields for ECMP hashing

ECMP hashing is used to distribute traffic across multiple equal-cost paths. See ECMP hashing support for load balancing for the default static hashing algorithm details.

You can now add user-defined packet header fields for ECMP path calculation for IPv4 and IPv6 flows using the cef platform load-balancing fields user-data command. Ensure you specify these user-defined fields based on the type of traffic flow that requires load balancing.

Table 1. Feature History Table

Feature Name

Release Information

Description

User-defined fields for ECMP hashing

Release 26.1.1

Introduced in this release on: Centralized Systems (8400 [ASIC:K100]) )(select variants only*)

*This feature is now supported on Cisco 8404-SYS-D routers.

User-defined fields for ECMP hashing

Release 25.4.1

Introduced in this release on: Fixed Systems (8700 [ASIC: K100], 8010 [ASIC: A100])(select variants only*)

*This feature is supported on:

  • 8711-48Z-M

  • 8011-32Y8L2H2FH

  • 8011-12G12X4Y-A/D

User-defined fields for ECMP hashing

Release 25.1.1

Introduced in this release on: Fixed Systems (8010 [ASIC: A100])(select variants only*)

*This feature is supported on Cisco 8011-4G24Y4H-I routers.

User-defined fields for ECMP hashing

Release 24.4.1

Introduced in this release on: Fixed Systems (8200 [ASIC: P100], 8700 [ASIC: P100, K100])(select variants only*); Modular Systems (8800 [LC ASIC: P100])(select variants only*)

*This feature is now supported on:

  • 8212-48FH-M

  • 8711-32FH-M

  • 8712-MOD-M

  • 88-LC1-12TH24FH-E

  • 88-LC1-36EH

  • 88-LC1-52Y8H-EM

User-defined fields for ECMP hashing

Release 7.5.5

Release 24.2.11

We ensure that in cases where multiple paths are used to carry packets from source to destination, each path is utilized for this purpose and no path is over-utilized or congested. This is made possible because we now provide customized ECMP hashing fields that are used for path computation.

Previously, the router relied on fixed packet header fields for hashing, which were not user configurable. With additional user-defined bytes considered for hashing, the granularity at which the traffic can be analyzed for ECMP load balancing increases, resulting in better load balancing and path utilization.

This feature introduces these changes:

CLI:

  • cef load-balancing fields user-data

  • The show cef exact-route command is modified with a new user-data keyword.

  • The show cef ipv4 exact-route command is modified with a new user-data keyword.

  • The show cef ipv6 exact-route command is modified with a new user-data keyword.

YANG:

  • New Xpath for Cisco-IOS-XR-8000-fib-platform-cfg.yang.

You can include these parameters:

  • Hash header: The hash header specifies which packet header is being considered for load balancing. You can enable any or all of the available six profiles.

    • IPv4: tcp, udp, non-tcp-udp

    • IPv6: tcp, udp, non-tcp-udp

    If any hash header profile is defined for load balancing, along with the fixed fields considered for hashing, additional bytes in the payload are also used for path computation.

  • Hashing offset: The hashing offset specifies the byte location from the end of the configured header.

  • Hash size: The hash size specifies the number of bytes that is considered from the start of the hash offset by the ECMP hashing algorithm. Range is 1 to 4 bytes.

  • Location: This specifies the location of the ingress line card that receives the incoming traffic. The user-defined hashing configuration is applied on the specified line card.

The addition of the user-defined packet header fields increases the granularity at which the traffic is analyzed for ECMP load balancing. When multiple paths with equal cost are available for routing a specific type of packet from a source to a destination, this granularity ensures that the intended type of traffic is evenly distributed across these paths. This ensures all available paths are used efficiently and prevents congestion or over-utilization of a single path.

You can also retrieve the exact-route information based on the configured user-data using the show cef exact-route command with the user-data keyword.

Note

  • When the user-defined hashing configuration is active, any additional options or optional keywords are disregarded during the parsing of incoming packets for retrieving the user-defined bytes.

  • The hashing results based on user-defined hash feature is applicable to BGP or IGP ECMP and LAG hashing.

  • The use of the user-defined hashing configuration changes the load balancing behavior of GRE and IP-in-IP traffic. This includes all traffic that begins with IPv4, IPv6, IPv4+UDP, IPv6+UDP, IPv4+TCP, and IPv6+TCP, regardless of the payload.

Configure user-defined fields for ECMP hashing

The cef load-balancing fields user-data command configures the additional user-defined fields that are to be considered for the hashing algorithm.

Procedure

1.

Enter global configuration mode.

Example:

Router# configure terminal
2.

Configure the additional IPv4 header fields for TCP packets.

Example:

Router# configure terminal
Router(config)# cef load-balancing fields user-data ipv4 tcp offset 5 size 3 location 0/0/CPU0

In this example, offset 5 means the payload considered for hashing starts from byte 6 from the end of the TCP header, size 3 means three bytes of payload are considered, and location 0/0/CPU0 specifies the line card on which the configuration is applied. Therefore, the sixth, seventh, and eighth bytes of the payload are considered additionally for the hashing.
3.

Save the configuration.

Example:

Router(config)# commit
4.

Enter global configuration mode.

Example:

Router# configure terminal
5.

Configure the additional IPv6 header fields for UDP packets.

Example:


Router(config)# cef load-balancing fields user-data ipv6 udp offset 0 size 2 location 0/0/CPU0
Router(config)# commit

In this example, offset 0 means the payload considered for hashing starts from the end of the UDP header, size 2 means two bytes of payload are considered, and location 0/0/CPU0 specifies the line card on which the configuration is applied. Therefore, the first two bytes of payload of a UDP packet are considered additionally for the hashing.
6.

Verify the running configuration.

Example:

Router# show running-config | include cef
Fri Jul 28 12:02:01.002 UTC
cef load-balancing fields user-data ipv4 tcp offset 5 size 3 location 0/0/CPU0
cef load-balancing fields user-data ipv6 udp offset 0 size 2 location 0/0/CPU0
Router#
7.

Verify the difference in load balancing before and after applying user-defined hashing, for a flow with data that exhibits good hashing behavior. Before applying user-defined hashing:

Example:

Router# show interfaces accounting | i IPV6_U
  Protocol              Pkts In         Chars In     Pkts Out        Chars Out
  IPV6_UNICAST                1               72            0                0
  IPV6_UNICAST                1               72            0                0
  IPV6_UNICAST                1               72            0                0
  IPV6_UNICAST                1               72            0                0
  IPV6_UNICAST                2              144            0                0
  IPV6_UNICAST                1               72            0                0
  IPV6_UNICAST                0                0      3979416       1981749168
  IPV6_UNICAST          4191438       2087336124            0                0
  IPV6_UNICAST                1               72            0                0
  IPV6_UNICAST                1               72            0                0
  IPV6_UNICAST                1               72            0                0
Router#
8.

Verify the load balancing after applying user-defined hashing.

Example:

Router# show interfaces accounting | i IPV6_U
  Protocol              Pkts In         Chars In     Pkts Out        Chars Out
  IPV6_UNICAST                0                0        39119         19481262
  IPV6_UNICAST                0                0        39801         19820898
  IPV6_UNICAST                0                0        40483         20160534
  IPV6_UNICAST                0                0        40524         20180952
  IPV6_UNICAST                0                0        40573         20205354
  IPV6_UNICAST                0                0        40614         20225772
  IPV6_UNICAST                0                0        39368         19605264
  IPV6_UNICAST                0                0        40734         20285532
  IPV6_UNICAST                0                0        40777         20306946
  IPV6_UNICAST                0                0        40171         20005158
  IPV6_UNICAST                0                0        40858         20347284
  IPV6_UNICAST                0                0        40269         20053962
  IPV6_UNICAST                0                0        41603         20718294
  IPV6_UNICAST                0                0        40363         20100774
  IPV6_UNICAST                0                0        40407         20122686
  IPV6_UNICAST                0                0        41098         20466804
  IPV6_UNICAST           850393        423495714            0                0
9.

View the exact route information allocated to the packets using the show cef exact-route command with the user-data keyword. The packet contains value 0x2 in the packet position for the IPv6 packet, for which the user-defined configuration has been added for a non-tcp-udp IPv6 flow.

Example:

Router# show cef ipv6 exact-route 100::10 60::1 flow-label 0 protocol 59 source-port 0 destination-port 0 user-data 0x2 ingress-interface HundredGigE0/0/0/2 location 0/0/cpu0
Unsupported protocol value 59
60::/16, version 1293, internal 0x1000001 0x20 (ptr 0x8b78ef00) [1], 0x400 (0x8e9cfc48), 0x0 (0x0)
 Updated Aug 14 07:50:20.022
 local adjacency to Bundle-Ether3.30

 Prefix Len 16, traffic index 0, precedence n/a, priority 2
   via Bundle-Ether3.30
   via fe80::72b3:17ff:feae:d703/128, Bundle-Ether3.30, 7 dependencies, weight 0, class 0 [flags 0x0]
    path-idx 7 NHID 0x0 [0x8db8bed8 0x0]
    next hop fe80::72b3:17ff:feae:d703/128
    local adjacency