acl

Access Control List (ACL) management module.

In EOS, an ACL is a collection of rules ordered by a sequence number. Each rule defines some filter criteria to match and an action determining whether matching traffic will be considered by the ACL.

ACLs are defined to match Ethernet, IPv4 or IPv6 headers and can be used with a variety of EOS features, including traffic filters on interfaces (supported by this module) and as traffic classifiers for class maps (eos/class_map.h).

This module offers an ACL manager, used to define ACLs in the system configuration and to apply them as traffic filters to network interfaces.

To react to the status of traffic filter application, an ACL handler is also provided with callback handlers you can implement to react to the ACL programming status on error or success.

Here’s an example of the basic workflow for defining and configuring an ACL, then applying it to Ethernet1:

 #include <eos/acl.h>
 #include <eos/ip.h>

 // The result of eos::sdk::get_acl_mgr() is in variable
 // acl_mgr_ within this example.

 // Deny all web traffic originating at srcaddr
 eos::ip_addr_mask_t srcaddr(eos::ip_addr_t("192.0.2.1"), 32);
 eos::ip_addr_mask_t dstaddr(eos::ip_addr_t("10.0.0.0"), 8);
 eos::acl_key_t acl_key("name_of_acl", eos::ACL_TYPE_IPV4);
 eos::acl_rule_ip_t rule1;

 rule1.source_addr_is(srcaddr);
 rule1.destination_addr_is(dstaddr);
 rule1.source_port_is(80);
 rule1.action_is(eos::ACL_DENY);

 // Configure the ACL and commit it to current configuration
 acl_mgr_->acl_rule_set(acl_key, 1, rule1);
 acl_mgr_->acl_commit();

 // Now apply the ACL for traffic filtering on Ethernet1 inbound
 acl_mgr_->acl_apply(acl_key, eos::intf_id_t("Ethernet1"), eos::ACL_IN, true);

namespace eos

Typedefs

typedef std::pair< uint32_t, acl_rule_ip_t > acl_rule_ip_entry_t

A rule in an IP ACL.

typedef std::pair< uint32_t, acl_rule_eth_t > acl_rule_eth_entry_t

A rule in an Ethernet ACL.

class acl_handler
#include <acl.h>

An ACL handler.

Derive from this class to react to ACL hardware synchronization events.

Public Functions

acl_handler(acl_mgr *)
acl_mgr * get_acl_mgr() const
void watch_all_acls(bool)

Watches updates to synchronization status for all ACLs. This defaults to false at handler construction time.

Parameters
  • bool -

    If true, receive ACL sync status notifications, else do not.

virtual void on_acl_sync()

Called upon hardware successfully committing all pending transactions.

It may be called more than once for a single transaction, or only once for a whole bunch of separate ACL updates. In fact, if someone updates an ACL in the CLI, this function may get called, i.e., it can get called once for zero transactions.

virtual void on_acl_sync_fail(std::string const & linecard, std::string const & message)

Called upon a problem stopping ACL configuration from being committed.

This indicates that the ACL config (as stored in Sysdb) cannot be loaded into hardware, ever. It must be changed in some way to get Sysdb and the hardware back in sync. The most common problem, of course, is too many ACLs or ACL entries. It is up to you to find some things to delete, commit those deletions, and then see if things fit once again (on_acl_sync() will get called if they do, or on_acl_sync_fail() will get called again if they don’t). Note you may be notified more than once of the same problem, and you may be notified of problems that have nothing to do with you, such as an operator at the CLI doing something unsupported.

class acl_iter_t
#include <acl.h>

An ACL iterator.

Private Functions

acl_iter_t(acl_iter_impl * const)

Friends

friend class acl_iter_impl
class acl_rule_ip_iter_t
#include <acl.h>

An IP ACL rule iterator.

Private Functions

acl_rule_ip_iter_t(acl_rule_ip_iter_impl * const)

Friends

friend class acl_rule_ip_iter_impl
class acl_rule_eth_iter_t
#include <acl.h>

An Ethernet ACL rule iterator.

Private Functions

acl_rule_eth_iter_t(acl_rule_eth_iter_impl * const)

Friends

friend class acl_rule_eth_iter_impl
class acl_mgr
#include <acl.h>

The ACL manager.

This manager provides access to current ACL configuration, creation, modification and deletion of ACLs, and functions to commit changes, apply ACLs to interfaces as well as manage fragments mode and enabling counters.

When managing ACLs, you provide give an ACL key to modify, a “sequence number” which starts at 1 and goes up to MAXINT, and for set operations, the rule to set. Note: you must call commit() for your changes here to get pushed into the hardware, and once you have started setting rules, you must call acl_commit() prior to any calls to acl_apply(), else the manager will panic(). Note that extremely large numbers of ACLs or rules per ACL can result in undefined behavior, including a switch reload.

Public Functions

virtual ~acl_mgr()
virtual acl_iter_t acl_iter() const = 0

Iterates over all ACLs.

virtual acl_rule_ip_iter_t acl_rule_ip_iter(acl_key_t const &) const = 0

Iterates over the rules with an IP ACL.

virtual acl_rule_eth_iter_t acl_rule_eth_iter(acl_key_t const &) const = 0

Iterates over the rules with an Ethernet ACL.

virtual bool acl_exists(acl_key_t const &) const = 0

Configuration ACL existence test.

Return
true if an ACL with the same name and type (i.e., key) exists in the configuration, else false.

virtual void acl_rule_set(acl_key_t const &, uint32_t, acl_rule_ip_t const &) = 0

Adds an IP ACL rule to an ACL.

If the ACL key doesn’t exist, it will be created. If the ACL type is not the same as the rule type, panic() is called.

Parameters
  • acl_key_t -

    The ACL key to modify (name and ACL type)

  • uint32_t -

    ACL sequence number

  • acl_rule_ip_t -

    ACL rule to set at sequence number

virtual void acl_rule_set(acl_key_t const &, uint32_t, acl_rule_eth_t const &) = 0

Adds an Ethernet (MAC) ACL rule to an ACL.

If the ACL doesn’t exist, it will be created before the rule is added to it: there is no explicit “create ACL” operation. If the ACL type is not the same as the rule type (i.e., Ethernet), panic() is called.

Parameters
  • acl_key_t -

    The ACL key to modify (name and ACL type)

  • uint32_t -

    ACL sequence number (in the range 1..MAXINT)

  • acl_rule_eth_t -

    ACL rule to set at sequence number

virtual void acl_rule_del(acl_key_t const &, uint32_t) = 0

Removes a rule from an ACL.

If the ACL key doesn’t exist, that is a no op. If there is no rule at the sequence number, that is also a no op.

Parameters
  • acl_key_t -

    The ACL key to modify (name and ACL type)

  • uint32_t -

    ACL sequence number to remove

virtual void acl_commit() = 0

Commits all rule changes and application changes made above to all ACLs.

Pushes ACLs into Sysdb’s active configuration. This commit cannot fail, but it can lead to a state where not all ACLs can be loaded into hardware. You will be notified via on_acl_sync() when this commit and all other outstanding operations such as interface applications are loaded into hardware, or on_acl_sync_fail() if the newly committed configuration can’t be loaded. If there are no changes pending and you call this function, you will get one of those callbacks depending on whether the current state in Sysdb can be loaded into hardware or not.

virtual void acl_del(acl_key_t const &) = 0

Deletes the ACL.

Removes all rules and removes the ACL from all interfaces. Any pending changes to the ACL are discarded. Is effective immediately (no commit or commit notification).

virtual void acl_apply(acl_key_t const &, intf_id_t, acl_direction_t, bool) = 0

Requests that an ACL be (un)applied on the given interface and direction.

ACL is loaded into hardware asynchronously. Like commit(), this function results in a call to your handler when we have applied, or failed to apply, this ACL configuration. That is, you do not get a handler callback per call; you get a handler callback when everything is loaded into hardware, or when we notice problems.

API call ordering note: any acl_rule_set() or acl_rule_del() calls be followed by an acl_commit() prior to calling this function else a panic() will occur.

virtual void acl_counters_enabled_set(acl_key_t const &, bool) = 0

Immediately enable or disable counters for the ACL.

virtual void acl_fragments_enabled_set(acl_key_t const &, bool) = 0

Immediately enable or disable fragments matching on the ACL.

Protected Functions

acl_mgr()

Private Members

acl_mgr

Friends

friend class acl_handler

Type definitions in acl

namespace eos

Enums

Anonymous enum

Values:

  • ALL_ICMP = 65535 -
acl_type_t enum

The ACL type, of which valid types are either IPv4, IPv6, or Ethernet.

Values:

  • ACL_TYPE_NULL -
  • ACL_TYPE_IPV4 -
  • ACL_TYPE_IPV6 -
  • ACL_TYPE_ETH -
  • ACL_TYPE_MPLS -
acl_direction_t enum

The direction in which an ACL is applied. To apply in both directions, use both operations in order.

Values:

  • ACL_DIRECTION_NULL -
  • ACL_IN -
  • ACL_OUT -
acl_range_operator_t enum

The type of range operator for TTL and port specifications below.

Values:

  • ACL_RANGE_NULL -
  • ACL_RANGE_ANY -
  • ACL_RANGE_EQ -
  • ACL_RANGE_GT -
  • ACL_RANGE_LT -
  • ACL_RANGE_NEQ -
  • ACL_RANGE_BETWEEN -
acl_action_t enum

The action to take for an individual ACL rule.

Values:

  • ACL_ACTION_NULL -
  • ACL_PERMIT -
  • ACL_DENY -
acl_tcp_flag_t enum

TCP flags used in IP rules to specify which TCP flags to match.

Values:

  • ACL_TCP_NULL -
  • ACL_TCP_FIN = 1 -
  • ACL_TCP_SYN = 2 -
  • ACL_TCP_RST = 4 -
  • ACL_TCP_PSH = 8 -
  • ACL_TCP_ACK = 16 -
  • ACL_TCP_URG = 32 -
class acl_ttl_spec_t
#include <acl.h>

A TTL specifier, used in an IP ACL rule to define TTLs to match.

Create an instance of the classes below, such as a acl_ttl_spec_gt_t to specify matching TTLs greater than the value passed.

Public Functions

acl_ttl_spec_t()
acl_ttl_spec_t(acl_range_operator_t oper, uint8_t ttl)
acl_range_operator_t oper() const

Getter for ‘oper’: the type of range, note, BETWEEN is not supported.

void oper_is(acl_range_operator_t oper)

Setter for ‘oper’.

uint8_t ttl() const

Getter for ‘ttl’: the type of range, note, BETWEEN is not supported.

void ttl_is(uint8_t ttl)

Setter for ‘ttl’.

bool operator==(acl_ttl_spec_t const & other) const
bool operator!=(acl_ttl_spec_t const & other) const
std::string to_string() const

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

Protected Attributes

acl_range_operator_t oper_
uint8_t ttl_

Friends

friend class acl_internal
friend std::ostream & operator<<

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

class acl_port_spec_t
#include <acl.h>

A UDP or TCP port specifier.

Pick one of either:

  • acl_port_spec_eq_t : Matches 1-10 port numbers.
  • acl_port_spec_neq_t : Doesn’t match these 1-10 ports.
  • acl_port_spec_lt_t : Matches ports less than the value.
  • acl_port_spec_gt_t : Matches ports greater than the value.
  • acl_port_spec_between_t : Matches ports between the two values.

Public Functions

acl_port_spec_t()

Default constructor, matches any port.

acl_port_spec_t(acl_range_operator_t oper, std::list< uint16_t > const & ports)
acl_range_operator_t oper() const
void oper_is(acl_range_operator_t oper)
std::list< uint16_t > const & ports() const
void ports_is(std::list< uint16_t > const & ports)
void port_set(uint16_t const & ports)

Prepend one port to the list.

void port_del(uint16_t const & ports)

Remove all matching port elements.

bool operator==(acl_port_spec_t const & other) const
bool operator!=(acl_port_spec_t const & other) const
std::string to_string() const

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

Protected Attributes

acl_range_operator_t oper_
std::list< uint16_t > ports_

Friends

friend class acl_internal
friend std::ostream & operator<<

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

class acl_key_t
#include <acl.h>

An ACL key is the combination of its name and ACL type (IPv4, IPv6 or ETH).

Public Functions

acl_key_t()
acl_key_t(std::string const & acl_name, acl_type_t acl_type)
std::string acl_name() const
acl_type_t acl_type() const
bool operator()(acl_key_t const & lhs, acl_key_t const & rhs) const
bool operator==(acl_key_t const & other) const
bool operator!=(acl_key_t const & other) const
std::string to_string() const

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

Private Members

std::string acl_name_
acl_type_t acl_type_

Friends

friend std::ostream & operator<<

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

class acl_rule_base_t
#include <acl.h>

Following are classes that represent access lists (ACLs). Access lists are sequences of rules specifying per-packet rules filters apply to either IPv4, IPv6 or ETH (layer 2) traffic and are attached to traffic arriving (in) or leaving (out) on zero or more interfaces.

To use ACL rules in these libraries, construct the appropriate concrete type of rule you desire, either a: * acl_rule_ip_t or a * acl_rule_eth_t

Base parameters common to all filter types are defined on the parent acl_base_filter_t, such as “log” to enable logging of packets matching the rule, and the action applied to packets matching the rule.

Base ACL rule class containing common fields. Instead of this, instantiate one of the concrete rule classes.

Public Functions

acl_action_t action() const
void action_is(acl_action_t action)
bool log() const
void log_is(bool log)
bool tracked() const
void tracked_is(bool tracked)
std::string to_string() const

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

Protected Functions

acl_rule_base_t()

Private Members

acl_action_t action_
bool log_
bool tracked_

Friends

friend std::ostream & operator<<

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

class acl_rule_ip_t
#include <acl.h>

An individual ACL rule for IPv4 or IPv6 ACLs.

Public Functions

acl_rule_ip_t()
vlan_id_t vlan() const
void vlan_is(vlan_id_t vlan)
vlan_id_t vlan_mask() const
void vlan_mask_is(vlan_id_t vlan_mask)
vlan_id_t inner_vlan() const
void inner_vlan_is(vlan_id_t inner_vlan)
vlan_id_t inner_vlan_mask() const
void inner_vlan_mask_is(vlan_id_t inner_vlan_mask)
uint8_t ip_protocol() const
void ip_protocol_is(uint8_t ip_protocol)
acl_ttl_spec_t ttl() const
void ttl_is(acl_ttl_spec_t ttl)
ip_addr_mask_t source_addr() const
void source_addr_is(ip_addr_mask_t const & source_addr)
ip_addr_mask_t destination_addr() const
void destination_addr_is(ip_addr_mask_t const & destination_addr)
acl_port_spec_t source_port() const
void source_port_is(acl_port_spec_t source_port)
acl_port_spec_t destination_port() const
void destination_port_is(acl_port_spec_t destination_port)
uint16_t tcp_flags() const

Getter for ‘tcp_flags’: bitmask of TCP flags to match, if set.

void tcp_flags_is(uint16_t tcp_flags)

Setter for ‘tcp_flags’.

bool established() const

Getter for ‘established’: match “established” connections.

void established_is(bool established)

Setter for ‘established’.

uint16_t icmp_type() const

Getter for ‘icmp_type’: match a specific ICMP type and code, the default value 0xFFFF matches all types or codes.

void icmp_type_is(uint16_t icmp_type)

Setter for ‘icmp_type’.

uint16_t icmp_code() const

Getter for ‘icmp_code’: match a specific ICMP type and code.

void icmp_code_is(uint16_t icmp_code)

Setter for ‘icmp_code’.

uint8_t priority_value() const

Getter for ‘priority_value’: 0..63, DSCP match to value (IPv4); traffic class (IPv6).

void priority_value_is(uint8_t priority_value)

Setter for ‘priority_value’.

uint8_t priority_mask() const

Getter for ‘priority_mask’: supported for IPv6 only.

void priority_mask_is(uint8_t priority_mask)

Setter for ‘priority_mask’.

bool match_fragments() const

Getter for ‘match_fragments’: match IP fragments.

void match_fragments_is(bool match_fragments)

Setter for ‘match_fragments’.

bool match_ip_priority() const

Getter for ‘match_ip_priority’: match DSCP (IPv4) or TE (IPv6) data provided in priority_{value,mask}.

void match_ip_priority_is(bool match_ip_priority)

Setter for ‘match_ip_priority’.

bool operator==(acl_rule_ip_t const & other) const
bool operator!=(acl_rule_ip_t const & other) const
std::string to_string() const

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

Private Members

vlan_id_t vlan_
vlan_id_t vlan_mask_
vlan_id_t inner_vlan_
vlan_id_t inner_vlan_mask_
uint8_t ip_protocol_
acl_ttl_spec_t ttl_
ip_addr_mask_t source_addr_
ip_addr_mask_t destination_addr_
acl_port_spec_t source_port_
acl_port_spec_t destination_port_
uint16_t tcp_flags_
bool established_
uint16_t icmp_type_
uint16_t icmp_code_
uint8_t priority_value_
uint8_t priority_mask_
bool match_fragments_
bool match_ip_priority_

Friends

friend std::ostream & operator<<

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

class acl_rule_eth_t
#include <acl.h>

An Ethernet ACL, which can be applied to Ethernet, Vlan, and MLAG interfaces.

Public Functions

acl_rule_eth_t()
vlan_id_t vlan() const
void vlan_is(vlan_id_t vlan)
vlan_id_t vlan_mask() const
void vlan_mask_is(vlan_id_t vlan_mask)
vlan_id_t inner_vlan() const
void inner_vlan_is(vlan_id_t inner_vlan)
vlan_id_t inner_vlan_mask() const
void inner_vlan_mask_is(vlan_id_t inner_vlan_mask)
eth_addr_t source_addr() const
void source_addr_is(eth_addr_t source_addr)
eth_addr_t destination_addr() const
void destination_addr_is(eth_addr_t destination_addr)
eth_addr_t source_mask() const
void source_mask_is(eth_addr_t source_mask)
eth_addr_t destination_mask() const
void destination_mask_is(eth_addr_t destination_mask)
bool operator==(acl_rule_eth_t const & other) const
bool operator!=(acl_rule_eth_t const & other) const
std::string to_string() const

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

Private Members

vlan_id_t vlan_
vlan_id_t vlan_mask_
vlan_id_t inner_vlan_
vlan_id_t inner_vlan_mask_
eth_addr_t source_addr_
eth_addr_t destination_addr_
eth_addr_t source_mask_
eth_addr_t destination_mask_

Friends

friend std::ostream & operator<<

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

Table Of Contents

Previous topic

Arista EOS SDK reference guide

Next topic

agent