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 created by this application.

virtual acl_iter_t acl_all_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 created by this application.

virtual acl_rule_ip_iter_t acl_all_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 created by this application.

virtual acl_rule_eth_iter_t acl_all_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 for this application, else false.

virtual bool acl_all_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: Enable or disable counters for the ACL. Note: Must call commit() for setting to apply.

virtual void acl_fragments_enabled_set(acl_key_t const &, bool) = 0: Enable or disable fragments matching on the ACL. Note: Must call commit() for setting to apply.

virtual bool stream_allowed(ip_addr_t const &, ip_addr_t const &, uint8_t = 0, uint16_t = 0, uint16_t = 0) = 0

Check a connection against any applied ACL to determine if it should be dropped, incrementing the ACL counter if so. For use with SOCK_STREAM or SOCK_DGRAM.

Return

false if connection should be dropped, true otherwise.

Parameters

ip_addr_t -
Source IP address
ip_addr_t -
Destination IP address
uint8_t -
Protocol (optional)
uint16_t -
Source port (optional)
uint16_t -
Destination port (optional)

virtual bool dgram_allowed(ip_addr_t const &, ip_addr_t const &, uint16_t, uint16_t, uint8_t, uint8_t, intf_id_t const &) = 0

Check a packet against any applied ACL to determine if it should be dropped, incrementing the ACL counter if so. For use with SOCK_DGRAM only.

Return

false if the packet should be dropped, true otherwise.

Parameters

ip_addr_t -
Source IP address
ip_addr_t -
Destination IP address
uint16_t -
Source port
uint16_t -
Destination port
uint8_t -
Time to live (IPv4) or hop limit (IPv6)
uint8_t -
Type of service (IPv4) or traffic class (IPv6)
intf_id_t -
Recipient interface

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_ttl_spec_t(const acl_ttl_spec_t & other)

acl_ttl_spec_t & operator=(acl_ttl_spec_t const & other)

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

bool operator<(acl_ttl_spec_t const & other) const

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

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

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

Private Members

std::shared_ptr< acl_ttl_spec_impl_t > pimpl

Friends

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_port_spec_t(const acl_port_spec_t & other)

acl_port_spec_t & operator=(acl_port_spec_t const & other)

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

bool operator<(acl_port_spec_t const & other) const

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

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

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

Private Members

std::shared_ptr< acl_port_spec_impl_t > pimpl

Friends

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

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

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

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_rule_base_t(const acl_rule_base_t & other)

acl_rule_base_t & operator=(acl_rule_base_t const & other)

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)

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

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

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

Protected Functions

acl_rule_base_t()

Private Members

std::shared_ptr< acl_rule_base_impl_t > pimpl

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

acl_rule_ip_t(const acl_rule_ip_t & other)

acl_rule_ip_t & operator=(acl_rule_ip_t const & other)

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)

std::string nexthop_group() const: Getter for ‘nexthop_group’: match nexthop-group in the FIB lookup result.

void nexthop_group_is(std::string nexthop_group): Setter for ‘nexthop_group’.

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’: IPv4: 0..63: DSCP value to match; IPv6: 0..255: DSCP + ECN bits (traffic class byte). Warning: for IPv6 the DSCP value must be shifted (ipv4_dscp<<2). Warning: for IPV4 also need to call match_ip_priority. Warning: mask default is 0 (all bits are wildcarded).

void priority_value_is(uint8_t priority_value): Setter for ‘priority_value’.

uint8_t priority_mask() const: Getter for ‘priority_mask’: 0..63 for IPv4; 0..255 for IPv6. Warning: the default mask is 0: any dscp will match.

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’: IPv4: enable for priority_{value,mask} to be effective; IPv6: dont care (not needed for match to happen).

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

bool operator<(acl_rule_ip_t const & other) const

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

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

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

Private Members

std::shared_ptr< acl_rule_ip_impl_t > pimpl

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

acl_rule_eth_t(const acl_rule_eth_t & other)

acl_rule_eth_t & operator=(acl_rule_eth_t const & other)

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)

uint32_t eth_protocol() const

void eth_protocol_is(uint32_t eth_protocol)

bool operator==(acl_rule_eth_t const & other) const

bool operator!=(acl_rule_eth_t const & other) const

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

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

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

Private Members

std::shared_ptr< acl_rule_eth_impl_t > pimpl

Friends

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

acl¶

Type definitions in acl¶

Table of Contents

Previous topic

Next topic