{"id":50309583,"url":"https://github.com/dotchance/nodalarc","last_synced_at":"2026-05-29T01:00:46.208Z","repository":{"id":359029224,"uuid":"1168689939","full_name":"dotchance/nodalarc","owner":"dotchance","description":"Satellite network emulator for orbital routing, handoffs, and moving topology.","archived":false,"fork":false,"pushed_at":"2026-05-20T03:52:06.000Z","size":22706,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-20T07:06:57.357Z","etag":null,"topics":["bgp","emulation","emulator","frr","isis","kubernetes","leo","linux-networking","mpls","network-visualization","networking","orbital","ospf","routing","satcom","satellite","segment-routing","space","traffic-engineering","vxlan"],"latest_commit_sha":null,"homepage":"https://nodal.asmolab.net","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dotchance.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":"CLA.md"}},"created_at":"2026-02-27T17:24:56.000Z","updated_at":"2026-05-20T03:52:08.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/dotchance/nodalarc","commit_stats":null,"previous_names":["dotchance/nodalarc"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/dotchance/nodalarc","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dotchance%2Fnodalarc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dotchance%2Fnodalarc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dotchance%2Fnodalarc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dotchance%2Fnodalarc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dotchance","download_url":"https://codeload.github.com/dotchance/nodalarc/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dotchance%2Fnodalarc/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33632271,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-28T02:00:06.440Z","response_time":99,"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":["bgp","emulation","emulator","frr","isis","kubernetes","leo","linux-networking","mpls","network-visualization","networking","orbital","ospf","routing","satcom","satellite","segment-routing","space","traffic-engineering","vxlan"],"created_at":"2026-05-28T20:00:31.626Z","updated_at":"2026-05-29T01:00:46.202Z","avatar_url":"https://github.com/dotchance.png","language":"Python","funding_links":[],"categories":["Software and Tools","Spacecraft"],"sub_categories":["Network simulators and emulators","Simulation"],"readme":"# NodalArc - Satellite Network Emulation for Orbital Routing\n\nNodalArc is an orbital network emulator for testing real routing stacks against moving satellite topology.\n\nIt gives network engineers a lab where satellites move, links appear and disappear, ground exits change, and routers have to live inside that motion.\n\n![NodalArc globe view](docs/images/readme-globe.png)\n\n## What NodalArc Is\n\nNodalArc is an emulator, not a packet-level simulator.\n\nEach satellite and ground station becomes a real Linux network namespace running a real routing stack. IS-IS hellos, OSPF LSAs, BGP updates, MPLS labels, kernel interfaces, carrier transitions, VXLAN links, and `tc` shaping all happen in the system that Linux actually runs.\n\nThe orbital mechanics are not decoration around a static lab. They drive the lab. When two satellites move out of range, the interface drops. When a ground station hands off to a new satellite, the router sees the carrier event. When the distance between two endpoints changes, the link latency changes with it.\n\nNodalArc is for testing questions like:\n\n- What does IS-IS do when cross-plane links disappear at the polar seam?\n- How much route churn does a ground-station handoff create?\n- What happens when the same constellation runs under OSPF, IS-IS, SR-MPLS, or centralized path computation?\n- How much of a measurement came from the protocol, and how much came from the lab substrate?\n- When does distributed routing stop being the right model?\n\nThat is the point: give real routers a moving world and watch what they do.\n\n## Why This Exists\n\nNetworks are leaving the ground.\n\nThat sounds like a slogan until you have to route through it. A terrestrial network lets you pretend the topology is mostly fixed. Links fail, routers reboot, fiber gets cut, but the bones of the thing stay where you put them.\n\nOn-orbit and space-based networks do not work that way.\n\nA satellite in low Earth orbit is moving about seven and a half kilometers a second. A cross-plane link can exist now and be gone a few minutes later. A ground station can be the best exit from the network this pass, and useless on the next. On the ground, topology change is an event. In orbit, topology change is the medium you are swimming in.\n\nNodalArc was built to make that difference measurable.\n\n## Quick Start\n\nThe command line is for installation and operations. Once NodalArc is running, users work from the browser.\n\n### Requirements\n\n- Kubernetes or K3s cluster with Linux worker nodes\n- Privileged node access for kernel networking operations\n- Container image build and load/pull path for the cluster\n- Host kernel support for network namespaces, veth, VXLAN, `tc`, forwarding, and MPLS where needed\n- `kubectl`, Helm, Docker, Node.js 22, and `uv`\n- 8 GB RAM minimum for the demo constellation\n- 32 GB RAM recommended for larger constellations\n\nThe bootstrap script is intended for fresh Linux hosts and is tested on Ubuntu/Debian-family systems. If you already have Kubernetes, you can skip bootstrap and install into the cluster.\n\n### Install And Run\n\n```bash\ngit clone https://github.com/dotchance/nodalarc.git\ncd nodalarc\nsudo scripts/bootstrap-host.sh\nmake all\n```\n\n`make all` builds the frontend, builds the service images, loads them into the cluster, installs the Helm chart, deploys the default session, and prints status.\n\nWhen the platform is ready, open:\n\n```text\nhttp://localhost:3000\n```\n\nFor a remote host, expose or forward port `3000` for the visualization frontend and port `8080` for VS-API.\n\n## The Browser Is The Lab\n\nNodalArc is built so a platform operator can install it, and a network engineer can run experiments from the GUI without touching `make`, `kubectl`, or shell scripts.\n\nFrom the browser you can:\n\n- choose constellations, satellite types, ground-station sets, and routing stacks\n- preview coverage before deploying a bad session\n- deploy and switch sessions\n- watch satellites, ISLs, ground links, handoffs, and convergence events\n- inspect individual satellites and ground stations\n- trace paths between nodes\n- open a terminal on a routing instance and run router commands\n\nThe browser is not a mock-up. It is connected to the running emulation.\n\n## Visual Workflow\n\n### 1. Watch The Moving Network\n\nThe globe shows satellites, ground stations, orbital paths, inter-satellite links, and ground links in motion. Link state follows the geometry.\n\n![Live NodalArc globe with satellite links](docs/images/readme-globe.png)\n\n### 2. Build Or Select A Session\n\nThe session wizard reads the same files the runtime reads. You can deploy from existing YAML, choose from catalog presets, or build a new session from primitives.\n\n![Session catalog and constellation picker](docs/images/readme-session-catalog.png)\n\nThe important boundary is still the session. The wizard is a safer way to write it, not a second configuration system.\n\n![Session ready for coverage preview](docs/images/readme-session-ready.png)\n\n### 3. Preview The Geometry Before Deploy\n\nThe coverage preview runs feasibility math before pods come up. It shows which ground stations are reachable, where the gaps are, how ISLs form, and where the selected geometry is going to disappoint you.\n\n![Coverage preview with ground-station gaps and ISL statistics](docs/images/readme-coverage-preview.png)\n\nThe editor can tell you whether the YAML parses. The preview tells you whether the sky agrees.\n\n### 4. Inspect The Running Network\n\nSelect a satellite or ground station to see active links, link latency, position, route-adjacency context, and trace controls.\n\n![Selected satellite detail panel](docs/images/readme-node-detail.png)\n\nSwitch to the topology view when the orbital picture is too physical and you want the graph.\n\n![Topology view of a running constellation](docs/images/readme-topology.png)\n\n### 5. Open A Router Terminal\n\nEvery satellite and ground station is a routing instance. Open the terminal and run the commands you already know.\n\n![Router terminal in the browser](docs/images/readme-router-terminal.png)\n\nThe terminal is not decorative. This is one shell into one real routing instance among hundreds. Each satellite and ground station has its own namespace, interfaces, routing daemon, neighbors, and forwarding table. The globe is the view. The routers are real.\n\n![FRR terminal showing show isis neighbor output](docs/images/readme-router-cli.png)\n\n## What You Can Test\n\nOnce the system is running, you can:\n\n- watch IS-IS or OSPF reconverge as orbital links appear and disappear\n- measure ground-station handoff impact instead of arguing about timers\n- run the same constellation under IS-IS, OSPF, SR-MPLS, or external path engines\n- change altitude, inclination, plane count, phase offset, and satellite terminal models\n- move ground stations and see what reachability you bought or lost\n- run `ping`, `traceroute`, and `iperf` through the emulated constellation\n- open a browser terminal to any satellite or ground station and use `vtysh`\n- script experiments through the REST and WebSocket APIs\n- connect external systems to the emulation and watch how they behave\n\nStart small. Demo-36 is enough to see the machinery. Starlink-176 and Iridium-66 start to show why the geometry matters. A Walker Delta gives you a steady backbone and access handoffs. A Walker Star gives you global reach and a polar seam that tears through the backbone on schedule.\n\nThat is where the interesting questions start.\n\n## What The System Gives You\n\n### Real Routing Stacks\n\nNodalArc starts with FRR because FRR is practical, scriptable, open, and already gives us IS-IS, OSPF, BGP, SR-MPLS, LDP, and traffic engineering.\n\nBut NodalArc is not an FRR simulator.\n\nThe router is a container boundary. If a routing stack can run in a container and attach to Linux interfaces, NodalArc can put it inside the moving topology. That means FRR on the satellites, Arista cEOS at the ground stations, Cisco XRd on a lunar relay, Juniper cRPD at a gateway, or any mix that makes the experiment worth running.\n\nThe emulator does not care whose CLI is inside the node. It gives the router interfaces, carrier events, latency, bandwidth, and reachability. The router gives back behavior.\n\nThat is the point. Real stacks, same sky.\n\n### Real Kernel Networking\n\nThe Node Agent builds veth pairs and VXLAN tunnels, then shapes them with `tc netem` and `tc tbf`. Latency comes from range. Bandwidth comes from the terminal model. The lab has a substrate, and the substrate is measured.\n\n### Session Primitives\n\nNodalArc sessions are built from primitives:\n\n- satellite types describe hardware: terminals, ranges, bandwidth, tracking limits\n- constellation geometry describes where the satellites move\n- ground stations describe where the network touches Earth and what prefixes enter there\n- routing stacks describe what runs inside each node\n\nChange one primitive and leave the others alone. Same sky, different routing. Same routing, different sky. Same constellation, different ground exits. A clean comparison has one deliberate difference.\n\n### Time Control\n\nPause, resume, change speed, and seek. If a failure happens at a certain point in the orbit, move time there and inspect the state while the system is still.\n\n### Multi-Node Scale\n\nA single machine can run hundreds of nodes. A Kubernetes cluster can spread the emulation across machines. Local links use host-mediated veths. Cross-node links use VXLAN. Substrate latency compensation keeps the emulated delay tied to the orbital path, not to the physical lab network.\n\n### External Path Engines\n\nNodalArc keeps the emulation substrate honest: orbital mechanics, carrier events, Linux interfaces, timing, and observability. External path engines, including NodalPath, can attach to that substrate when distributed routing is not the model you want to test.\n\n## Architecture At A Glance\n\n```text\nOME          Orbital mechanics and visibility truth\nScheduler    Desired topology, reconciliation, and link intent\nNode Agent   Host kernel operations and proof of actual state\nOperator     Session lifecycle, pods, configs, and deployment\nVS-API       Browser/API front door and state aggregation\nVF           React + Three.js visualization frontend\nNATS         Event bus and durable fact stream\n```\n\nThe boundary matters. OME computes the sky. The Scheduler decides what should exist. The Node Agent proves what Linux actually did. The router owns routing.\n\n## Project Structure\n\n```text\nservices/       Backend services: OME, Scheduler, Node Agent, VS-API, Operator\nfrontend/       Visualization frontend: React + Three.js\nlib/            Shared Python library\nimages/         Container images: FRR and probe\ndeploy/         Helm chart and deployment tooling\nconfigs/        Constellations, ground stations, satellite types, sessions\ntests/          Unit and integration tests\ndocs/           User, operations, and developer documentation\nscripts/        Lifecycle, host bootstrap, and operational scripts\ntools/          Python report, scenario, compare, and reconfig CLIs\n```\n\n## Documentation\n\nThe docs are split by the work you are trying to do.\n\n- [User Guide](docs/user/) - visualization, sessions, node inspection, path tracing, terminal access, and API use\n- [Operations Guide](docs/ops/) - install, Kubernetes deployment, multi-node clusters, scaling, teardown, and troubleshooting\n- [Developer Guide](docs/dev/) - architecture, invariants, services, tests, and contribution workflow\n\n## Community\n\nNodalArc is open source under the Apache License 2.0 and welcomes useful contributions. Bugs, routing stacks, constellation models, visualization improvements, documentation fixes, and operational reports all help, as long as they respect the architecture.\n\n- **Issues** - bug reports, feature requests, and questions\n- **Pull Requests** - read [CONTRIBUTING.md](CONTRIBUTING.md), the [Developer Guide](docs/dev/), and the [Contributor License Agreement](CLA.md) before opening one\n- **Discussions** - architecture proposals, use cases, and experiments\n\n## License\n\nNodalArc is licensed under the Apache License 2.0. You can use, modify, and distribute it under the Apache License, Version 2.0. See [LICENSE](LICENSE) for full terms and [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) for bundled third-party notices.\n\nCopyright 2024-2026 .chance (dotchance)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdotchance%2Fnodalarc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdotchance%2Fnodalarc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdotchance%2Fnodalarc/lists"}