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);
Typedefs
A rule in an IP ACL.
A rule in an Ethernet ACL.
An ACL handler.
Derive from this class to react to ACL hardware synchronization events.
Public Functions
Watches updates to synchronization status for all ACLs. This defaults to false at handler construction time.
If true, receive ACL sync status notifications, else do not.
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.
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.
An ACL iterator.
Private Functions
Friends
An IP ACL rule iterator.
Private Functions
Friends
An Ethernet ACL rule iterator.
Private Functions
Friends
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
Iterates over all ACLs.
Iterates over the rules with an IP ACL.
Iterates over the rules with an Ethernet ACL.
Configuration ACL existence test.
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.
The ACL key to modify (name and ACL type)
ACL sequence number
ACL rule to set at sequence number
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.
The ACL key to modify (name and ACL type)
ACL sequence number (in the range 1..MAXINT)
ACL rule to set at sequence number
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.
The ACL key to modify (name and ACL type)
ACL sequence number to remove
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.
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).
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.
Enable or disable counters for the ACL. Note: Must call commit() for setting to apply.
Enable or disable fragments matching on the ACL. Note: Must call commit() for setting to apply.
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.
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.
Protected Functions
Private Members
Friends
Enums
Values:
The ACL type, of which valid types are either IPv4, IPv6, or Ethernet.
Values:
The direction in which an ACL is applied. To apply in both directions, use both operations in order.
Values:
The type of range operator for TTL and port specifications below.
Values:
The action to take for an individual ACL rule.
Values:
TCP flags used in IP rules to specify which TCP flags to match.
Values:
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
Getter for ‘oper’: the type of range, note, BETWEEN is not supported.
Setter for ‘oper’.
Getter for ‘ttl’: the type of range, note, BETWEEN is not supported.
Setter for ‘ttl’.
The hash function for type acl_ttl_spec_t.
Returns a string representation of the current object’s values.
Protected Attributes
Friends
A utility stream operator that adds a string representation of acl_ttl_spec_t to the ostream.
A UDP or TCP port specifier.
Pick one of either:
Public Functions
Default constructor, matches any port.
Prepend one port to the list.
Remove all matching port elements.
The hash function for type acl_port_spec_t.
Returns a string representation of the current object’s values.
Protected Attributes
Friends
A utility stream operator that adds a string representation of acl_port_spec_t to the ostream.
An ACL key is the combination of its name and ACL type (IPv4, IPv6 or ETH).
Public Functions
The hash function for type acl_key_t.
Returns a string representation of the current object’s values.
Private Members
Friends
A utility stream operator that adds a string representation of acl_key_t to the ostream.
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:
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
The hash function for type acl_rule_base_t.
Returns a string representation of the current object’s values.
Protected Functions
Private Members
Friends
A utility stream operator that adds a string representation of acl_rule_base_t to the ostream.
An individual ACL rule for IPv4 or IPv6 ACLs.
Public Functions
Getter for ‘nexthop_group’: match nexthop-group in the FIB lookup result.
Setter for ‘nexthop_group’.
Getter for ‘tcp_flags’: bitmask of TCP flags to match, if set.
Setter for ‘tcp_flags’.
Getter for ‘established’: match “established” connections.
Setter for ‘established’.
Getter for ‘icmp_type’: match a specific ICMP type and code, the default value 0xFFFF matches all types or codes.
Setter for ‘icmp_type’.
Getter for ‘icmp_code’: match a specific ICMP type and code.
Setter for ‘icmp_code’.
Getter for ‘priority_value’: 0..63, DSCP match to value (IPv4); traffic class (IPv6).
Setter for ‘priority_value’.
Getter for ‘priority_mask’: supported for IPv6 only.
Setter for ‘priority_mask’.
Getter for ‘match_fragments’: match IP fragments.
Setter for ‘match_fragments’.
Getter for ‘match_ip_priority’: match DSCP (IPv4) or TE (IPv6) data provided in priority_{value,mask}.
Setter for ‘match_ip_priority’.
The hash function for type acl_rule_ip_t.
Returns a string representation of the current object’s values.
Private Members
Friends
A utility stream operator that adds a string representation of acl_rule_ip_t to the ostream.
An Ethernet ACL, which can be applied to Ethernet, Vlan, and MLAG interfaces.
Public Functions
The hash function for type acl_rule_eth_t.
Returns a string representation of the current object’s values.
Private Members
Friends
A utility stream operator that adds a string representation of acl_rule_eth_t to the ostream.