Skip to content

Commit 767a9a0

Browse files
author
shaygol
committed
Internal Review Updates
1 parent 1a0f703 commit 767a9a0

File tree

2 files changed

+78
-72
lines changed

2 files changed

+78
-72
lines changed

‎doc/acl/custom_acl_based_metering/Config_Flow.jpg

-40.3 KB
Loading

‎doc/acl/custom_acl_based_metering/Custom-ACL-Based-Metering.md

+78-72
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
# Custom ACL Based Metering
22

3-
### Table Of Content
3+
### Table Of Contents
44
- [Custom ACL Based Metering](#custom-acl-based-metering)
5-
- [Table Of Content](#table-of-content)
5+
- [Table Of Contents](#table-of-contents)
66
- [Revision](#revision)
77
- [Scope](#scope)
88
- [Definitions/Abbreviations](#definitionsabbreviations)
@@ -13,13 +13,13 @@
1313
- [CLI Requirements](#cli-requirements)
1414
- [Architecture Design](#architecture-design)
1515
- [High-Level Design](#high-level-design)
16-
- [Modules and Sub-Modules](#modules-and-sub-modules)
17-
- [*Image 1: Configuration Flow Overview*](#image-1-configuration-flow-overview)
16+
- [Custom ACL Mechanism](#custom-acl-mechanism)
17+
- [**Configuration Flow**](#configuration-flow)
1818
- [Configuration and Management](#configuration-and-management)
1919
- [Config DB Enhancements](#config-db-enhancements)
20-
- [ACL table](#acl-table)
21-
- [Custom ACL Table Type --\> no change](#custom-acl-table-type----no-change)
22-
- [ACL rule](#acl-rule)
20+
- [ACL Tables Table --\> No Change](#acl-tables-table----no-change)
21+
- [ACL Table Type Table](#acl-table-type-table)
22+
- [ACL Rules Table](#acl-rules-table)
2323
- [YANG Model Enhancements](#yang-model-enhancements)
2424
- [CLI Config Commands](#cli-config-commands)
2525
- [CLI Show Commands](#cli-show-commands)
@@ -30,6 +30,7 @@
3030
- [Unit Test Cases](#unit-test-cases)
3131
- [System Test Cases](#system-test-cases)
3232
- [CLI Level Tests](#cli-level-tests)
33+
- [Negative Test Cases](#negative-test-cases)
3334
- [DB validation](#db-validation)
3435
- [Open/Action Items](#openaction-items)
3536
- [Related HLDs](#related-hlds)
@@ -60,27 +61,32 @@ This document describes the Custom ACL Based Metering (CABM) feature design in S
6061
---
6162
### Overview
6263

63-
Policers in networking are responsible for **metering** (Monitoring the rate of traffic) and **marking** (Flagging traffic that exceeds defined limits) traffic based on predefined criteria.
64-
By applying policers to ACL rules, SONiC can effectively control the flow of network traffic, ensuring fairness, optimizing bandwidth utilization, and preventing network congestion.
64+
The Custom ACL-Based Metering (CABM) feature extends SONiC's capabilities to provide granular traffic management by integrating policers with ACL rules.
65+
Policers are essential tools for **metering** (Monitoring the rate of traffic) and **marking** (Flagging traffic that exceeds defined limits) traffic based on predefined criteria.
66+
67+
By leveraging flexible ACL tables with customized match fields and action sets, CABM allows customers to implement smart traffic policies dedicated to their needs.
68+
This flexibility ensures scalability and adaptability in diverse network environments.
6569

6670
Usage examples:
67-
- **Security**: Custom ACL Based Metering can be used to guard against **network storms or DDoS attacks** by limiting traffic rates.
68-
- **Fair Bandwidth Distribution**: Ensures bandwidth is allocated effectively across applications and services.
71+
- **Security**: Custom ACL Based Metering can be used to guard against **DoS attacks (such as TCP SYN attacks)**.
72+
This can be done by defining rules that detect specific traffic patterns (e.g., TCP SYN packets) and applies rate-limiting policers to minimize their impact.
73+
- **Efficient Bandwidth Distribution**: Ensures bandwidth is allocated effectively across applications and services by rate-limiting specific traffic types (e.g., backup traffic sent with SCP or FTP), ensuring priority traffic can operate without interruption.
6974

7075
---
7176
### Requirements
7277
#### Functional Requirements
73-
- Backward compatibility for existing ACL features - If policer is not set, the system will function as it did previously.
74-
- Ability to config policers with ACL entries.
75-
- Support existing Policer types (Policer mode, meter_type).
76-
- Support custom ACL type mechanism with policers.
78+
- Backward compatibility for existing ACL features.
79+
- Ability to bind policers to ACL entries.
80+
- Extend [ACL User Defined Table Type](https://github.com/sonic-net/SONiC/blob/master/doc/acl/ACL-Table-Type-HLD.md) (custom ACL type) mechanism with policers.
81+
- Ability to have customer specific table that contains a list of actions and match fields.
82+
- Gracefully handle unsupported or invalid configurations (e.g., rules referencing non-existent policers).
7783
### Scalability Requirements:
78-
- Support multiple rules within ACL to be bound to one policer.
84+
- Support binding of multiple ACL rules to a single policer.
7985
- Query and validate SAI capabilities.
8086
#### CLI Requirements
81-
- Bind policers with ACL rules.
82-
- Unbind policer from ACL rules.
83-
- Show ACLs with policers
87+
- Extend ACL table command to support policer.
88+
- Extend ACl rules command to bind and unbind rule to policers.
89+
- Support show ACL rules command with policers.
8490
---
8591
### Architecture Design
8692

@@ -89,50 +95,50 @@ No SONiC architecture changes are required as the existing infrastructure is bei
8995
---
9096
### High-Level Design
9197

92-
#### Modules and Sub-Modules
98+
#### Custom ACL Mechanism
99+
SONiC currently supports [ACL User Defined Table Types](https://github.com/sonic-net/SONiC/blob/master/doc/acl/ACL-Table-Type-HLD.md) that enables customers to define flexible ACL tables tailored to specific operational needs.
100+
This mechanism extends SONiC’s ACL framework by allowing users to specify their own match fields and actions supporting a wide range of traffic management policies.
93101

94-
- **SWSS**
95-
- ACL-Orch
96-
- Set or disable policer action.
97-
- Query from SAI the ACL actions capability.
98-
- Allow policer action only when the capability is enabled.
99-
- Parse policer action fields.
100-
- Policer-Orch
101-
- Validate policer info.
102-
- Map policer name to policer object ID.
103-
- Prevent from deleting policer that bound to ACLs.
102+
Custom ACL Based Metering (CABM) builds directly upon this custom ACL mechanism by introducing support for policer actions within custom ACL table types, allowing customers to enforce advanced traffic management policies.
104103

105-
##### *Image 1: Configuration Flow Overview*
104+
#### **Configuration Flow**
106105

107106
![alt text](Config_Flow.jpg)
108107

109108

109+
1. Query Capabilities on Initialization: ACL-Orch queries SAI to retrieve supported ACL actions, including SAI_ACL_ACTION_TYPE_SET_POLICER.
110+
2. Create Policer Object: Policer configurations are defined in POLICER_TABLE, validated, and created in SAI.
111+
3. Define Custom ACL Table Type: Users define custom ACL table types in ACL_TABLE_TYPE with specified matches and actions, including POLICER_ACTION.
112+
4. Verify Table Capabilities: ACL-Orch ensures that the custom table type's action set, including POLICER_ACTION, is supported by the queried SAI capabilities.
113+
5. Create ACL Table: Add an ACL table in ACL_TABLE, referencing the custom table type and validates the configuration.
114+
6. Create ACL Rule: Add an ACL rule in ACL_RULE, referencing actions, including policer_action.
115+
7. Verify Rule Compatibility: ACL-Orch validates that the rule action compatibility with the associated ACL table type.
116+
8. Verify and Map Policer to SAI Object: Policer-Orch maps the policer_action name if it exists from CONFIG_DB to SAI object IDs.
117+
9. Program ACL Rule in SAI: ACL-Orch programs ACL rule entries into SAI associating them with the policer object.
118+
110119
---
111120

112121
### Configuration and Management
113122
#### Config DB Enhancements
114123

115-
##### ACL table
116-
- When a new ACL is created, SAI API should get a packet-action list of supported actions that could be used in the rules belonging to this table.
117-
- An existing mechanism allows defining **custom ACL table types** and specifying the desired combination of actions and match fields (ACL User Defined Table Type HLD).
118-
- To support the new policer action, the custom table type will be extended with the policer action attribute - SAI_ACL_ACTION_TYPE_SET_POLICER.
124+
##### ACL Tables Table --> No Change
125+
126+
##### ACL Table Type Table
127+
When a new ACL table is created, SAI needs to receive a list of supported actions which the rules belonging to this table are allowed to use.
128+
To support the new policer action, the custom table types table schema will be extended with a policer action attribute - **"POLICER_ACTION"** for the actions attribute field.
119129

120-
###### Custom ACL Table Type --> no change
121130
```
122131
key: ACL_TABLE_TYPE|<TYPE_NAME> ; key of the ACL table type entry.
123132
; the name is arbitary name user chooses.
124-
; field = value
133+
;field = value
125134
matches = match-list ; list of matches for this table.
126135
; matches are same as in ACL_RULE table.
127136
actions = action-list ; list of actions for this table.
128-
; actions are same as in ACL_RULE table.
129-
bind_points = bind-points-list ; list of bind point types for this table.
137+
; ["REDIRECT_ACTION", ... , "POLICER_ACTION"]
130138
```
131139

132-
##### ACL rule
133-
- The CONFIG_DB ACL rules table schema will be updated with a new attribute **"policer_action"** with the value of one of the existing policer object names.
134-
- This proposed schema is flexible and can support rules with more than a single action.
135-
- The existing design of SONiC ACL allows only one action to be defined per rule, this consept will be kept.
140+
##### ACL Rules Table
141+
The CONFIG_DB ACL Rules Table schema will be updated with a new attribute field **"policer_action"** with the value of one of the existing policer object names.
136142

137143
```
138144
key: ACL_RULE|<TABLE_NAME>|<RULE_NAME> ; key of the rule entry in the table,
@@ -146,14 +152,7 @@ priority = 1*3DIGIT ; rule priority. Valid values rang
146152
147153
packet_action = "FORWARD"/"DROP"/"DO_NOT_NAT" ; action when the fields are matched
148154
149-
redirect_action = 1*255CHAR ; redirect parameter
150-
; This parameter defines a destination for redirected packets
151-
; it could be:
152-
: name of physical port. Example: "Ethernet10"
153-
: name of LAG port Example: "PortChannel5"
154-
: next-hop ip address (in global) Example: "10.0.0.1"
155-
: next-hop ip address and vrf Example: "10.0.0.2@Vrf2"
156-
: next-hop ip address and ifname Example: "10.0.0.3@Ethernet1"
155+
mirror_ingress_action = 1*255VCHAR ; refer to the mirror session
157156
...
158157
+ policer_action = 1*255VCHAR ; refer to the policer object name
159158
```
@@ -170,6 +169,12 @@ sonic-yang-models/yang-templates/**sonic-acl**.yang.j2:
170169
container sonic-acl {
171170
container ACL_RULE {
172171
...
172+
leaf MIRROR_INGRESS_ACTION {
173+
type leafref {
174+
path "/sms:sonic-mirror-session/sms:MIRROR_SESSION/sms:MIRROR_SESSION_LIST/sms:name";
175+
}
176+
}
177+
173178
+ leaf POLICER_ACTION {
174179
+ type leafref {
175180
+ path "/policer:sonic-policer/policer:POLICER/policer:POLICER_LIST/policer:name";
@@ -246,8 +251,10 @@ Two options to bind policer with ACL rules:
246251
"SRC_IP",
247252
],
248253
"ACTIONS": [
249-
"POLICER_ACTION"
254+
"REDIRECT_ACTION",
255+
+ "POLICER_ACTION"
250256
],
257+
}
251258
}
252259

253260
/* create ACL policer type table */
@@ -277,7 +284,7 @@ Two options to bind policer with ACL rules:
277284
"priority": "80",
278285
+ "policer_action": "M_POLICER_93",
279286
"IP_PROTOCOL": "TCP",
280-
"SRC_IP": "192.168.1/24",
287+
"SRC_IP": "192.168.0/24",
281288
"DST_IP": "10.5.170.0/24",
282289
"L4_SRC_PORT_RANGE": "1024-65535",
283290
"L4_DST_PORT_RANGE": "80-89",
@@ -301,7 +308,7 @@ Two options to bind policer with ACL rules:
301308

302309
# Example:
303310
config acl add table "MY_ACL_1" "Custom_1_POLICER"
304-
config acl update full "MY_ACL_2" --policer_name "M_POLICER_7" rules_example.json
311+
config acl update incremental "MY_ACL_1" --policer_name "M_POLICER_7" rules_example.json
305312

306313
# note that these commands wrapps "AclLoader" utility script that uses the external "open_config" lib
307314
```
@@ -321,26 +328,16 @@ show acl rule [OPTIONS] [TABLE_NAME] [RULE_ID]
321328

322329

323330
# Example:
324-
admin@sonic:~$ show acl table
325-
Name Type Binding Description Stage Status
326-
----------- --------------- --------- -------------------------- ------- -----------------
327-
MY_ACL_1 CUSTOM_1_POLICER Ethernet2 Limit some traffic flows Ingress ACTIVE
328-
Ethernet4
329-
Ethernet7
330-
331-
MY_ACL_2 CUSTOM_3 Ethernet8 Limit AND redirect traffic Ingress ACTIVE
332-
333-
334331
admin@sonic:~$ show acl rule
335332
Table Rule Priority Actions Match
336333
-------- ------------ ---------- ------------------------- ----------------------------
337-
MY_ACL_1 MY_RULE_1 70 POLICER: M_POLICER_7 IP_PROTOCOL: 17
338-
334+
MY_ACL_1 MY_RULE_1 60 POLICER: M_POLICER_7 IP_PROTOCOL: 17
339335

340-
MY_ACL_2 MY_RULE_2 80 POLICER: M_POLICER_93 L4_SRC_PORT: 80
336+
MY_ACL_1 MY_RULE_2 70 POLICER: M_POLICER_93 L4_SRC_PORT: 80
341337

338+
MY_ACL_1 MY_RULE_3 80 POLICER: M_POLICER_93 L4_SRC_PORT: 443
342339

343-
MY_ACL_2 MY_RULE_3 90 REDIRECT: Ethernet8 L4_SRC_PORT: 25
340+
MY_ACL_1 MY_RULE_4 90 REDIRECT: Ethernet8 L4_SRC_PORT: 20
344341
```
345342

346343
---
@@ -376,18 +373,27 @@ During warmboot or fastboot, both ACL rules and policers configurations are rest
376373
---
377374
### Testing Requirements/Design
378375
#### Unit Test Cases
376+
- Create custom acl table type with policer attribute.
377+
- Create acl table of the custom type and add acl rule with policer action.
378+
- Delete acl rule with valid policer action.
379+
- Create acl rule with valid policer and try to delete the policer.
380+
- Create acl rule with action as non-existent policer.
379381
- Test ACL-Orch and Policer-Orch logic for correct processing.
380382
#### System Test Cases
381383
- Ensure correct packet marking based on policer configurations.
382384
- Test different traffic patterns and rates to ensure consistent marking.
383385
- Warm/Fast reboot tests
384-
- verify that policer configurations are preserved across reboots
385-
- verify that ACL configurations are preserved across reboots
386+
- verify that policer configurations are preserved across reboots.
387+
- verify that ACL configurations are preserved across reboots.
386388
#### CLI Level Tests
387-
- Verify command run successfully with valid parameter enable/disable.
389+
- Verify command run successfully with valid policer parameter.
388390
- Verify command abort with invalid policer parameter.
389-
- Verify command output.
391+
- Verify show acl rule command display the policer parameter.
390392
- Verify binding and unbinding policers with ACL rules.
393+
##### Negative Test Cases
394+
- Configure a rule with an action not listed in the custom ACL table type's action set, verify that the configuration is rejected with an appropriate error message.
395+
- Configure a rule with a non-existent policer name, verify that the configuration is rejected with an appropriate error message.
396+
- Attempt to delete a policer referenced by active ACL rules, verify that the deletion is blocked with an appropriate error message.
391397
#### DB validation
392398
- Verify CONFIG DB is correctly updated.
393399
---

0 commit comments

Comments
 (0)