Twinet is a Go implementation of a container-based teaching network twin. It builds, places, operates, and grades labs made of real Linux containers, routers, and switches.
Documentation status. āShippedā below means a capability exists in this source tree and is covered by automated checks. āMeasuredā means a result was observed on the named cluster run in the status ledger; it is not a release or capacity promise. āTargetā and āhistoricalā claims are explicitly labelled in the supporting documents.
- The controller talks to node agents through an HTTP/JSON API. A non-loopback agent requires TLS 1.3 mutual authentication (plus its controller token); this is not gRPC.
- The build contains several command entry points, not just a controller and
agent. The source-generated list, runtime/NOS registries, interior generators,
fault count, and bundled-example statistics are checked in
docs/09_status.md. - Docker, Podman, and containerd are registered, selectable runtimes.
placement.runtimeand per-node overrides are validated against runtime capabilities before mutation; agent status exposes backend/version/socket and deployment rejects a mismatch. Every bundled example declaresruntime: containerd, the engine the operator guide installs, and--runtimeorTWINET_RUNTIMEruns the same manifest unmodified on Docker or Podman.make podman-integrationandmake containerd-integrationare the explicit real-engine lifecycle gates. Twinet therefore has host and image dependencies; it is not a one-binary, dependency-free deployment. - Deterministic allocation still derives names, addresses, and link identifiers from a manifest. Student-owned configuration, topology/coordination records, event journals, and replica acknowledgements are instead persisted in the state store.
- Cluster mutation uses fenced leases and transactional agent phases. Cross-node links share one external VXLAN device per lab/node pair; bridge VLAN-to-VNI bindings isolate logical links.
- State and services have replication policies, strict live-inventory admission runs before cluster mutation, and agents expose bounded Prometheus metrics and a durable, scoped event stream.
- FRR and BIRD are registered NOS providers.
explicit,ring,two-tier, andclosare registered interior generators. Capability validation refuses unsupported NOS/topology combinations before deployment.
The precise scope and evidence for these features are deliberately kept out of marketing language: see Implementation status.
The current measured reference deployment is a 12-AS lab. Its timing range,
the class-scale result, and grading measurements are recorded only in
docs/09_status.md#measurements. They are
measurements from a specific three-node environment, not claims that every
machine or course will obtain the same result.
Multicast and the RPKI hijack exercise are implemented examples with grading checks and behaviour/fault support. Their source coverage does not imply that every course acceptance scenario has been run live; the distinction is recorded in the status ledger.
| Document | Scope |
|---|---|
| Assessment | Historical assessment of the predecessor platform |
| Architecture | Source-verified control-plane and persistence architecture |
| Topology model | Manifest, NOS, interior, and behaviour model |
| Networking and scale-out | Shared overlay, placement, durability, and admission design |
| Services and access | Services, replicas, access, metrics, and events |
| Grading | Shipped grading modes and evidence boundaries |
| Roadmap | Historical targets and remaining acceptance work |
| Resources and decisions | Historical decision record and current evidence boundary |
| Implementation status | Canonical shipped/target/measured ledger |
| Fault injection and RCA | NIKA fault work (maintained separately) |
| Scalability and reliability objectives | Objectives and review gate (maintained separately) |
| Operator guide | Runbook from three clean machines to a deployed, graded, and safely removed lab |
Documentation gates are executable:
go test ./internal/cli -run 'Test(EveryDocumented|Documentation)'
python3 scripts/check_docs.pyThe first command checks documented commands, the flags written after them, and source-derived capability facts. The second checks Markdown local links, referenced paths, and benchmark labels. Full source validation remains:
go test ./...Twinet builds on the teaching ideas of the mini-Internet project by the Networked Systems Group at ETH ZĆ¼rich. It shares no code with that project.