nexthop_group¶

Nexthop groups are a forwarding/tunneling abstraction in EOS.

A nexthop group is comprised of a tunneling protocol (IP/GRE or MPLS, for example) and a collection of nexthop (aka destination) IP addresses and other forwarding information (such as MPLS stack operations to apply for traffic sent to that nexthop). The same IP address may be specified in more than one entry within the group, allowing for unequal cost load balancing. By using distinct addresses for each entry, equal cost load balancing can be achieved.

The nexthop or destination IP is the tunnel (outer) destination IP address for GRE and IP-in-IP. For MPLS, the nexthop address is used to find (via ARP/ND) a MAC address for the MPLS next hop.

Nexthop entries must be manually monitored and maintained by the agent. If a tunnel destination (aka nexthop) becomes unreachable, traffic hashed to that entry will be black-holed in the network until a working entry is set in that index of the nexthop group, or the entry is deleted.

Presently, all nexthop groups encapsulate traffic directed to them, either as an IP-in-IP (IP protocol 4) tunnel, a GRE (IP protocol 47) tunnel encapsulating either IPv4, IPv6 or MPLS traffic, or as pure MPLS frames. MPLS label switching operations are also supported, see the nexthop_group_entry_t class for more information.

Presently, MPLS switching actions are only only supported when used with PBR and cannot be used with IP routes.

The following example creates a nexthop group called “nhg1” which performs GRE encapsulation of traffic sent to it, sending traffic to two different nexthop IP addresses unequally (at a 2/3 to 1/3 ratio). For a usage of a nexthop group with policy routing, see the policy_map.h file.

eos::nexthop_group_t nhg("nhg1", eos::NEXTHOP_GROUP_GRE);
// Specify two destinations (nexthop group entries) for the traffic
eos::nexthop_group_entry_t nhe1(eos::ip_addr_t("172.12.1.1"));
eos::nexthop_group_entry_t nhe2(eos::ip_addr_t("172.12.1.2"));
// Set the nexthop group entries on the group with unequal cost load balancing
// Balance traffic 2/3 to 172.12.1.1, 1/3 to 172.12.1.2.
nhg.nexthop_set(0, nhe1);
nhg.nexthop_set(1, nhe1);
nhg.nexthop_set(2, nhe2);

namespace eos

class nexthop_group_handler

#include <nexthop_group.h>

This class handles changes to a nexthop group’s status.

Public Functions

nexthop_group_handler(nexthop_group_mgr *)

nexthop_group_mgr * get_nexthop_group_mgr() const

void watch_all_nexthop_groups(bool)

Registers this class to receive change updates on all nexthop groups.

Expects a boolean signifying whether notifications should be propagated to this instance or not.

void watch_nexthop_group(std::string const & nexthop_group_name, bool)

Registers this class to receive change updates on the given nexthop group.

Expects the name of the corresponding nexthop group and a boolean signifying whether notifications should be propagated to this instance or not.

virtual void on_nexthop_group_active(std::string const & nexthop_group_name, bool active): Handler called when the active status of a nexthop_group changes.

virtual void on_nexthop_group_programmed(std::string const & nexthop_group_name): Handler called when the nexthop_group is programmed in response to a configuration change.

class nexthop_group_iter_t

Private Functions

nexthop_group_iter_t(nexthop_group_iter_impl * const)

Friends

friend class nexthop_group_iter_impl

class programmed_nexthop_group_iter_t

Private Functions

programmed_nexthop_group_iter_t(programmed_nexthop_group_iter_impl * const)

Friends

friend class programmed_nexthop_group_iter_impl

class nexthop_group_mgr

#include <nexthop_group.h>

A manager of ‘nexthop-group’ configurations.

Create one of these via an sdk object prior to starting the agent main loop. When your eos::agent_handler::on_initialized virtual function is called, the manager is valid for use.

Public Functions

virtual ~nexthop_group_mgr()

virtual void resync_init() = 0

virtual void resync_complete() = 0

virtual nexthop_group_iter_t nexthop_group_iter() const = 0: Iterates over all the nexthop groups currently configured.

virtual nexthop_group_t nexthop_group(std::string const & nexthop_group_name) const = 0: Retrieves an existing nexthop_group_t by name, if it exists. Otherwise this returns an empty nexthop_group_t()

virtual nexthop_group_entry_counter_t counter(std::string const & nexthop_group_name, uint16_t entry) const = 0

Returns the counter corresponding to the given nexthop group name and entry, if it exists. Otherwise this returns an empty ‘nexthop_group_entry_counter_t()’

Counters are reset whenever nexthop group entry configuration changes.

virtual bool exists(std::string const & nexthop_group_name) const = 0: Returns true if a nexthop group with the given name has been configured.

virtual bool active(std::string const & nexthop_group_name) const = 0

Returns whether or not the given nexthop group is active.

Nexthop groups are active if the FIB has prefixes using this group. Deleting an active nexthop group will cause all prefixes that point to that nexthop group to blackhole their traffic.

In order to hitlessly delete a nexthop group, first delete all prefixes that point to it, wait for the nexthop group to no longer be active (using nexthop_group_handler::on_nexthop_group_active), and then delete the nexthop group.

virtual void nexthop_group_set(nexthop_group_t const &) = 0: Creates or updates a nexthop group.

virtual void nexthop_group_del(std::string const & nexthop_group_name) = 0: Removes the named nexthop group from the configuration if it exists.

virtual programmed_nexthop_group_iter_t programmed_nexthop_group_iter() const = 0

Public Members

nexthop_group_t const

Protected Functions

nexthop_group_mgr()

Private Members

nexthop_group_mgr

Friends

friend class nexthop_group_handler

Type definitions in nexthop_group¶

namespace eos

Enums

nexthop_group_encap_t enum

The type of encapsulation to use for this nexthop group.

Each tunnel encapsulation type for Nexthop Groups causes a variety of packet headers for packets using the group to be changed to appropriately encapsulate the frame. IP type has no encapsulation.

Values:

NEXTHOP_GROUP_TYPE_NULL -
NEXTHOP_GROUP_IP_IN_IP -
IP in IP encapsulation.
NEXTHOP_GROUP_GRE -
GRE encapsulation.
NEXTHOP_GROUP_MPLS -
MPLS encapsulation.
NEXTHOP_GROUP_MPLS_OVER_GRE -
MPLS over GRE encapsulation.
NEXTHOP_GROUP_IP -
IP no encapsulation.

nexthop_group_gre_key_t enum

How the GRE tunnel key is set for GRE nexthop groups.

Values:

NEXTHOP_GROUP_GRE_KEY_NULL -
Default value; do not set the GRE tunnel key.
NEXTHOP_GROUP_GRE_KEY_INGRESS_INTF -
Use the ingress interface as the tunnel key. Not supported in this release.

class nexthop_group_mpls_action_t

#include <nexthop_group.h>

An MPLS nexthop group switching operation.

This structure combines a stack of labels and an MPLS switching operation using those labels, such as eos::MPLS_ACTION_PUSH.

Public Functions

nexthop_group_mpls_action_t(): Default constructor.

nexthop_group_mpls_action_t(mpls_action_t action_type): Constructs an MPLS action with a specific switching operation.

nexthop_group_mpls_action_t(mpls_action_t action_type, std::forward_list< mpls_label_t > const & label_stack): Constructs a populated MPLS label stack for some switching action.

nexthop_group_mpls_action_t(const nexthop_group_mpls_action_t & other)

nexthop_group_mpls_action_t & operator=(nexthop_group_mpls_action_t const & other)

mpls_action_t action_type() const: Getter for ‘action_type’: the MPLS switching operation for this action.

void action_type_is(mpls_action_t action_type): Setter for ‘action_type’.

std::forward_list< mpls_label_t > const & label_stack() const

Getter for ‘label_stack’: the MPLS label stack.

The first element in iteration order is the innermost label, the last element in iteration order is the outermost label. When using std::forward_list< eos::mpls_label_t >::push_front to build the label stack, the first element pushed will be the outermost label, also known as top of stack.

void label_stack_is(std::forward_list< mpls_label_t > const & label_stack): Setter for ‘label_stack’.

void label_stack_set(mpls_label_t const & label_stack): Prepend one label_stack to the list.

void label_stack_del(mpls_label_t const & label_stack): Remove all matching label_stack elements.

bool operator==(nexthop_group_mpls_action_t const & other) const

bool operator!=(nexthop_group_mpls_action_t const & other) const

bool operator<(nexthop_group_mpls_action_t const & other) const

uint32_t hash() const: The hash function for type nexthop_group_mpls_action_t.

void mix_me(hash_mix & h) const: The hash mix function for type nexthop_group_mpls_action_t.

std::string to_string() const: Returns a string representation of the current object’s values.

Private Members

std::shared_ptr< nexthop_group_mpls_action_impl_t > pimpl

Friends

friend std::ostream & operator<<: A utility stream operator that adds a string representation of nexthop_group_mpls_action_t to the ostream.

class nexthop_group_entry_counter_t

#include <nexthop_group.h>

Defines counter for a nexthop entry.

Public Functions

nexthop_group_entry_counter_t()

nexthop_group_entry_counter_t(uint64_t packets, uint64_t bytes, bool valid)

nexthop_group_entry_counter_t(const nexthop_group_entry_counter_t & other)

nexthop_group_entry_counter_t & operator=(nexthop_group_entry_counter_t const & other)

uint64_t packets() const

uint64_t bytes() const

bool valid() const

bool operator==(nexthop_group_entry_counter_t const & other) const

bool operator!=(nexthop_group_entry_counter_t const & other) const

bool operator<(nexthop_group_entry_counter_t const & other) const

uint32_t hash() const: The hash function for type nexthop_group_entry_counter_t.

void mix_me(hash_mix & h) const: The hash mix function for type nexthop_group_entry_counter_t.

std::string to_string() const: Returns a string representation of the current object’s values.

Private Members

std::shared_ptr< nexthop_group_entry_counter_impl_t > pimpl

Friends

friend std::ostream & operator<<: A utility stream operator that adds a string representation of nexthop_group_entry_counter_t to the ostream.

class nexthop_group_entry_t

#include <nexthop_group.h>

A nexthop group destination entry.

An entry consists of a nexthop IP address, and optionally an MPLS label switching operation.

Public Functions

nexthop_group_entry_t()

nexthop_group_entry_t(ip_addr_t const & nexthop)

nexthop_group_entry_t(ip_addr_t const & nexthop, intf_id_t const & intf)

nexthop_group_entry_t(std::string const & child_nexthop_group)

nexthop_group_entry_t(const nexthop_group_entry_t & other)

nexthop_group_entry_t & operator=(nexthop_group_entry_t const & other)

nexthop_group_mpls_action_t mpls_action() const: Getter for ‘mpls_action’: MPLS label switching stack for this entry.

void mpls_action_is(nexthop_group_mpls_action_t const & mpls_action): Setter for ‘mpls_action’.

ip_addr_t nexthop() const: Getter for ‘nexthop’: the next hop IP address for this entry.

void nexthop_is(ip_addr_t const & nexthop): Setter for ‘nexthop’.

intf_id_t intf() const: Getter for ‘intf’: the next hop egress interface.

void intf_is(intf_id_t const & intf): Setter for ‘intf’.

std::string child_nexthop_group() const: Getter for ‘child_nexthop_group’: the name of next level nexthop-group.

void child_nexthop_group_is(std::string const & child_nexthop_group): Setter for ‘child_nexthop_group’.

bool operator==(nexthop_group_entry_t const & other) const

bool operator!=(nexthop_group_entry_t const & other) const

bool operator<(nexthop_group_entry_t const & other) const

uint32_t hash() const: The hash function for type nexthop_group_entry_t.

void mix_me(hash_mix & h) const: The hash mix function for type nexthop_group_entry_t.

std::string to_string() const: Returns a string representation of the current object’s values.

Private Members

std::shared_ptr< nexthop_group_entry_impl_t > pimpl

Friends

friend std::ostream & operator<<: A utility stream operator that adds a string representation of nexthop_group_entry_t to the ostream.

class nexthop_group_t

#include <nexthop_group.h>

A nexthop group.

A nexthop group represents encapsulation and IP addressing information to be used with a policy routing application.

Public Functions

nexthop_group_t()

nexthop_group_t(std::string name, nexthop_group_encap_t type)

nexthop_group_t(std::string name, nexthop_group_encap_t type, nexthop_group_gre_key_t gre_key_type)

nexthop_group_t(std::string name, ip_addr_t const & source_ip)

nexthop_group_t(std::string name, ip_addr_t const & source_ip, std::map< uint16_t, nexthop_group_entry_t > const & nexthops)

nexthop_group_t(const nexthop_group_t & other)

nexthop_group_t & operator=(nexthop_group_t const & other)

std::string name() const: Getter for ‘name’: the unique name of the nexthop group.

nexthop_group_encap_t type() const: Getter for ‘type’: the type of packet encapsulation used on the group.

nexthop_group_gre_key_t gre_key_type() const: Getter for ‘gre_key_type’: the key of the GRE tunnel.

uint16_t ttl() const: Getter for ‘ttl’: the TTL set in frame headers of IP-in-IP or GRE tunnels.

void ttl_is(uint16_t ttl): Setter for ‘ttl’.

ip_addr_t source_ip() const: Getter for ‘source_ip’: the source IP used on frames sent on this group.

void source_ip_is(ip_addr_t const & source_ip): Setter for ‘source_ip’.

intf_id_t source_intf() const: Getter for ‘source_intf’: the source interface to use.

void source_intf_is(intf_id_t source_intf): Setter for ‘source_intf’.

bool autosize() const: Getter for ‘autosize’: Dynamic resizing configuration for the nexthop group. When set, unresolved entries from the nexthop group are not programmed into hardware, and packets will be hashed across the remaining reachable entries in the group. Disabled (i.e. set to false) by default.

void autosize_is(bool autosize): Setter for ‘autosize’.

uint16_t size() const: Utility method to return the number of entries configured in the nexthop group.

std::map< uint16_t, nexthop_group_entry_t > const & nexthops() const: Getter for ‘nexthops’: array index to nexthop group entry map.

void nexthops_is(std::map< uint16_t, nexthop_group_entry_t > const & nexthops): Setter for ‘nexthops’.

void nexthop_set(uint16_t key, nexthop_group_entry_t const & value): Inserts key/value pair to the map.

void nexthop_del(uint16_t key): Deletes the key/value pair from the map.

std::map< uint16_t, ip_addr_t > const & destination_ips() const: Getter for ‘destination_ips’: array index to IP address map.

void destination_ips_is(std::map< uint16_t, ip_addr_t > const & destination_ips): Setter for ‘destination_ips’.

void destination_ip_set(uint16_t key, ip_addr_t const & value): Inserts key/value pair to the map.

void destination_ip_del(uint16_t key): Deletes the key/value pair from the map.

bool counters_unshared() const: Getter for ‘counters_unshared’: Defines whether entry counters are unshared for the nexthop group. When set, do not share counter values between entries that share the same tunnel destination. Each entry will have its own unique counter. Disabled (i.e. set to false) by default.

void counters_unshared_is(bool counters_unshared): Setter for ‘counters_unshared’.

bool hierarchical_fecs_enabled() const: Getter for ‘hierarchical_fecs_enabled’: Enableing hierarchical fec resolution for programming nexthop group entries. If this flag is true, the entry resolved over a remote nexthop will be programmed hierarchically in the hardware, i.e., the entry is pointing to another FEC which resolves over other nexthops. If the flag is false, the entry resolved over a remote nexthop will be programmed with the final resolved nexthop directly. In case the remote nexthop is resolved over ECMP of nexthops one of the ECMP nexthops is chosen to be programmed for the entry, in order to maintain the size of the nexthop group. This flag is also required to be set to true in order to configure entries resolving over other nexthop groups. The flag is disabled (i.e set to false) by default.

void hierarchical_fecs_enabled_is(bool hierarchical_fecs_enabled): Setter for ‘hierarchical_fecs_enabled’.

bool operator==(nexthop_group_t const & other) const

bool operator!=(nexthop_group_t const & other) const

bool operator<(nexthop_group_t const & other) const

uint32_t hash() const: The hash function for type nexthop_group_t.

void mix_me(hash_mix & h) const: The hash mix function for type nexthop_group_t.

std::string to_string() const: Returns a string representation of the current object’s values.

Private Members

std::shared_ptr< nexthop_group_impl_t > pimpl

Friends

friend std::ostream & operator<<: A utility stream operator that adds a string representation of nexthop_group_t to the ostream.

nexthop_group¶

Type definitions in nexthop_group¶

Table of Contents

Previous topic

Next topic