Skip to content

Commit d6d0822

Browse files
dks19dks19
authored
Merge pull request sonic-net#72 from abhishekd0/community_acl_enhancements
Community HLD for ACL enhancements
2 parents b283759 + a177c03 commit d6d0822

File tree

4 files changed

+320
-0
lines changed

4 files changed

+320
-0
lines changed

‎L24Services/Community/ACLEnhancements.md

+320
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,320 @@
1+
# ACL Enhancements in SONiC
2+
High level design document for ACL enhancements in SONiC.
3+
4+
# High Level Design Document
5+
Rev 0.1
6+
7+
# Table of Contents
8+
- **[List of Tables](#list-of-tables)**
9+
- **[Revision](#revision)**
10+
- **[About this Manual](#about-this-manual)**
11+
- **[Scope](#scope)**
12+
- **[Definition/Abbreviation](#definition_abbreviation)**
13+
- [Table 1: Abbreviations](#table-1-abbreviations)
14+
- **[1 Feature Overview](#1-feature-overview)**
15+
- [1.1 Requirements](#11-requirements)
16+
- [1.1.1 Functional Requirements](#111-functional-requirements)
17+
- [1.1.2 Configuration and Management Requirements](#112-configuration-and-management-requirements)
18+
- [1.1.3 Scalability Requirements](#113-scalability-requirements)
19+
- [1.1.4 Warm Boot Requirements](#114-warm-boot-requirements)
20+
- [1.2 Design Overview](#12-design-overview)
21+
- [1.2.1 Basic Approach](#121-basic-approach)
22+
- [1.2.2 Container](#122-container)
23+
- [1.2.3 SAI Overview](#123-sai-overview)
24+
- **[2 Functionality](#2-functionality)**
25+
- [2.1 Target Deployment Use Cases](#21-target-deployment-use-cases)
26+
- [2.2 Functional Description](#22-functional-description)
27+
- **[3 Design](#3-design)**
28+
- [3.1 Overview](#31-overview)
29+
- [3.2 DB Changes](#32-db-changes)
30+
- [3.2.1 CONFIG DB](#321-config-db)
31+
- *[3.2.1.1 ACL_TABLE Table](#3211-acl_table-table)*
32+
- *[3.2.1.2 ACL_RULE_TABLE Table for L2 ACL](#3212-acl_rule_table-table-for-l2-acl)*
33+
- *[3.2.1.3 ACL_RULE_TABLE Table additional actions](#3213-acl_rule_table-table-additional-actions)*
34+
- [3.2.2 APP DB](#322-app-db)
35+
- [3.2.3 STATE DB](#323-state-db)
36+
- [3.2.4 ASIC DB](#324-asic-db)
37+
- [3.2.5 COUNTER DB](#325-counter-db)
38+
- [3.3 Switch State Service Design](#33-switch-state-service-design)
39+
- [3.3.1 Orchestration Agent](#331-orchestration-agent)
40+
- *[3.3.1.1 ACL Orchagent](#3311-acl-orchagent)*
41+
- *[3.3.1.2 Policer Orchagent](#3312-policer-orchagent)*
42+
- [3.3.2 Other Process](#332-other-process)
43+
- [3.4 SyncD](#34-syncd)
44+
- [3.5 SAI](#35-sai)
45+
- [3.6 User Interface](#36-user-interface)
46+
- **[4 Flow Diagrams](#4-flow-diagrams)**
47+
- [4.1 Creating ACL rules with policer](#41-creating-acl-rules-with-policer)
48+
- [4.2 Deleting ACL rules with policer](#42-deleting-acl-rules-with-policer)
49+
- **[5 Error Handling](#5-error-handling)**
50+
- **[6 Serviceability and Debug](#6-serviceability-and-debug)**
51+
- **[7 Warm Boot Support](#7-warm-boot-support)**
52+
- **[8 Scalability](#8-scalability)**
53+
- **[9 Unit Test](#9-unit-test)**
54+
- **[10 Internal Design Information](#10-internal-design-information)**
55+
56+
# List of Tables
57+
[Table 1: Abbreviations](#table-1-abbreviations)
58+
59+
# Revision
60+
| Rev | Date | Author | Change Description |
61+
| :--: | :--------: | :-----------------: | ------------------ |
62+
| 0.1 | 09/25/2020 | Abhishek Dharwadkar | Initial version |
63+
64+
# About this Manual
65+
This document provides information about the ACL matches and actions enhancements feature implementation in SONiC.
66+
67+
# Scope
68+
This document describes the high level design of ACL enhancements feature. This document covers the changes done for orchestration agent and doesn't cover the UI aspects of the configuration. A follow up HLD will contain the UI related aspects.
69+
70+
# Definition/Abbreviation
71+
72+
## Table 1: Abbreviations
73+
| **Term** | **Meaning** |
74+
| -------- | ------------------- |
75+
| ACL | Access Control List |
76+
| API | Application Programmable Interface |
77+
| SAI | Switch Abstraction Interface |
78+
| JSON | JavaScript Object Notation |
79+
80+
81+
# 1 Feature Overview
82+
83+
Access-control lists (ACLs) are used to filter traffic based on the contents of the Layer 2 and/or Layer 3 packet header. ACLs configured and are then applied to interfaces on which traffic filtering is intended for the ACL to take effect.
84+
85+
## 1.1 Requirements
86+
87+
### 1.1.1 Functional Requirements
88+
89+
The following are the requirements for ACL enhancements:
90+
91+
1. Support Layer 2 ACL i.e. support match on Layer 2 fields like Source MAC, Destination MAC, PCP, etc.
92+
2. Support L3 header based matches like DSCP, ICMP type and ICMP code for IPv4 and IPv6 ACLs.
93+
3. Support ACL application at Switch level ie it will be applied to all interfaces ie Ethernet, Lags and Vlans.
94+
4. Support DSCP, COS Remarking and Policing QoS action.
95+
96+
### 1.1.2 Configuration and Management Requirements
97+
"config load" command will be used to read the configuration JSON file and set it into Config DB. Management framework is beyond the scope of this document.
98+
99+
### 1.1.3 Scalability Requirements
100+
The exact numbers will be silicon specific.
101+
### 1.1.4 Warm Boot Requirements
102+
103+
ACL functionality should be preserved across warm boot.
104+
105+
## 1.2 Design Overview
106+
### 1.2.1 Basic Approach
107+
This is an enhancement to existing ACL orchestration agent that's available in the community.
108+
109+
### 1.2.2 Container
110+
ACL and Policer orchestration agent present in the swss container will be enhanced to support the new functionality mentioned in this document. No new containers will be added.
111+
112+
### 1.2.3 SAI Overview
113+
Current SAI Specification https://github.com/opencomputeproject/SAI/blob/master/inc/saiacl.h already has the necessary support. No changes needed in SAI.
114+
115+
# 2 Functionality
116+
## 2.1 Target Deployment Use Cases
117+
1. Data traffic filtering using L2, L3 and L4 header fields.
118+
2. QoS actions can be used to fine tune traffic by classifying the traffic via ACL fields and taking actions like Remarking, Policing etc.
119+
120+
## 2.2 Functional Description
121+
ACLs are used to filter traffic based on packets L2/L3/L4 header. Currently the filtering is based on L3 and L4 headers. This enhancement will add the capability to filter traffic based on Layer 2 header and also to take DSCP, PCP remarking and Policing based on ACL.
122+
123+
# 3 Design
124+
## 3.1 Overview
125+
Following diagram describes a top level overview of the existing SONiC Switch components. ACL and Policer orchestration agents will be enhanced.
126+
127+
![Sonic SwSS components](images/ACLOverview.png)
128+
129+
## 3.2 DB Changes
130+
Describe changes to existing DBs or any new DB being added.
131+
132+
### 3.2.1 CONFIG DB
133+
#### 3.2.1.1 ACL_TABLE Table
134+
135+
A new ACL type called l2 is introduced to support MAC ACLs. The following shows the changes done to existing schema
136+
137+
```
138+
key = ACL_TABLE:name ; acl_table_name must be unique
139+
;field = value
140+
type = "l2" ; type of acl table, every type of
141+
; table defines the match/action a
142+
; specific set of match and actions.
143+
```
144+
145+
#### 3.2.1.2 ACL_RULE_TABLE Table for L2 ACL
146+
147+
The following is the schema changes for L2 ACL rules.
148+
149+
```
150+
key = ACL_RULE_TABLE:table_name:rule_name ; key of the rule entry in the table,
151+
; seq is the order of the rules
152+
; when the packet is filtered by the
153+
; ACL "policy_name".
154+
; A rule is always assocaited with a
155+
; policy.
156+
;field = value
157+
priority = 1*3DIGIT ; rule priority. Valid values range
158+
; could be platform dependent
159+
PACKET_ACTION = "forward"/"drop"/"redirect:"redirect_action
160+
; action when the fields are matched
161+
; In case of packet_action="redirect" a parameter is required
162+
; This parameter defines a destination for redirected packets
163+
; it could be:
164+
; name of physical port. Example: "Ethernet10"
165+
; name of LAG port Example: "PortChannel5"
166+
167+
redirect_action = 1*255CHAR ; redirect parameter
168+
; This parameter defines a destination for redirected packets
169+
; it could be:
170+
; name of physical port. Example: "Ethernet10"
171+
; name of LAG port Example: "PortChannel5"
172+
; next-hop ip address (in global) Example: "10.0.0.1"
173+
; next-hop ip address and vrf Example: "10.0.0.2@Vrf2"
174+
; next-hop ip address and ifname Example: "10.0.0.3@Ethernet1"
175+
; next-hop group set of next-hop Example: "10.0.0.1,10.0.0.3@Ethernet1"
176+
177+
SRC_MAC = mac_addr ["/" mac_mask ] ; Source MAC address
178+
DST_MAC = mac_addr ["/" mac_mask ] ; Destination MAC address
179+
ETHER_TYPE = h16 ; Ethernet type field
180+
PCP = pcp_val [ "/"" pcp_val] ; PCP Value in range of 0-7
181+
DEI = BIT ["/" BIT ] ; DEI Value. 0 or 1.
182+
VLAN = vlan_id ; VLAN ID. Supported range is 1-4094.
183+
; valid only if the ACL is applied to Port or
184+
; LAG or Switch. For VLAN binding this will be
185+
; ignored.
186+
187+
;value annotations
188+
mac_addr = 2HEXDIG "-" 2HEXDIG "-" 2HEXDIG "-" 2HEXDIG "-" 2HEXDIG "-" 2HEXDIG
189+
/ 2HEXDIG ":" 2HEXDIG ":" 2HEXDIG ":" 2HEXDIG ":" 2HEXDIG ":" 2HEXDIG
190+
vlan_id = %x31-39 ; 1-9
191+
/ %x31-39 DIGIT ; 10-99
192+
/ %x31-39 2DIGIT ; 100-999
193+
/ %x31-33 3DIGIT ; 1000-3999
194+
/ %x34 %x30 %x30-39 %x30-34 ; 4000 - 4094
195+
pcp_val = %x30-37
196+
```
197+
198+
#### 3.2.1.3 ACL_RULE_TABLE Table additional actions
199+
200+
The following new results will be added to the ACL_RULE_TABLE.
201+
202+
```
203+
key = ACL_RULE_TABLE:table_name:rule_name ; key of the rule entry in the table,
204+
; seq is the order of the rules
205+
; when the packet is filtered by the
206+
; ACL "policy_name".
207+
; A rule is always assocaited with a
208+
; policy.
209+
;field = value
210+
SET_DSCP = DIGIT / %x31-36 %x30-33 ; 0-9 or 10 - 63
211+
SET_PCP = %x30-37 ; 0-7
212+
SET_POLICER = 1*255VCHAR ; refer to the POLICER
213+
214+
;value annotations
215+
```
216+
217+
POLICER_TABLE schema is defined in https://github.com/Azure/sonic-swss/blob/master/doc/swss-schema.md will be reused for Configuration DB. The table name will be POLICER in Configuration DB.
218+
219+
### 3.2.2 APP DB
220+
No Change
221+
222+
### 3.2.3 STATE DB
223+
No Change
224+
225+
### 3.2.4 ASIC DB
226+
No Change
227+
228+
### 3.2.5 COUNTER DB
229+
The Policer counters will be stored in
230+
231+
```
232+
POLICER_COUNTERS: policer_name
233+
234+
GreenPackets : <packets_counter_value>
235+
GreenBytes : <bytes_counter_value>
236+
YellowPackets : <packets_counter_value>
237+
YellowBytes : <bytes_counter_value>
238+
RedPackets : <packets_counter_value>
239+
RedBytes : <bytes_counter_value>
240+
```
241+
242+
## 3.3 Switch State Service Design
243+
### 3.3.1 Orchestration Agent
244+
ACL and Policer Orch agents will be updated to support the new results.
245+
246+
#### 3.3.1.1 ACL Orchagent
247+
248+
A new class called AclRuleL2 will be added for L2 ACL Rule. The implementation of this class will be similar to that of AclRuleL3.
249+
250+
```
251+
class AclRuleL2: public AclRule
252+
{
253+
public:
254+
AclRuleL2(AclOrch *m_pAclOrch, string rule, string table, acl_table_type_t type, bool createCounter = true);
255+
256+
bool validateAddAction(string attr_name, string attr_value);
257+
bool validateAddMatch(string attr_name, string attr_value);
258+
bool validate();
259+
void update(SubjectType, void *);
260+
protected:
261+
sai_object_id_t getRedirectObjectId(const string& redirect_param);
262+
};
263+
```
264+
265+
To support policer as one of the actions, ACL orchagent has to interact with Policer orchagent to get the SAI object ID associated with the policer name. This will be done using the existing APIs exposed by the policer orchagent namely `policerExists`, `getPolicerOid`, `increaseRefCount`, `decreaseRefCount`.
266+
267+
#### 3.3.1.2 Policer Orchagent
268+
Policer orchagent will poll the policer counters every 10 seconds. This is not configurable as of now and will be populated in POLICER_COUNTER table.
269+
270+
### 3.3.2 Other Process
271+
NA
272+
273+
## 3.4 SyncD
274+
NA
275+
276+
## 3.5 SAI
277+
https://github.com/opencomputeproject/SAI/blob/master/inc/saiacl.h already has the necessary support. No enhancements are necessary. The following QoS Actions will be used
278+
- SAI_ACL_ENTRY_ATTR_ACTION_SET_OUTER_VLAN_PRI
279+
- SAI_ACL_ENTRY_ATTR_ACTION_SET_DSCP
280+
- SAI_ACL_ENTRY_ATTR_ACTION_SET_POLICER
281+
282+
## 3.6 User Interface
283+
NA
284+
285+
# 4 Flow Diagrams
286+
This enhancement doesn't add any additional flows for L2 ACL support. The flows for different scenarios of ACL Orchagent are at <https://github.com/Azure/SONiC/wiki/ACL-High-Level-Design>.
287+
288+
## 4.1 Creating ACL rules with policer
289+
![Adding Rule with policer](images/RuleAddPolicer.png "Adding Rule with policer")
290+
291+
**Figure 1: Adding Rule with policer**
292+
## 4.2 Deleting ACL rules with policer
293+
![Deleteing Rule with policer](images/RuleDelPolicer.png "Deleting Rule with policer")
294+
295+
**Figure 2: Deleting Rule with policer**
296+
# 5 Error Handling
297+
Errors will logged to syslogs.
298+
299+
# 6 Serviceability and Debug
300+
Existing commands like "show acl table", "show acl rule" and "aclshow" will show the details of the configuration like match criteria and actions. Syslogs will contain logs generated by ACL and Policer orchestration agent which can be used for debugging.
301+
302+
# 7 Warm Boot Support
303+
ACLs applied will be functional across warm reboots.
304+
305+
# 8 Scalability
306+
Scalability is silicon dependent.
307+
308+
# 9 Unit Test
309+
The following tests will be automated using Pytest.
310+
1. Add ACL and rules with policer and verify ASIC DB and Counters DB.
311+
2. Add ACL and rules with DSCP remarking and verify ASIC DB and Counters DB.
312+
3. Add ACL and rules with PCP remarking and verify ASIC DB and Counters DB.
313+
4. Delete ACL and rules with policer and verify ASIC DB and Counters DB cleanup.
314+
5. Delete ACL and rules with DSCP remarking and verify ASIC DB and Counters DB cleanup.
315+
6. Delete ACL and rules with PCP remarking and verify ASIC DB and Counters DB cleanup.
316+
317+
# 10 Internal Design Information
318+
NA
319+
320+

‎L24Services/Community/images/ACLOverview.png

34.5 KB
Loading

‎L24Services/Community/images/RuleAddPolicer.png

45.9 KB
Loading

‎L24Services/Community/images/RuleDelPolicer.png

28.6 KB
Loading

0 commit comments

Comments
 (0)