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_entry_set(0, nhe1);
   nhg.nexthop_entry_set(1, nhe1);
   nhg.nexthop_entry_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.

class nexthop_group_iter_t

Private Functions

nexthop_group_iter_t(nexthop_group_iter_impl * const)

Friends

friend class 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.

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.

The present nexthop group types are all tunnel encapsulations. Each causes a variety of packet headers for packets using the group to be changed to appropriately encapsulate the frame.

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_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.

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 is the outermost label.

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

std::string to_string() const

Returns a string representation of the current object’s values.

Private Members

mpls_action_t action_type_

std::forward_list< mpls_label_t > label_stack_

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)

uint64_t packets() const

uint64_t bytes() 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

std::string to_string() const

Returns a string representation of the current object’s values.

Private Members

uint64_t packets_

uint64_t bytes_

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_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’.

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

std::string to_string() const

Returns a string representation of the current object’s values.

Private Members

nexthop_group_mpls_action_t mpls_action_

ip_addr_t nexthop_

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)

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’: For GRE nexthop groups, how to set the GRE tunnel key.

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’.

uint16_t size() const

The maximum size of the nexthop group in entries.

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 persistent() const

Getter for ‘persistent’: The source interface to use.

void persistent_is(bool persistent)

Setter for ‘persistent’.

bool operator==(nexthop_group_t const & other) const

bool operator!=(nexthop_group_t const & other) const

bool operator<(nexthop_group_t const & other) const

std::string to_string() const

Returns a string representation of the current object’s values.

Private Members

std::string name_

nexthop_group_encap_t type_

nexthop_group_gre_key_t gre_key_type_

uint16_t ttl_

ip_addr_t source_ip_

intf_id_t source_intf_

std::map< uint16_t, nexthop_group_entry_t > nexthops_

std::map< uint16_t, ip_addr_t > destination_ips_

bool persistent_

Friends

friend std::ostream & operator<<

A utility stream operator that adds a string representation of nexthop_group_t to the ostream.