benvin
f80cc2cc30
Project the fleet-global model through a device's bindings into a rendered,
interface-agnostic config: rules compile to saddr/daddr forward matches with no
iif/oif so they are correct under FRR/ECMP. Firewalls always enforce; routers
enforce only when their fabric opts into defense-in-depth. Referenced address
groups are emitted as named sets carrying their source (static CIDRs, dns FQDNs,
or asn numbers) so membership churns out-of-band without a rule reload. Wire
GET /devices/{name}/config to compile and serve YAML, generation-stamped. Add
portgroups/policies/settings store methods and portgroup CRUD. Pure Render is
unit-tested for enforcement gating, ASN set emission, and resolver precedence.
tomswallapi
Fleet control plane for tomswall.
Declare zones, address groups, and firewall policy once; the API compiles each
intent into the concrete per-device rules every firewall and router on the path
needs, and serves each device its rendered tomswall.yaml. A connection that
crosses several firewalls — src → rt1 → rt2 → rt3 → dest — is expressed as a
single rule.
The full design (data model, compile algorithm, invariants, agent protocol) lives
in DESIGN.md in
the tomswall repo.
Architecture
- tomswallapi (this repo) — Terraform-managed HTTP API. Stores the fleet model in Postgres, peers with FRR for reachability, compiles intents into per-device configs, and serves them.
- tomswall agent — pulls its rendered config, runs the existing differential
apply, maintains dns-backed ipsets via an on-device resolver, and reports the config generation it has applied. Does not fail closed on API-unreachable.
Running locally
docker compose up --build
# API on :8000, Postgres on :5432
curl -s localhost:8000/healthz
Configuration
All configuration is via environment variables (TOMSWALLAPI_*):
| var | default | purpose |
|---|---|---|
TOMSWALLAPI_LISTEN_ADDR |
:8000 |
HTTP listen address |
TOMSWALLAPI_DB_HOST |
localhost |
Postgres host |
TOMSWALLAPI_DB_PORT |
5432 |
Postgres port |
TOMSWALLAPI_DB_USER |
tomswallapi |
Postgres user |
TOMSWALLAPI_DB_PASSWORD |
— | Postgres password |
TOMSWALLAPI_DB_NAME |
tomswallapi |
Postgres database |
TOMSWALLAPI_DB_SSLMODE |
disable |
Postgres sslmode |
TOMSWALLAPI_WRITE_TOKEN |
— | bearer token guarding mutating endpoints (Terraform) |
TOMSWALLAPI_AGENT_TOKEN |
— | bearer token guarding the per-device config endpoint (agents) |
TOMSWALLAPI_IPLOCATE_API_KEY |
— | iplocate key for ASN address-group expansion |
Migrations are embedded and applied automatically on startup.
Development
make build # build the binary
make test # run tests
make lint # gofmt + go vet
make run # build and run
Releases
make patch|minor|major computes and pushes the next v* tag, which triggers the
Woodpecker docker pipeline to build and push the image to
git.unkin.net/unkin/tomswallapi.