Skip to content

Commit b8e0495

Browse files
dr412113dr412113
authored
Merge pull request sonic-net#175 from dr412113/L2-Traceroute
L2 traceroute HLD
2 parents 973f634 + 97f4f65 commit b8e0495

File tree

4 files changed

+284
-0
lines changed

4 files changed

+284
-0
lines changed

‎.DS_Store

6 KB
Binary file not shown.

‎L2/.DS_Store

6 KB
Binary file not shown.

‎L2/L2_Traceroute/L2_Trace_PDU.png

389 KB
Loading

‎L2/L2_Traceroute/L2_Traceroute.md

+284
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,284 @@
1+
# Feature Name
2+
3+
L2 Traceroute
4+
5+
# High Level Design Document
6+
7+
#### Rev 1.1
8+
9+
# Table of Contents
10+
11+
# List of Tables
12+
13+
[Table 1: Abbreviations](#table-1-abbreviations)
14+
15+
# Revision
16+
| Rev | Date | Author | Change Description |
17+
|:--:|:--------:|:-----------------:|:------------------------------------------------------------:|
18+
| 0.1 | 05/03/2021 | Dhanasekar Rathinavel | Initial version |
19+
| | | | |
20+
21+
# Definition/Abbreviation
22+
23+
### Table 1: Abbreviations
24+
25+
| **Term** | **Meaning** |
26+
| -------- | ------------------------------ |
27+
| LAN | Local Area Network |
28+
| MAC | Media Access Control addresses |
29+
| VLAN | Virtual Local Area Network |
30+
| | |
31+
32+
# About this Manual
33+
34+
This document provides general overview of L2 Traceroute feature(Trace-L2).
35+
36+
37+
38+
# 1 Introduction and Scope
39+
40+
Trace-L2 can trace all the L2 traffic paths for a given VLAN or to a particular destination device in the given VLAN. The destination device is identified based on its unicast-IP, DNS name or unicast-MAC. The main use of the Trace-L2 feature is to provide flexibility to administrators to determine the L2 paths in a L2 topology.
41+
Trace-L2 is a proprietary feature and it cannot interop with any other vendors. FYI, cisco has its own proprietary L2-traceroute.
42+
43+
# 2 Requirements Overview
44+
45+
## 2.1 Functional Requirements
46+
47+
Trace-L2 feature supports the following:
48+
49+
- Traces all the available paths to a particular IP, MAC or hostname in a VLAN.
50+
- Probes the entire Layer 2 topology.
51+
- Displays the input or output ports of each hop in the path.
52+
- Displays the round trip travel time of each hop.
53+
- Displays hops in a VLAN that form a loop.
54+
55+
The resulting trace displays a report that provides information about a packet’s path to a device, such as hop and port information and travel time. It also can locate any Layer 2 loop in a VLAN. The probed Layer 2 information is discarded when a new command is issued again.
56+
57+
For each hop in the path, trace-l2 displays its input/output port, L2 protocols of the input port, and the microsecond travel time between hop and hop. It also prints out the hops which form a loop, if any. Displaying L2 topology lets a user easily obtain information of all hops.
58+
59+
The devices that will participate in the trace-l2 protocol must be assigned to a VLAN. Devices that do not support the trace-l2 protocol will forward the trace-l2 packets without a reply. Hence, these devices are transparent to the trace-l2 protocol. The destination for the packet with the trace-l2 protocol must be a device that supports the trace-l2 protocol and the destination cannot be a client, such as a personal computer, or devices from other vendors. Trace-l2 will follow the xSTP path if enabled in the system.
60+
61+
62+
## 2.2 Configuration and Management Requirements
63+
- Trace-l2 first tries to use the IP address of the virtual routing interface that is associated with a VLAN. If the virtual routing interface is not available, it then uses the loopback address. If both addresses are not available, it displays MAC address only.
64+
- One way time is not available because the trace-l2 protocol does not synchronize the clocks between hops.
65+
66+
67+
## 2.3 Scalability Requirements
68+
The trace-l2 command cannot reach any device beyond ~60 hops. The maximum hop number is ~60 which is the number of hub informations that can be stored in a 1500 bytes Ethernet packet.
69+
70+
71+
## 2.4 Warm Boot Requirements
72+
73+
This is a utility command. Warmboot will not be supported.
74+
75+
## 2.5 Use case
76+
77+
The main use of the Trace-L2 feature is to provide flexibility to the administrators to determine the L2 paths in a L2 topology. The protocol provides a high level overview of the L2 topology.
78+
79+
# 3 Design
80+
81+
## 3.1 Overview
82+
83+
L2Trace container will have L2TraceMgr and L2Traced processes.
84+
85+
L2Trace process will register with the APP DB for receiving all the L2Trace configurations. L2TraceMgr will notify this configuration information to L2Traced for starting the session.
86+
87+
L2Traced process will handle following interactions. L2Traced will use libevent for processing the incoming events and timers.
88+
89+
1) Packet processing
90+
91+
- Socket of PF_PACKET type will be created for packet tx/rx
92+
- Filters will be attached to the socket to receive the L2Trace PDUs based on DA MAC (03:04:80:00:00:00)
93+
94+
2) Configuration - L2Trace CLI commands will be received from L2TraceMgr via a unix domain socket.
95+
3) Timers handling - Timer events are generated every 1sec for handling L2Trace protocol timers.
96+
4) Port events - Netlink socket interface for processing create/delete of port, link state changes of port.
97+
5) Operational updates - *L2Tracesync* is part of *L2Traced* and handles all the updates to APP DB. All DB interactions are detailed in the Section 3.2.
98+
99+
### 3.1.1 L2-Trace PDU processing
100+
101+
![L2Trace](L2_Trace_PDU.png "Figure 1: PDU Format")
102+
103+
MRP(Media Ring Protection) protocol was a BROCADE proprietary protocol. The trace-l2 BPDU is a MRP RHP (ring health packet) which has the following format.
104+
105+
```
106+
destination MAC (6 bytes: 0304.8000.0000)
107+
source MAC (6 bytes)
108+
length (2 bytes)
109+
LLC header (3 bytes: 0x33 0x33 0x03)
110+
protocol_id (2 bytes) // set to 2, which indicates trace-l2 Packet
111+
protocol_version (1 byte, should be 1)
112+
Type // query/reply
113+
```
114+
115+
These fields are followed by MRP packet format. The MRP protocol id field is increased from 1 to 2.
116+
117+
We are holding the IP-rights to BROCADE MAC address so we can continue to use BROCADE Multicast MAC.
118+
119+
When a trace-l2 command is issued,
120+
121+
- the device constructs a RHP packet with protocol id of 2 and trace type of “query”. The payload includes the destination IP address or a destination unicast MAC address. The packet is flooded on the vlan.
122+
123+
When a trace-l2 packet is received,
124+
125+
- If the payload destination addresses matches the device address, it appends its information to the payload, changes the trace type to “reply” and sends it back to through the input port. The reply packet is unicasted to the source, it uses the same packet format with trace type='reply'. The destination IP address must match the address of the VE associated with the queried vlan or any loopback address.
126+
- If the destination address in the payload does not match, the device appends its information to the payload as a HOP entry and floods the BPDU to the entire vlan except the input port.
127+
- If the destination device finds itself already in the list of HOPs traveresed by the packet , a LOOP is identified and reported.
128+
- During L2 forwarding query or reply, the source MAC address is always updated to avoid potential trouble such as station movement.
129+
130+
Only 1 active session can exist per VLAN+destination. A syslog error will be thrown if an active trace-l2 session is already in progress for the same VLAN+destination. When a reply comes back, the device prints the trace and cancels the associated timer. If there is no reply before the one-second timer gets expired, the one-second timer will print out failure and frees the data structure. If the reply is received after the timer expiry, it will be silently dropped. The assumption here is that one second of the waiting time is adequate in a L2 environment.
131+
132+
## 3.2 DB Changes
133+
134+
This section describes the changes made to different DBs for supporting the L2 Traceroute protocol.
135+
136+
### 3.2.1 APP DB
137+
138+
Following APP DB schemas are defined / modified for supporting this feature:
139+
140+
### TRACE_L2_SESSION_TABLE
141+
142+
;Stores Trace L2 session details
143+
;Status: work in progress
144+
key = TRACE_L2_SESSION:"Vlan"vlanid:MAC:IP
145+
session_id = 4*DIGIT ; max 4096 sessions
146+
path_count = 2*DIGIT ;
147+
148+
149+
### TRACE_L2_PATH_INFO_TABLE
150+
151+
;Stores Trace L2 paths per session
152+
;Status: work in progress
153+
key = TRACE_L2_PATHS:session_id:path_no
154+
hop_count = 2*DIGIT ;
155+
156+
157+
### TRACE_L2_HOP_INFO_TABLE
158+
159+
;Stores Trace L2 hop information per session details
160+
;Status: work in progress
161+
key = TRACE_L2_HOP_INFO:session_id:path_no:hop_entry
162+
device_name = STRING ; device name
163+
ip = STRING ; ip address of the VE or Loopback ip of device
164+
mac = STRING ; mac address of the device
165+
in_port = STRING ; input port name
166+
out_port = STRING ; "FLOOD" or a port name
167+
is_loop = true/false ;
168+
169+
170+
171+
172+
## 3.3 Switch State Service Design
173+
174+
### 3.3.1 Orchestration Agent
175+
176+
No changes
177+
178+
### 3.3.2 BPDU trap mechanism
179+
180+
SONiC uses copp configuration file 00-copp.config.json for configuring the trap group, ids, cpu priority queue and a policer. This functionality has been extended for supporting L2-Trace BPDU trap to CPU.
181+
182+
## 3.4 SAI
183+
184+
No SAI changes required
185+
186+
## 3.5 User Interface
187+
188+
### 3.5.1 Data Models
189+
190+
Work in progress. Openconfig YANG model is not available for L2-Trace, We will propose a l2-trace-extenstion.
191+
192+
#### 3.5.2 CLI
193+
194+
##### 3.5.2.1 Configuration Commands
195+
196+
There is no config CLI.
197+
198+
##### 3.5.2.2 Show Commands
199+
200+
- show trace-l2 vlan <vlan_id> mac <destination_address>
201+
- show trace-l2 vlan <vlan_id> ip <destination_address>
202+
- show trace-l2 vlan <vlan_id>
203+
```
204+
The probed topology is displayed using this command.
205+
The <destination address> can be a MAC address, an IP address, or a host name. You can enter the
206+
destination-address in one of the following formats:
207+
208+
- HHHH.HHHH.HHHH – Destination MAC address
209+
- A.B.C.D – Destination IP address
210+
- ASCII string – Destination host name
211+
212+
```
213+
214+
##### 3.5.2.3 Exec Commands
215+
216+
- trace-l2 vlan <vlan_id> mac <destination_address>
217+
- trace-l2 vlan <vlan_id> ip <destination_address>
218+
219+
```
220+
This command is used to trace traffic path of a packets in a L2 topology for a specific vlan
221+
222+
The <destination address> can be a MAC address, an IP address, or a host name. You can enter the
223+
destination-address in one of the following formats:
224+
225+
- HHHH.HHHH.HHHH – Destination MAC address
226+
- A.B.C.D – Destination IP address
227+
- ASCII string – Destination host name
228+
229+
If a destination address is not specified as shown below or the destination does not exists, trace-l2 collects L2 topology information which can be displayed by issuing a ‘trace-l2 show’ command.
230+
```
231+
232+
- trace-l2 vlan <vlan_id>
233+
```
234+
This command is used to probe L2 traffic path of a packets in a L2 topology for a specific vlan.
235+
```
236+
237+
# 4 Flow Diagrams
238+
239+
# 5 Serviceability and Debug
240+
241+
The existing logging mechanisms shall be used. Proposed debug framework shall be used for internal state dump.
242+
243+
# 6 Limitations
244+
245+
Following are not supported in the first release,
246+
247+
* L2-Trace to a hostname.
248+
* L2-Trace on IPv6.
249+
* L2-Trace over VxLAN.
250+
* Maximum number of parallel sessions is limited to MAX Vlan. Even though the possibility can be extended infinitely to the combination of VLAN+MAC+IP, we shall plan to increase the max_parallel_sessions on need basis.
251+
252+
# 7 Unit Test cases
253+
254+
| TC ID | Category | Objective |
255+
| ----- | ---------------- | ------------------------------------------------------------ |
256+
| 1 | Basic | Verify if all the Trace-L2 CLIs are available and gives necessary options. |
257+
| 2 | Basic | Trace-l2 operation on valid vlan |
258+
| 3 | | |
259+
| 4 | | |
260+
| 5 | Integration | Verify Mcast Suppression port works |
261+
| 6 | Negative | Trace-l2 operation on invalid vlan |
262+
| 7 | Negative | Trace-l2 operation on invalid host name |
263+
| 8 | Negative | Trace-l2 operation on Self IP Address |
264+
| 9 | Negative | Trace-l2 operation on Bridge MAC Address |
265+
| 10 | Negative | Perform more than one trace-l2 operation from different sessions |
266+
| 11 | Interoperability | Perform Trace-L2 between SONiC and Non-SONiC device. |
267+
| 12 | Advanced | Verify whether a LOOP is detected by Trace-L2. |
268+
| 13 | Basic | Verify that Trace-L2 works on tagged ports |
269+
| 14 | Advanced | Verify that Trace-L2 works on a mix of tagged and untagged ports |
270+
| 15 | Basic | Verify trace-l2 in three node topology |
271+
| 16 | | |
272+
| 17 | Basic | Verify that time, input and output ports are displayed accurately |
273+
| 18 | Basic | Verify that the topology is held for 10 minutes |
274+
| 19 | Basic | Verify trace-l2 to a destination IP |
275+
| 20 | Basic | Verify trace-l2 to a destination MAC |
276+
| 21 | Basic | Verify trace-l2 in multiple paths topology |
277+
| 22 | Interaction | Verify that Rx trace-l2 packet is dropped on STP non-fwding port |
278+
| 23 | Negative | Verify that Rx trace-l2 packet is dropped on port which is not part of vlan |
279+
| 24 | Basic | Verify new trace-l2 operation on Session1(VLAN1, destination1), cleans up operational data for same Session1(VLAN1, destination1) |
280+
| 25 | Basic | Verify new trace-l2 operation on Session2(VLAN2, destination2), does not cleanup operational data for Session1(VLAN1, destination1) |
281+
| 26 | Advanced | Verify no tracel2 topology exists after DUT Reload |
282+
| 27 | Advanced | Verify that Ctrl+C behavior on trace-l2 exec CLI |
283+
| 28 | Advanced | Verify trace-l2 operation over LAG/Port Channel |
284+
| | | |

0 commit comments

Comments
 (0)