Skip to content

Commit e8c86d1

Browse files
rupesh-krupesh-k
committed
SONiC Port mirroring HLD
1 parent a124c68 commit e8c86d1

1 file changed

Lines changed: 319 additions & 0 deletions

File tree

‎doc/SONiC_Port_Mirroring_HLD.md‎

Lines changed: 319 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,319 @@
1+
# SONiC Port Mirroring HLD
2+
#### Rev 1.0
3+
4+
# Table of Contents
5+
* [List of Tables](#list-of-tables)
6+
* [Revision](#revision)
7+
* [About This Manual](#about-this-manual)
8+
* [Scope](#scope)
9+
* [Definition/Abbreviation](#definitionabbreviation)
10+
* [1. Requirements Overview](#1-requirement-overview)
11+
* [1.1 Functional Requirements](#11-functional-requirements)
12+
* [1.2 Configuration and Management Requirements](#12-configuration-and-management-requirements)
13+
* [1.3 Scalability Requirements](#13-scalability-requirements)
14+
* [1.4 Warm Boot Requirements](#14-warm-boot-requirements)
15+
* [2. Functionality](#2-functionality)
16+
* [2.1 Functional Description](#21-functional-description)
17+
* [3. Design](#3-design)
18+
* [3.1 Overview](#31-overview)
19+
* [3.2 DB Changes](#32-db-changes)
20+
* [3.2.1 CONFIG DB](#321-config-db)
21+
* [3.2.2 APP_DB](#322-app_db)
22+
* [3.2.3 STATE_DB](#323-state_db)
23+
* [3.2.4 ASIC_DB](#324-asic_db)
24+
* [3.2.5 COUNTER_DB](#325-counter_db)
25+
* [3.3 Switch State Service Design](#33-switch-state-service-design)
26+
* [3.3.1 Orchestration Agent](#331-orchestration-agent)
27+
* [3.3.2 Other Process](#332-other-process)
28+
* [3.4 SAI](#35-sai)
29+
* [3.5 CLI](#36-cli)
30+
* [3.5.1 Data Models](#351-data-models)
31+
* [3.5.2 Configuration Commands](#352-configuration-commands)
32+
* [3.5.3 Show Commands](#353-show-commands)
33+
* [3.5.4 Clear Commands](#354-clear-commands)
34+
* [3.5.5 Debug Commands](#355-debug-commands)
35+
* [3.5.6 Rest API Support](#356-rest-api-support)
36+
* [3.5.7 GNMI Support](#357-gnmi-support)
37+
* [4. Flow Diagrams](#4-flow-diagrams)
38+
* [5. Error Handling](#5-Error-Handling)
39+
* [6. Serviceability and Debug](#6-serviceability-and-debug)
40+
* [7. Warm Boot Support](#7-warm-boot-support)
41+
* [8. Scalability](#8-scalability)
42+
* [9. Unit Test](#9-unit-test)
43+
44+
# List of Tables
45+
[Table 1: Abbreviations](#table-1-abbreviations)
46+
47+
48+
# Revision
49+
| Rev | Date | Author | Change Description |
50+
|:---:|:-----------:|:------------------:|--------------------------------------------|
51+
| 0.1 | 05/17/2019 | Rupesh Kumar | Initial version |
52+
53+
54+
# About this Manual
55+
This document provides general information about extending mirroring implementation in SONiC.
56+
# Scope
57+
This document describes the high level design of Mirroring Enhancements feature.
58+
59+
60+
# Definition/Abbreviation
61+
### Table 1: Abbreviations
62+
| **Term** | **Meaning** |
63+
|--------------------------|-------------------------------------|
64+
| SPAN | Switched Port ANalyzer |
65+
| ERSPAN | Encapsulated Remote Switched Port ANalyzer |
66+
67+
68+
# 1 Requirement Overview
69+
## 1.1 Functional Requirements
70+
71+
1. Port/Port-channel mirroring support
72+
- Add support to mirror ingress traffic on port/port-channel to SPAN/ERPSAN mirror session.
73+
- Add support to mirror egress traffic on port/port-channel to SPAN/ERSPAN mirror session.
74+
- Add support to mirror both ingress/egress traffic on port/port-channel to SPAN/ERSPAN mirror session.
75+
76+
2. Dynamic session management
77+
- Allow multiple source to single destination.
78+
- Each session supports mirroring from single port to single destination port.
79+
- Session-id created in SAI per destination port will be used when the same destination port is configured in other session.
80+
This effectively utilizes the hardware resource to be shared across multiple sessions.
81+
- Mirror session on source portchannel will be active if at least one port is part of portchannel.
82+
- Mirror session on source portchannel will become inactive when portchannel has no members.
83+
- ERSPAN session will be active/inactive based on destination IP reachability.
84+
85+
3. ACL rules can continue to use port/ERSPAN sessions as the action.
86+
87+
4. Configuration CLI for mirror session
88+
- CLI allows all flavors of mirror sessions.
89+
- CLI validation for all mandatory parameters in ERSPAN configuration.
90+
- CLI validation for all mandatory parameters in port/portchannel mirroring.
91+
- CLI to allow mirror session configuration only with destination port.
92+
93+
94+
## 1.2 Configuration and Management Requirements
95+
- Existing CLI 'config mirror_session add/remove'to be extended to include source port/portchannel.
96+
- Existing CLI 'config mirror_session add/remove' to be extended to include destination port/portchannel.
97+
- Existing CLI 'show mirror session' is extended to support all flavors of mirror sessions.
98+
99+
100+
## 1.3 Scalability Requirements
101+
- Up to max ASIC capable mirror sessions to be supported.
102+
- Once max mirror sessions are created and user attempts to create new session, error will be logged in syslog.
103+
104+
105+
## 1.4 Warm Boot Requirements
106+
- Mirroring functionality should continue to work across warm reboot.
107+
108+
To support planned system warm boot.
109+
To support SWSS docker warm boot.
110+
111+
112+
# 2 Functionality
113+
114+
Refer section 1
115+
116+
## 2.2 Functional Description
117+
Refer section 1.1
118+
119+
## 2.3 Functional Description
120+
121+
Mirroring to destination VLAN (RSPAN) is not supported in this release.
122+
123+
# 3 Design
124+
## 3.1 Overview
125+
126+
127+
## 3.2 DB Changes
128+
### 3.2.1 CONFIG DB
129+
130+
Existing table PORT_MIRROR_TABLE is enhanced to accept new source and destination configuration options in the configuration database. This table is filled by the management framework.
131+
132+
#### CONFIG_PORT_MIRROR_TABLE
133+
134+
;Configure SPAN/ERSPAN mirror session.
135+
;storm control type - broadcast / unknown-unicast / unknown-multicast
136+
key = PORT_MIRROR_TABLE:mirror_session_name ; mirror_session_name is
137+
; unique session
138+
; identifier
139+
;field = value
140+
destination_port = PORT_TABLE:ifname ; ifname must be unique across PORT TABLE.
141+
source_port = PORT_TABLE:ifname ; ifname must be unique across PORT,INTF,LAG TABLES
142+
direction = ingress or egress or both ; Direction ingress or egress or both.
143+
144+
mirror_session_name = 1*255VCHAR
145+
146+
### 3.2.2 APP_DB
147+
No tables are introduced in APP_DB
148+
### 3.2.3 STATE_DB
149+
No tables are introduced in STATE_DB.·
150+
151+
### 3.2.4 ASIC_DB
152+
No changes are introduced in ASIC_DB.·
153+
### 3.2.5 COUNTER_DB
154+
No changes are introduced in COUNTER_DB.·
155+
156+
## 3.3 Switch State Service Design
157+
### 3.3.1 Orchestration Agent
158+
159+
Mirror Orchestration agent is modified to support this feature:
160+
- Handle both SPAN and ERSPAN sessions separately·
161+
- No changes to ERSPAN functionality.
162+
- Configure mirror session based on CONFIG_DB parameters.
163+
- Port mirror session is activated
164+
- Populates the mirror attribute SAI structures and pushes the entry to ASIC_DB.·
165+
166+
## 3.4 SAI
167+
Mirror SAI interface APIs are already defined. More details about SAI API and attributes are described below SAI Spec @
168+
169+
https://github.com/opencomputeproject/SAI/blob/master/inc/saimirror.h
170+
171+
## 3.5 CLI
172+
### 3.5.1 Data Models
173+
Custom Yang model will be introduced for this feature.
174+
175+
### 3.5.2 Configuration Commands
176+
177+
Existing mirror session commands are enhanced to support this feature.
178+
179+
# Modify existing ERSPAN configuration as below.
180+
config mirror_session add erspan <session-name> <src_ip> <dst_ip> <gre> <dscp> [ttl] [queue]
181+
182+
#Configure Destination only span mirror session.
183+
config mirror_session add span <session-name> <destination_ifName>
184+
185+
# Modify existing ERSPAN configuration to accept source port and direction
186+
config mirror_session add erspan <session-name> <src_ip> <dst_ip> <gre> <dscp> [ttl] [queue] [src_port] [rx/tx/both]
187+
188+
#Configure Port mirror span mirror session.
189+
config mirror_session add span <session-name> <destination_ifName> <source_ifName> <rx/tx/both>
190+
191+
192+
KLISH CLI Support.
193+
194+
# SPAN config
195+
# **switch(config)# [no] mirror-session <session-name>** <br>
196+
**switch(config-mirror-<session-name>)# [no] destination <dest_ifName> [source <src_ifName> direction <rx/tx/both>]** <br>
197+
dest_ifName can be port only
198+
src_ifName can be port/port-channel>
199+
200+
# ERSPAN config
201+
**switch(config)# [no] mirror-session <session-name>** <br>
202+
**switch(config-mirror-<session-name>)# [no] destination erspan src_ip <src_ip> dst_ip <dst_ip> dscp < dscp > ttl < ttl > [ gre < gre >] [queue <queue>] [source <src_ifName> direction <rx/tx>**] <br>
203+
204+
### 3.5.3 Show Commands
205+
206+
The following show command display all the mirror sessions that are configured.
207+
208+
# show mirror-session
209+
ERSPAN Sessions
210+
---------------------------------------------------------------------------------------------------------
211+
Name Status SRC IP DST IP GRE DSCP TTL Queue Policer SRC Port Direction
212+
everflow0 active 10.1.0.32 10.0.0.7 10 10 10
213+
everflow1 active 10.1.0.33 10.0.0.8 10 10 10 Ethernet4 both
214+
215+
SPAN Sessions
216+
---------------------------------------------------------------------------------------------------------
217+
Name Status DST Port SRC Port Direction
218+
sess1 active Ethernet4 Ethernet0 rx
219+
220+
KLISH show mirror-session is same as above.
221+
222+
### 3.5.4 Clear Commands
223+
No command variants of config commands take care of clear config.
224+
225+
### 3.5.5 Debug Commands
226+
Not applicable
227+
228+
### 3.5.6 REST API Support
229+
230+
- Please check all REST API from link @ https://<switch_ip>/ui link.
231+
- This webserver provides user information about all the REST URLS, REST Data. Return codes.
232+
- This webserver also provides interactive support to try REST queries.
233+
234+
- Following REST SET and GET APIs will be supported
235+
236+
The following show command display all the mirror sessions that are configured.
237+
238+
# Get all mirror sessions
239+
# curl -X GET "https://<switch_ip>/restconf/data/sonic-mirror-session:sonic-mirror-session" -H "accept: application/yang-data+json"
240+
241+
# Create SPAN session
242+
# curl -X POST "https://<switch_ip>/restconf/data/sonic-mirror-session:sonic-mirror-session" -H "accept: application/yang-data+json" -H "Content-Type: application/yang-data+json" -d "{ \"sonic-mirror-session:MIRROR_SESSION\": { \"MIRROR_SESSION_LIST\": [ { \"name\": \"sess1\", \"dst_port\": \"Ethernet10\", \"src_port\": \"Ethernet8\", \"direction\": \"rx\" } ] }}"
243+
244+
# Delete all mirror sessions
245+
# curl -X DELETE "https://<switch_ip>/restconf/data/sonic-mirror-session:sonic-mirror-session" -H "accept: application/yang-data+json"
246+
247+
# Delete specific mirror session
248+
# curl -X DELETE "https://<switch_ip>/restconf/data/sonic-mirror-session:sonic-mirror-session/MIRROR_SESSION/MIRROR_SESSION_LIST=mirr3" -H "accept: application/yang-data+json"
249+
250+
### 3.5.7 GNMI Support
251+
252+
253+
- Following GNMI set and get commands will be supported
254+
255+
# Get all mirror sessions
256+
# gnmi_get -xpath /sonic-mirror-session:sonic-mirror-session -target_addr 127.0.0.1:8080 -insecure
257+
258+
# Create SPAN session. mirror.json includes json payload same as rest-api above.
259+
# gnmi_set -update /sonic-mirror-session:sonic-mirror-session/:@./mirror.json -target_addr 127.0.0.1:8080 -insecure
260+
261+
# Delete all mirror sessions
262+
# gnmi_set -delete /sonic-mirror-session:sonic-mirror-session -target_addr 127.0.0.1:8080 -insecure
263+
264+
# Delete specific mirror session
265+
# gnmi_set -delete /sonic-mirror-session:sonic-mirror-session/MIRROR_SESSION/MIRROR_SESSION_LIST[name=Mirror1] -target_addr 127.0.0.1:8080 -insecure
266+
267+
# 4 Flow Diagrams
268+
269+
# 5 Error Handling
270+
271+
- show mirror session command will display any errors during session configuration and current status of session.
272+
- Internal processing errors within SwSS will be logged in syslog with ERROR level
273+
- SAI interaction errors will be logged in syslog
274+
275+
# 6 Serviceability and Debug
276+
277+
# 7 Warm Boot Support
278+
The mirroring configurations be retained across warmboot so that source traffic gets mirrored properly to destination port.
279+
280+
# 8 Scalability
281+
282+
Max mirror sessions supported are silicon specific. Testing would be done by creating max mirror sessions on the switch.·
283+
###### Table 3: Scaling limits
284+
|Name | Scaling value |
285+
|--------------------------|--------------------|
286+
| Max mirror sessions | silicon specific |
287+
288+
# 9 Unit Test
289+
290+
## 9.1 CLI Test Cases
291+
292+
1. Configure ERSPAN mirror session and verify all parameters are updated properly in CONFIG_DB
293+
2. Configure SPAN mirror session and verify all parameters are updated properly in CONFIG_DB.
294+
3. Unconfigure ERSPAN/SPAN mirror sessions and check that it is updated in CONFIG_DB.
295+
4. Execute the show mirror session command to check the mirroring configuration.·
296+
5. Verify that the mirror configurations are correctly re-applied after cold reboot.
297+
6. Verify mirror session goes to in-active state when source port-channel has no members.
298+
7. Verify mirror session goes to active state when source port-channel has atleast one active member.
299+
300+
## 9.2 Rest API Test Cases
301+
8. Verify SPAN/ERSPAN mirroring can be configured via REST.
302+
9. Verify SPAN/ERSPAN mirroring can be un-configured via REST.
303+
304+
## 9.3 Functional Test Cases
305+
10. Verify that traffic on source port gets mirrored to destination port.
306+
11. Verify that traffic on source port-channel gets mirrored to destination port.
307+
12. Verify that traffic on source port/port-channel gets mirrored properly with proper Erspan session.
308+
13. Verify all existing test-cases of ERSPAN works properly.
309+
310+
## 9.4 Scaling Test Cases
311+
14. Configure max mirror sessions and verify that all are working properly.
312+
313+
## 9.5 Warm Boot Test Cases
314+
15. Verify that mirroring configurations are restored after warm boot.·
315+
16. Verify that mirroring continues to work across warm boot.
316+
317+
## 9.6 Negative Test Cases
318+
17. Verify that mirror configuration throws error with invalid interface or direction.
319+
18. Verify that mirror configuration throws error with already configured session.

0 commit comments

Comments
 (0)