Example new

examples/basic/README.md

@@ -0,0 +1,47 @@
+# Basic Examples
+
+This folder contains small, focused SEED Emulator examples. The `A00`-series
+examples introduce core emulator concepts, progressively adding routing,
+real-world connectivity, components, compiler behavior, customization, mixed
+backends, ExaBGP, generated topologies, and control-plane regression coverage.
+
+Many examples include an `example.yaml` manifest and `test_runtime.py` so they
+can be run through `seedemu.testing`.
+
+## Examples
+
+| Example | Purpose |
+| --- | --- |
+| `A00_simple_as` | Builds three simple autonomous systems on one IX, adds web hosts, and verifies basic cross-AS reachability. This is the minimal reference example for the standardized test lifecycle. |
+| `A01_transit_as` | Demonstrates a transit AS connecting two stub ASes through eBGP and internal routing. It also shows how to save the emulation as a reusable component. |
+| `A02a_transit_as_mpls` | Demonstrates MPLS/LDP in a transit AS using the emulator's MPLS layer. This example depends on host MPLS kernel support for full runtime validation. |
+| `A02b_manual_mpls` | Demonstrates manual MPLS label-table setup instead of relying on LDP. It is useful for teaching MPLS label push, swap, and pop behavior explicitly. |
+| `A03a_out_to_real_world` | Demonstrates outbound real-world connectivity from inside the emulator, using a real-world AS/prefix target. |
+| `A03b_from_real_world` | Demonstrates access from the real world into the emulator using OpenVPN remote access. |
+| `A04_visualization` | Demonstrates visualization metadata, including display information used by maps or graphing tools. |
+| `A05_components` | Demonstrates loading a prebuilt component, modifying it, and adding new ASes, hosts, and IXes around it. |
+| `A06_merge_emulation` | Demonstrates merging two separately built emulations into one combined emulator. |
+| `A07_compilers` | Demonstrates compiler and registry usage, including different compiler outputs. |
+| `A08_buildtime_docker` | Demonstrates using a build-time Docker container during emulator build, including generated artifacts from a helper image. |
+| `A09_node_customization` | Demonstrates node customization, including adding programs and custom behavior to nodes. |
+| `A10_add_containers` | Demonstrates attaching existing containers to networks inside an emulation. |
+| `A11_add_containers_new` | Demonstrates newer patterns for adding existing containers and displaying them in the Internet map. |
+| `A12_bgp_mixed_backend` | Demonstrates mixed BIRD and FRR routing backends in the same IPv4 emulator topology. |
+| `A13_exabgp` | Demonstrates adding an ExaBGP speaker to the emulator and manually announcing or withdrawing routes through a helper script. |
+| `A15_toplogy_generator` | Demonstrates the NetworkX-based autonomous-system topology generator, including generated internal topology, eBGP attachment, iBGP mode selection, and topology artifacts. |
+| `A20_nano_internet` | Builds a very small Internet to demonstrate basic Internet-scale composition with transit and stub ASes. |
+| `A21_shadow_internet` | Demonstrates a shadow Internet topology for experimenting with a larger emulated Internet structure. |
+| `A62_route_reflector` | Demonstrates route-reflector use in transit ASes and compares iBGP designs with and without route reflection. |
+| `A63_control_plane_regression` | Provides a compact regression example covering BIRD route servers, mixed BIRD/FRR routers, route reflectors, ExaBGP binding, and MPLS/LDP readiness. |
+
+## Running Tested Examples
+
+For examples with `example.yaml`, use:
+
+```sh
+python -m seedemu.testing.cli all examples/basic/A00_simple_as/example.yaml
+```
+
+Replace the path with the example you want to run. Some examples, especially
+MPLS and real-world connectivity examples, require host or network support that
+may not be available in every CI environment.

examples/routing/R01_routing_matrix/README.md

@@ -0,0 +1,54 @@
+# R01 Routing Matrix Regression
+
+This example is a compact regression suite for the routing control plane. It
+uses several independent transit ASes in one emulator. Each transit AS
+demonstrates one routing design/backend combination.
+
+## Matrix
+
+```text
+AS2: all-router full mesh, BIRD
+AS3: all-router full mesh, FRR
+AS4: all-router route reflector, BIRD
+AS5: all-router route reflector, FRR
+AS6: auto-completed route reflector, mixed BIRD/FRR
+AS7: edge-only full mesh, mixed BIRD/FRR
+```
+
+Each transit AS connects two stub ASes. For example:
+
+```text
+AS150 -- IX100 -- AS2 -- IX101 -- AS151
+```
+
+The slices are independent, so a failure usually points to one routing design.
+
+## What This Tests
+
+- eBGP private peering at IXes
+- iBGP all-router full mesh
+- iBGP route-reflector rendering
+- deterministic AS-level route-reflector auto-completion
+- BIRD BGP rendering
+- FRR BGP rendering
+- mixed BIRD/FRR iBGP interoperability
+- edge-only iBGP control-plane structure
+
+AS7 is a structural BGP-free-core control-plane test. It intentionally does not
+require end-to-end plain-IP forwarding because the core routers do not carry the
+external BGP table.
+
+## Run
+
+From the repository root:
+
+```sh
+python seedemu/testing/cli.py clean examples/routing/R01_routing_matrix/example.yaml
+python seedemu/testing/cli.py compile examples/routing/R01_routing_matrix/example.yaml
+python seedemu/testing/cli.py build examples/routing/R01_routing_matrix/example.yaml
+python seedemu/testing/cli.py all examples/routing/R01_routing_matrix/example.yaml
+```
+
+The custom runtime test inspects generated Docker Compose labels and router
+configuration files, then writes `routing-matrix-runtime-test.json` into the
+test artifact directory.

examples/routing/R01_routing_matrix/example.yaml

@@ -0,0 +1,109 @@
+id: routing-r01-routing-matrix
+name: Routing Matrix Regression
+description: Exercises major iBGP designs across BIRD, FRR, and mixed backends.
+runner: internet
+script: routing_matrix.py
+platform: amd
+features:
+  - routing-regression
+  - ebgp-private-peering
+  - ibgp-full-mesh
+  - ibgp-route-reflector
+  - ibgp-auto-complete
+  - bird
+  - frr
+  - ospf
+
+compile:
+  enabled: true
+  output: output
+  clean:
+    - output
+  expected:
+    - output/docker-compose.yml
+  timeout: 300
+
+build:
+  enabled: true
+  timeout: 1200
+
+runtime:
+  compose: output/docker-compose.yml
+  readiness:
+    - name: routing matrix services are running
+      type: compose-ps
+      services:
+        - brdnode_2_edge0
+        - rnode_2_core0
+        - rnode_2_core1
+        - brdnode_2_edge1
+        - brdnode_3_edge0
+        - rnode_3_core0
+        - rnode_3_core1
+        - brdnode_3_edge1
+        - brdnode_4_edge0
+        - rnode_4_core0
+        - brdnode_5_edge0
+        - rnode_5_core0
+        - brdnode_6_edge0
+        - rnode_6_core0
+        - brdnode_7_edge0
+        - rnode_7_core0
+        - hnode_150_host_0
+        - hnode_151_host_0
+        - hnode_152_host_0
+        - hnode_153_host_0
+        - hnode_154_host_0
+        - hnode_155_host_0
+        - hnode_156_host_0
+        - hnode_157_host_0
+        - hnode_158_host_0
+        - hnode_159_host_0
+      retries: 40
+      interval: 3
+
+probes:
+  - name: AS150 reaches AS151 through AS2 BIRD full mesh
+    type: ping
+    service: hnode_150_host_0
+    target: 10.151.0.71
+    count: 3
+    retries: 30
+    interval: 5
+
+  - name: AS152 reaches AS153 through AS3 FRR full mesh
+    type: ping
+    service: hnode_152_host_0
+    target: 10.153.0.71
+    count: 3
+    retries: 30
+    interval: 5
+
+  - name: AS154 reaches AS155 through AS4 BIRD route reflector
+    type: ping
+    service: hnode_154_host_0
+    target: 10.155.0.71
+    count: 3
+    retries: 30
+    interval: 5
+
+  - name: AS156 reaches AS157 through AS5 FRR route reflector
+    type: ping
+    service: hnode_156_host_0
+    target: 10.157.0.71
+    count: 3
+    retries: 30
+    interval: 5
+
+  - name: AS158 reaches AS159 through AS6 auto-completed route reflector
+    type: ping
+    service: hnode_158_host_0
+    target: 10.159.0.71
+    count: 3
+    retries: 30
+    interval: 5
+
+test_programs:
+  - name: routing matrix runtime validation
+    script: test_runtime.py
+    timeout: 420