Skip to content

Commit 6ba3cb2

Browse files
hyperpolymathhyperpolymath
committed
Add sponsor badge
1 parent a039c32 commit 6ba3cb2

1 file changed

Lines changed: 246 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 246 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,246 @@
1+
[![Sponsor](https://img.shields.io/badge/Sponsor-%E2%9D%A4-pink?logo=github)](https://github.com/sponsors/hyperpolymath)
2+
3+
// SPDX-License-Identifier: MPL-2.0
4+
// SPDX-FileCopyrightText: 2025-2026 Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
5+
6+
= bgp-backbone-lab
7+
8+
image:https://img.shields.io/badge/OpenSSF-Best_Practices-green?logo=opensourcesecurity[OpenSSF Best Practices,link="https://www.bestpractices.dev/en/projects/new?repo_url=https://github.com/hyperpolymath/bgp-backbone-lab"]
9+
image:https://img.shields.io/badge/License-PMPL--1.0-blue.svg[License: PMPL-1.0,link="https://github.com/hyperpolymath/palimpsest-license"]
10+
image:https://api.thegreenwebfoundation.org/greencheckimage/github.com[Green Web,link="https://www.thegreenwebfoundation.org/green-web-check/?url=github.com"]
11+
12+
13+
14+
15+
:icons: font
16+
:toc: left
17+
:toclevels: 3
18+
19+
== Purpose
20+
21+
Private BGP routing, ASN allocation, route maps, and backbone simulation for the FlatRacoon Network Stack.
22+
23+
Provides a lab environment for developing and testing BGP configurations before deployment to production network infrastructure.
24+
25+
Part of the link:https://github.com/hyperpolymath/flatracoon-netstack[FlatRacoon Network Stack].
26+
27+
== Architecture
28+
29+
[source]
30+
----
31+
┌─────────────────────┐
32+
│ Transit Provider │
33+
│ AS 64500 │
34+
└──────────┬──────────┘
35+
│ eBGP
36+
┌────────────────┼────────────────┐
37+
│ │ │
38+
┌────────▼────────┐ │ ┌────────▼────────┐
39+
│ Edge Router │ │ │ Edge Router │
40+
│ AS 65001 │ │ │ AS 65002 │
41+
│ Site A │ │ │ Site B │
42+
└────────┬────────┘ │ └────────┬────────┘
43+
│ │ │
44+
│ iBGP │ iBGP │ iBGP
45+
│ │ │
46+
┌────────▼────────────────▼────────────────▼────────┐
47+
│ Core Backbone (iBGP Mesh) │
48+
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
49+
│ │ Router │◄──►│ Router │◄──►│ Router │ │
50+
│ │ R1 │ │ R2 │ │ R3 │ │
51+
│ └─────────┘ └─────────┘ └─────────┘ │
52+
└────────────────────────────────────────────────────┘
53+
│
54+
┌────────────────┼────────────────┐
55+
│ │ │
56+
┌────────▼────────┐ ┌─────▼─────┐ ┌───────▼───────┐
57+
│ ZeroTier │ │ IPFS │ │ Services │
58+
│ Overlay │ │ Nodes │ │ (K8s) │
59+
└─────────────────┘ └───────────┘ └───────────────┘
60+
----
61+
62+
== Components
63+
64+
* **GNS3/Containerlab topology** - Network simulation environment
65+
* **FRRouting configuration** - BGP daemon configs
66+
* **Route maps and policies** - Traffic engineering rules
67+
* **ASN allocation** - Private ASN management
68+
* **Monitoring** - BGP session and route monitoring
69+
70+
== Directory Structure
71+
72+
[source]
73+
----
74+
bgp-backbone-lab/
75+
├── topologies/
76+
│ ├── simple-mesh.yaml # Containerlab topology
77+
│ ├── dual-homed.yaml # Dual-homed design
78+
│ ├── full-mesh.yaml # Full iBGP mesh
79+
│ └── route-reflector.yaml # Route reflector design
80+
├── configs/
81+
│ ├── frr/ # FRRouting configurations
82+
│ │ ├── edge-router.ncl
83+
│ │ ├── core-router.ncl
84+
│ │ └── route-reflector.ncl
85+
│ ├── route-maps.ncl # Route map definitions
86+
│ ├── prefix-lists.ncl # Prefix list definitions
87+
│ └── communities.ncl # BGP community definitions
88+
├── scripts/
89+
│ ├── deploy-lab.sh # Lab deployment
90+
│ ├── validate-routes.sh # Route validation
91+
│ ├── traffic-eng.sh # Traffic engineering tests
92+
│ └── failover-test.sh # Failover testing
93+
├── docs/
94+
│ ├── asn-allocation.adoc # ASN registry
95+
│ ├── prefix-allocation.adoc # IP prefix registry
96+
│ └── design-decisions.adoc # Architecture notes
97+
├── Justfile
98+
├── README.adoc
99+
├── STATE.scm
100+
├── META.scm
101+
└── ECOSYSTEM.scm
102+
----
103+
104+
== Inputs
105+
106+
[cols="1,2,1"]
107+
|===
108+
| Input | Description | Source
109+
110+
| ASN allocation
111+
| Private ASN numbers (64512-65534)
112+
| docs/asn-allocation.adoc
113+
114+
| Prefix allocation
115+
| IPv4/IPv6 prefixes to announce
116+
| docs/prefix-allocation.adoc
117+
118+
| Topology definition
119+
| Network topology YAML
120+
| topologies/*.yaml
121+
122+
| Routing policy
123+
| Route maps and filters
124+
| configs/*.ncl
125+
|===
126+
127+
== Outputs
128+
129+
[cols="1,2"]
130+
|===
131+
| Output | Description
132+
133+
| Running lab environment
134+
| Containerlab network simulation
135+
136+
| Validated configurations
137+
| Production-ready FRR configs
138+
139+
| Route tables
140+
| Exported BGP RIB
141+
142+
| Test results
143+
| Failover and convergence metrics
144+
|===
145+
146+
== ASN Allocation
147+
148+
[cols="1,2,2"]
149+
|===
150+
| ASN | Role | Description
151+
152+
| 64512
153+
| Transit simulation
154+
| Simulated upstream provider
155+
156+
| 65001
157+
| Site A edge
158+
| Primary site edge router
159+
160+
| 65002
161+
| Site B edge
162+
| Secondary site edge router
163+
164+
| 65010
165+
| Route reflector
166+
| iBGP route reflector
167+
168+
| 65100
169+
| ZeroTier overlay
170+
| ZeroTier network routing
171+
|===
172+
173+
== Integration Points
174+
175+
=== With FlatRacoon Stack
176+
177+
* **zerotier-k8s-link** - Overlay routes announced via BGP
178+
* **ipv6-site-enforcer** - IPv6 prefix announcements
179+
* **network-dashboard** - BGP session monitoring
180+
181+
=== Machine-Readable Manifest
182+
183+
[source,json]
184+
----
185+
{
186+
"module": "bgp-backbone-lab",
187+
"version": "0.1.0",
188+
"layer": "network",
189+
"requires": ["containerlab", "frrouting"],
190+
"provides": ["bgp-simulation", "route-validation", "traffic-engineering"],
191+
"config_schema": "configs/schema.ncl",
192+
"health_endpoint": "n/a",
193+
"metrics_endpoint": "/bgp/metrics"
194+
}
195+
----
196+
197+
== Quick Start
198+
199+
[source,bash]
200+
----
201+
# 1. Start Containerlab topology
202+
just deploy simple-mesh
203+
204+
# 2. Verify BGP sessions
205+
just bgp-summary
206+
207+
# 3. Check route propagation
208+
just show-routes
209+
210+
# 4. Run failover test
211+
just failover-test edge-router-1
212+
213+
# 5. Export production configs
214+
just export-configs
215+
----
216+
217+
== Example BGP Configuration (FRR)
218+
219+
[source]
220+
----
221+
router bgp 65001
222+
bgp router-id 10.0.0.1
223+
no bgp default ipv4-unicast
224+
neighbor IBGP peer-group
225+
neighbor IBGP remote-as 65001
226+
neighbor IBGP update-source lo
227+
neighbor 10.0.0.2 peer-group IBGP
228+
neighbor 10.0.0.3 peer-group IBGP
229+
!
230+
address-family ipv6 unicast
231+
network 2001:db8:face::/48
232+
neighbor IBGP activate
233+
neighbor IBGP route-reflector-client
234+
exit-address-family
235+
----
236+
237+
== Status
238+
239+
[horizontal]
240+
Phase:: Scaffolding
241+
Completion:: 5%
242+
Next:: Containerlab topology definitions
243+
244+
== License
245+
246+
MPL-2.0

0 commit comments

Comments
 (0)