A hands-on, engineering-focused project that models how real SONiC-based switches behave internally.
This tool brings together the essential building blocks of a modern data-center switch: VLAN handling, routing, BGP/FRR neighbor logic, ARP behavior, next-hop selection, and ECMP load balancing.
Rather than replicating a full NOS, this project focuses on the parts engineers actually debug every day.
This project started as a personal way to understand how SONiC and FRRouting manage L2/L3 control-plane behavior.
Everything here—from the BGP state machine to ECMP hashing—is written with simplicity, clarity, and real switch behavior in mind.
The goal is not to be a simulator.
The goal is to think like a switch, debug like an engineer, and see how protocols interact internally.
- Builds VLANs and port memberships
- Tracks MAC learning logic
- Identifies mismatched FDB entries
- Helps visualize L2 segmentation
- Longest-prefix match logic
- Multi-path routing (ECMP) with round-robin rotation
- Route origin tracking (static, connected, BGP)
- Debug-friendly route history
- Simplified BGP FSM
- Keepalive timers
- Flap detection
- Basic advertisement behavior
- Neighbor stability score
- Dynamic and static learning
- ARP aging
- Miss and retry logic
- Pending state tracking
- VLAN mismatch detector
- ECMP path-change observer
- BGP flap analyzer
- Route convergence tracker
- State history viewer
- Lightweight 5-tuple hashing
- ECMP distribution simulation
- Useful for checking load-balancing behavior
sonic-l2l3-protocol-debugger/
├── main.py
├── build_and_run.ps1
├── requirements.txt
├── README.md
├── .gitignore
├── .vscode/ # editor settings (optional to document)
├── src/
│ ├── vlan_manager.py
│ ├── routing_engine.py
│ ├── bgp_frr_neighbor.py
│ ├── arp_table.py
│ ├── cli.py
│ └── __pycache__/ # generated, not committed
├── cpp/
│ └── packet_processor.cpp
└── docs/
└── QUICKSTART.md
Everything is organized the same way a real NOS codebase is separated:
L2, L3, control-plane state machines, and tools.
Requires Python 3.9+.
Install dependencies:
pip install -r requirements.txt
python main.py
You will see the banner and can start issuing commands (e.g. show vlan).
On Windows you can use the included script:
./build_and_run.ps1
This can be extended to compile C++ or perform pre-run checks (currently lightweight).
To experiment with the ECMP hashing logic:
g++ -O2 -std=c++17 cpp/packet_processor.cpp -o packet_processor
./packet_processor
__pycache__/ and .vscode/ are generated/editor-specific and intentionally excluded from conceptual docs.
The CLI behaves like a trimmed SONiC/FRR environment:
show vlan
show arp
show ip bgp summary
show ip bgp neighbors
show route
show ecmp paths
debug bgp events
debug vlan mismatch
debug route updates
help
exit
The initial environment loads with:
- Prebuilt VLANs
- Static + BGP-style routes
- Neighbors in different FSM states
- ARP entries that age naturally
- ECMP routes to observe hashing behavior
It's meant to feel like a switch you can play with, without needing hardware
Designed to be easy to follow but still realistic:
- Longest prefix match
- Multipath awareness
- Hop rotation
- Next-hop visibility
Imitates FRR's practical behavior:
- State transitions
- Keepalive timing
- Flap counters
- Basic advertising logic
Reflects real control planes:
- Pending state
- Retry tracking
- Aging and cleanup
- Static overrides
Useful for:
- Testing per-flow distribution
- Observing how hashing decisions behave
- Validating path imbalance
===============================================
SONiC L2/L3 Protocol Debugger
Type 'help' for available commands
===============================================
> show vlan
VLAN Name Ports
10 Users Ethernet0, Ethernet4
20 Mgmt Ethernet8
30 Storage Ethernet12
Routes, BGP neighbors, and ARP tables show in a similar detailed format.
I wanted a realistic environment to learn, test, and visualize how:
- Control-plane states transition
- ECMP makes decisions
- BGP behaves under flaps
- ARP interacts with routing
- VLANs affect forwarding
This project gave me a way to explore these ideas without relying on vendor hardware.
I'm Vamsi Reddy Galiveeti, a software engineer who enjoys building systems that behave like real networking platforms.
My interests revolve around C++, Python, system design, cloud networking, SONiC, FRR, and data-center routing.
I love writing clean, understandable code and recreating real-world scenarios in small, focused tools.
📧 vamsigaliveetivr@gmail.com
📍 Dallas, TX
🔗 LinkedIn