Access Control Lists - ACLs

Netfilter is the packet filtering framework in SONiC as well as most other Linux distributions. There are a number of tools available for configuring access control lists (ACLs) in SONiC.

For an in depth discussion of ACLs, read the Cumulus Linux user guide.

ACL Configuration Flows

You configure ACLs in SONiC using:

  • The SONiC CONFIG_DB, defined in /etc/sonic/config_db.json.
  • The SONiC CLI.

You can also configure SONiC using the SONiC management framework and REST API. However, since they are not enabled in SONiC by default, they are beyond the scope of this topic.

Configure ACL Tables Using CONFIG_DB

The following table contains the CONFIG_DB schema. The schema is defined according to ABNF RFC 5234 syntax; refer to RFC 5234 for more information about the schema definition.

FieldValueDescription
keyACL_TABLE:nameThe name must be unique within the ACL_TABLE table. The name is used to reference this table from other places in the SONiC configuration database.
;fieldvalue
POLICY_DESC1*255VCHARThe W of the ACL policy table description, user defined description for the table.
TYPE1*255VCHARType of ACL table, every type of table defines the match/action a specific set of match and actions. See the next table below for details on the type field.
PORTS[0-INF]*port_nameThe list of ports to which this ACL table is applied, this field can be empty.
STAGE“INGRESS”/“EGRESS”ACL table stage, either ingress or egress.
SERVICES[0-INF]*service_nameList of services, valid only for TYPE=CTRLPLANE.

The TYPE field can be one of the following:

TypeBind Port Types SupportedMatch Fields SupportedSupported ACL Rule Actions
L3PORT, LAG
  • ETHER_TYPE
  • IP_TYPE
  • IP_PROTOCOL
  • SRC_IP
  • DST_IP
  • ICMP_TYPE
  • ICMP_CODE
  • L4_SRC_PORT
  • L4_DST_PORT
  • TCP_FLAGS
  • L4_DST_PORT_RANGE
  • L4_SRC_PORT_RANGE
  • PACKET_ACTION
  • REDIRECT_ACTION
  • DO_NOT_NAT_ACTION
  • MIRROR_INGRESS_ACTION
  • MIRROR_EGRESS_ACTION
  • MIRROR_ACTION
L3V6PORT,LAG
  • ETHER_TYPE
  • IP_TYPE
  • IP_PROTOCOL
  • SRC_IPV6
  • DST_IPV6
  • ICMPV6_TYPE
  • ICMPV6_CODE
  • L4_SRC_PORT
  • L4_DST_PORT
  • TCP_FLAGS
  • L4_DST_PORT_RANGE
  • L4_SRC_PORT_RANGE
  • PACKET_ACTION
  • REDIRECT_ACTION
  • DO_NOT_NAT_ACTION
MIRRORPORT,LAG
  • ETHER_TYPE
  • IP_TYPE
  • IP_PROTOCOL
  • SRC_IP
  • DST_IP
  • ICMP_TYPE
  • ICMP_CODE
  • SRC_IPV6 (*)
  • DST_IPV6 (*)
  • ICMPV6_TYPE (*)
  • ICMPV6_CODE (*)
  • L4_SRC_PORT
  • L4_DST_PORT
  • TCP_FLAGS
  • L4_DST_PORT_RANGE
  • L4_SRC_PORT_RANGE
  • MIRROR_INGRESS_ACTION
  • MIRROR_EGRESS_ACTION
  • MIRROR_ACTION
MIRRORV6PORT,LAG
  • IP_TYPE
  • IP_PROTOCOL
  • SRC_IP
  • DST_IP
  • ICMP_TYPE
  • ICMP_CODE
  • SRC_IPV6 (*)
  • DST_IPV6 (*)
  • ICMPV6_TYPE (*)
  • ICMPV6_CODE (*)
  • L4_SRC_PORT
  • L4_DST_PORT
  • TCP_FLAGS
  • L4_DST_PORT_RANGE
  • L4_SRC_PORT_RANGE
  • MIRROR_INGRESS_ACTION
  • MIRROR_EGRESS_ACTION
  • MIRROR_ACTION
MIRROR_DSCPPORT,LAG
  • DSCP
  • MIRROR_INGRESS_ACTION
  • MIRROR_EGRESS_ACTION
  • MIRROR_ACTION
PFCWDPORT
  • TC
Used internally by SONiC; not user configurable.
DTEL_FLOW_WATCHLISTSWITCHNot supported on NVIDIA Spectrum ASICs.Not supported on NVIDIA Spectrum ASICs.
DTEL_DROP_WATCHLISTSWITCHNot supported on NVIDIA Spectrum ASICs.Not supported on NVIDIA Spectrum ASICs.

Notes

  • (*) Depends on whether the ASIC supports mirroring IPv6 packets and supports IPv6 match and IPv4 match in single ACL table. Mellanox ASICs support IPv6 mirroring, however do not support IPv4 and IPv6 match in the same ACL table. SONiC creates two ACL tables in HW, so that from the user perspective configuring IPv6 rules in ACL table MIRROR should be possible.
  • MIRROR_ACTION is an alias for MIRROR_INGRESS_ACTION.
  • MIRROR_INGRESS_ACTION and MIRROR_EGRESS_ACTION have their own limitations with regard to ACL table stage. See, the ACL rule section below.
  • The VLAN bind point is not supported by SONiC; this is a SONiC orchagent limitation.
  • The bind point is layer 2; currently SONiC does not support binding an ACL table to a RIF.

Configure ACL Tables Using the SONiC CLI

You create an ACL table with the SONiC CLI using the config acl add table command. You need to specify a table name and type (see above for table types). The command takes the following options:

OptionDescription
-d, –description “TEXT”A brief description of the table.
-p, –ports “TEXT”A list of ports included in the table. Both physical and virtual ports are acceptable.
-s, –stage [ingress|egress]ACL table stage, which indicates whether the table is used for ingress or egress.

Example of ACL table creation and removal:

admin@switch:~$ sudo config acl add table L3_INGRESS_1 L3 --description="L3 ingress table" --stage=ingress --ports="Ethernet0,Ethernet124,PortChannel0001"
admin@switch:~$ sudo config save -y

To display ACL tables configured in the system, run:

admin@switch:~$ show acl table  
Name          Type    Binding          Description       Stage
------------  ------  ---------------  ----------------  -------
L3_INGRESS_1  L3      Ethernet0        L3 ingress table  ingress
                      Ethernet124
                      PortChannel0001

It’s a good idea to check /var/log/syslog to verify that the ACL table was created successfully.

To remove an ACL table, run:

admin@switch:~$ sudo config acl remove table L3_INGRESS_1
admin@switch:~$ sudo config save -y

Configure ACL Rules

You configure ACL rules in JSON format in the SONiC CONFIG_DB; you cannot create ACL rules with the SONiC CLI.

Look at table types above to see if a match and action pair is supported for particular table type. Several match rules are possible.

The following table shows the CONFIG_DB schema.

FieldValueDescription
keyACL_RULE_TABLE:table_name:rule_nameThe key of the rule entry in the table, the sequence is the order of the rules when the packet is filtered by the ACL “policy_name”. A rule is always associated with a policy.
;fieldvalue
priority1*3DIGITThe rule priority. Valid values range are platform dependent. For example, on NVIDIA Spectrum switches, the minimum priority is 0 and the maximum priority is 16381. You can always check it in logs:
admin@switch:~$ show log | grep ‘Get ACL entry priority values’
Apr 22 16:46:55.967195 switch NOTICE swss#orchagent: :- init: Get ACL entry priority values, min: 0, max: 16381
packet_action“forward”/“drop”/“redirect:“redirect_parameter/“do_not_nat”An action when the fields are matched. There is a parameter in case of packet_action="redirect". This parameter defines a destination for redirected packets and can be:
- The name of a physical port, like “Ethernet10”
- The name of a LAG port, like “PortChannel5”.
- The next hop IP address (in a global), like “10.0.0.1”.
- The next hop IP address and VRF, like “10.0.0.2@Vrf2”.
- The next hop IP address and interface name, like “10.0.0.3@Ethernet1”.
- The next hop group set of next hops, like “10.0.0.1,10.0.0.3@Ethernet1”.
redirect_action1*255CHARThe redirect parameter. This parameter defines a destination for redirected packets and can be:
- The name of a physical port, like “Ethernet10”.
- The name of LAG port, like “PortChannel5”.
- The next hop IP address (in a global), like “10.0.0.1”.
- The next hop IP address and VRF, like “10.0.0.2@Vrf2”.
- The next hop IP address and interface name, like “10.0.0.3@Ethernet1”.
- The next hop group set of next hops, like “10.0.0.1,10.0.0.3@Ethernet1”.
mirror_action1*255VCHARRefer to the mirror session. By default this is an ingress mirror action.
mirror_ingress_action1*255VCHARRefer to the mirror session.
mirror_egress_action1*255VCHARRefer to the mirror session.
ether_typeh16Ethernet type field.
ip_typeip_typesOptions for the l2_protocol_type field.
ip_protocolh8Options for the l3_protocol_type field.
src_ipipv4_prefixOptions for the source IPv4 address (and mask) field.
dst_ipipv4_prefixOptions for the destination IPv4 address (and mask) field.
src_ipv6ipv6_prefixOptions for the source IPv6 address (and mask) field.
dst_ipv6ipv6_prefixOptions for the destination IPv6 address (and mask) field.
l4_src_portport_numThe source L4 port.
l4_dst_portport_numThe destination L4 port.
l4_src_port_rangeport_num_L-port_num_HThe source port range of the L4 ports field.
l4_dst_port_rangeport_num_L-port_num_HThe destination port range of the L4 ports field.
tcp_flagsh8/h8TCP flags field and mask.
dscph8The DSCP field, which is only available for mirror table type.
icmp_typeh8/h8The ICMP type and mask.
icmpv6_typeh8/h8The ICMPv6 type and mask.
icmp_codeh8/h8The ICMP code and mask.
icmpv6_codeh8/h8The ICMPv6 code and mask.
in_portsstringA comma-separated list of inbound ports to match.
out_portsstringA comma-separated list of outbound ports to match value annotations.
ip_typesany | ip | ipv4 | ipv4any | non_ipv4 | ipv6any | non_ipv6Type of IP address. On NVIDIA Spectrum switches, an IP type of any requires at least one additional match rule besides any, such as "ETHER_TYPE": "2048".
port_num1*5DIGITA port number between 0 and 65535.
port_num_L1*5DIGITA port number between 0 and 65535. The port_num_L must be lower than port_num_H.
port_num_H1*5DIGITA port number between 0 and 65535. The port_num_H must be higher than port_num_L.
ipv6_prefix6( h16 “:” ) ls32
“::” 5( h16 “:” ) ls32
[ h16 ] “::” 4( h16 “:” ) ls32
[ *1( h16 “:” ) h16 ] “::” 3( h16 “:” ) ls32
[ *2( h16 “:” ) h16 ] “::” 2( h16 “:” ) ls32
[ *3( h16 “:” ) h16 ] “::” h16 “:” ls32
[ *4( h16 “:” ) h16 ] “::” ls32
[ *5( h16 “:” ) h16 ] “::” h16
[ *6( h16 “:” ) h16 ] “::”
h81*2HEXDIG
h161*4HEXDIG
ls32( h16 “:” h16 ) / IPv4address
ipv4_prefixdec-octet “.” dec-octet “.” dec-octet “.” dec-octet “/” %d1-32
dec-octetDIGIT0-9
%x31-39 DIGIT10-99
“1” 2DIGIT100-199
“2” %x30-34 DIGIT200-249

ACL Rule Example

"ACL_RULE": {
    "DATAACL|DEFAULT_RULE": {
        "PRIORITY": "1",
        "PACKET_ACTION": "DROP",
        "ETHER_TYPE": "2048"
    },
    "DATAACL|RULE_1": {
        "PRIORITY": "9999",
        "PACKET_ACTION": "DROP",
        "SRC_IP": "10.0.0.2/32"
    },
    "DATAACL|RULE_2": {
        "PRIORITY": "9998",
        "PACKET_ACTION": "DROP",
        "DST_IP": "192.168.0.16/32"
    },
}