{"id":25469489,"url":"https://github.com/justin-marian/switch-ethernet","last_synced_at":"2025-10-10T17:44:48.100Z","repository":{"id":227742776,"uuid":"770865710","full_name":"justin-marian/switch-ethernet","owner":"justin-marian","description":"Implementation for Ethernet switch features such as MAC address learning, VLAN support with 802.1Q tagging, and Spanning Tree Protocol (STP).","archived":false,"fork":false,"pushed_at":"2024-03-17T21:47:23.000Z","size":139,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-08-30T08:46:47.531Z","etag":null,"topics":["cam-table","python3","stp","switch","vlan"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"cc0-1.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/justin-marian.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-03-12T09:51:58.000Z","updated_at":"2025-02-12T11:26:14.000Z","dependencies_parsed_at":"2024-03-14T23:44:36.357Z","dependency_job_id":"8abef744-a07c-4d27-a601-a4a31aa25e6b","html_url":"https://github.com/justin-marian/switch-ethernet","commit_stats":null,"previous_names":["justin-marian/switch","justin-marian/switch-ethernet"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/justin-marian/switch-ethernet","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/justin-marian%2Fswitch-ethernet","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/justin-marian%2Fswitch-ethernet/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/justin-marian%2Fswitch-ethernet/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/justin-marian%2Fswitch-ethernet/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/justin-marian","download_url":"https://codeload.github.com/justin-marian/switch-ethernet/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/justin-marian%2Fswitch-ethernet/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279004821,"owners_count":26083784,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-10T02:00:06.843Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cam-table","python3","stp","switch","vlan"],"created_at":"2025-02-18T08:19:34.488Z","updated_at":"2025-10-10T17:44:48.078Z","avatar_url":"https://github.com/justin-marian.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Switch\r\n\r\nEthernet `Switch` that uses **VLAN segmentation** for network efficiency, **Spanning Tree Protocol (STP)** for loop prevention, and **MAC address** learning for fast frame forwarding. By  managing **VLAN membership**, **preventing loops**, and **learning MAC addresses**, the implementation ensures reliable communication and facilitates network segmentation for enhanced performance.\r\n\r\n\u003cp align=\"center\"\u003e\r\n    \u003cimg src=\"./images/topo.png\" alt=\"TOPO\" width=\"65%\"\u003e\r\n\u003c/p\u003e\r\n\r\n## Frame Forwarding Process\r\n\r\n- **Frame Arrival:** An Ethernet frame arrives at a switch through one of its ports.\r\n- **Destination MAC Address:** The switch examines the destination MAC address in the header frame.\r\n- **MAC Address Table Lookup:** The switch checks its MAC address table to find the port associated with the destination MAC address. If found, the frame is forwarded out of the corresponding port.\r\n- **Unknown Destination MAC Address:** If the MAC address is unknown, the switch floods the frame to all ports except the incoming one to ensure connectivity.\r\n- **Broadcast and Multicast:**\r\n  - `Broadcast` frames are forwarded to **all** ports except the receiving one, all devices receive the broadcast.\r\n  - `Multicast` frames are forwarded **only** to ports interested in the multicast group.\r\n\r\n## VLAN\r\n\r\n`VLANs` (`Virtual Local Area Networks`) segment a single physical LAN into multiple broadcast domains. The VLANs introduce the concept of `VLAN tagging` and forwards frames based on VLAN membership, facilitating efficient network segmentation and traffic management.\r\n\r\n\u003cp align=\"center\"\u003e\r\n    \u003cimg src=\"./images/ethernet_802.png\" alt=\"ETHERNET_802\" width=\"75%\"\u003e\r\n\u003c/p\u003e\r\n\r\n### VLAN Forwarding Process\r\n\r\n- **Frame Reception:** When a switch receives a frame with an *unknown destination or broadcast*, it forwards it to all ports within the same VLAN, including trunks.\r\n- **IEEE 802.1Q VLAN Tagging:** VLAN tagging is introduced using `IEEE 802.1Q`, adding **4** bytes to the frame. The `VID field` (**12 bits**) represents the **VLAN identifier**.\r\n\r\n**Switch Behavior:**\r\n\r\n- If on an **access port**:\r\n  - Forwards **with** `802.1Q` header on trunk interfaces.\r\n  - Forwards **without** header if VLAN ID matches that of the incoming interface.\r\n- If on a **trunk port**:\r\n  - Removes **VLAN tag** and forwards:\r\n    - **With** `802.1Q header` (including tag) on trunk interfaces.\r\n    - **Without** header if VLAN ID matches that of the received frame on access interfaces.\r\n\r\n1. **Linux VLAN Filtering:** `TPID` value of `0x8200` is used instead of `0x8100`. `PCP` and `DEI` are set to `0`.\r\n2. **Trunk Links:** Links between switches operate in **trunk mode**, allowing passage of all VLANs.\r\n3. **Configuration:** VLANs and trunk configurations are set via a `configuration file` specified in the API section.\r\n\r\n\u003cp align=\"center\"\u003e\r\n    \u003cimg src=\"./images/tag_format.png\" alt=\"TAG\" width=\"50%\"\u003e\r\n\u003c/p\u003e\r\n\r\n## STP (Spanning Tree Protocol)\r\n\r\n`STP` (`Spanning Tree Protocol`) is a protocol used to prevent loops in network topologies by creating a loop-free logical topology. This implementation provides a simplified version of STP to avoid LAN loops.\r\n\r\n- Each switch initially considers itself as the `root bridge` and starts with all ports in the `Listening state`.\r\n- `BPDUs` are exchanged between switches to elect the `root bridge` and determine the `designated ports`.\r\n- `Trunk` ports are crucial for loop prevention, and `STP` operates **only on these ports** *to avoid potential loops*.\r\n\r\n### Structure of BPDU Frames\r\n\r\n`BPDU frames` utilize encapsulation with the `802.2 Logical Link Control (LLC) header`. The `Bridge Protocol Data Units (BPDUs)` utilize the encapsulation of the 802.2 Logical Link Control (LLC) header. The structure of a BPDU is as follows:\r\n\r\n-------------------------------------------------\r\n\r\n1. **Destination MAC** (`DST_MAC`): `6` bytes\r\n2. **Source MAC** (`SRC_MAC`): `6` bytes\r\n3. **LLC Length** (`LLC_LENGTH`): `2` bytes, indicating the total size of the frame including the BPDU.\r\n4. **LLC Header** (`LLC_HEADER`): `3` bytes, comprising the **DSAP** (*Destination Service Access Point*), **SSAP** (*Source Service Access Point*), and **Control** fields.\r\n   - `DSAP`: `1` byte, typically set to `0x42` to identify the STP protocol.\r\n   - `SSAP`: `1` byte, also set to `0x42` to identify the STP protocol.\r\n   - `Control`: `1` byte, often set to `0x03` for control purposes.\r\n5. **BPDU Header** (`BPDU_HEADER`): `4` bytes, containing control information specific to STP.\r\n6. **BPDU Configuration** (`BPDU_CONFIG`): `31` bytes, encompassing various parameters such as **flags**, **root bridge ID**, **root path cost**, **sender bridge ID**, **port ID**, **message age**, **max age**, **hello time**, and **forward delay**.\r\n\r\n-------------------------------------------------\r\n\r\n### STP Forwarding Process\r\n\r\n- **Initialization:** `Trunk ports` start in the `Blocking state` to prevent loops. Switches consider themselves as `root bridges`, with all ports in the `Listening state`. If a switch it's the `root bridge`, all ports are `Designated`.\r\n- **BPDU Exchange:** Switches exchange `BPDUs` to elect the `root bridge` and determine designated ports. `BPDUs` contain **root bridge ID**, **sender bridge ID**, and **root path cost**, sent regularly on **trunk ports**.\r\n- **Root Bridge Election:** Upon receiving a `BPDU`, switches compare `root bridge IDs`. If received **ID is lower**, the switch **updates** its information and **forwards** the BPDU.\r\n  - Switches **continuously update root bridge** information.\r\n- **Port States:** Ports can be `Blocking`, `Listening`, `Learning`, or `Forwarding`.\r\n  - `Blocking` prevents loops,\r\n  - `Listening` prepares for Learning state,\r\n  - `Learning populates` MAC address tables, and\r\n  - `Forwarding` fully operates.\r\n- **Loop Prevention:** STP operates on trunk ports to prevent loops. `BPDUs` determine best paths to:\r\n  - **root bridge**\r\n  - **block redundant links**\r\n- **Frame Forwarding:** Forward frames based on established spanning tree topology, ensuring a loop-free network.\r\n\r\n## Usage\r\n\r\nTo simulate a virtual network use `Mininet`. Mininet is a network simulator that utilizes real kernel, switch, and application code implementations. Mininet can be used on both Linux and WSL2.\r\n\r\n```bash\r\nsudo apt update\r\nsudo apt install mininet openvswitch-testcontroller tshark python3-click python3-scapy xterm python3-pip\r\nsudo pip3 install mininet\r\n```\r\n\r\nAfter installing Mininet use the following command to increase the font size in the terminals we open.\r\n\r\n```bash\r\necho \"xterm*font: *-fixed-*-*-*-18-*\" \u003e\u003e ~/.Xresources\r\nxrdb -merge ~/.Xresources\r\n```\r\n\r\nWhen running the simulation, you may encounter the following error: `Exception: Please shut down the controller which is running on port 6653:`. To resolve the issue, you will need to run `pkill ovs-test`.\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjustin-marian%2Fswitch-ethernet","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjustin-marian%2Fswitch-ethernet","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjustin-marian%2Fswitch-ethernet/lists"}