# vpp-maglev Health checker, gRPC control plane, CLI, and web dashboard for the VPP `lb` (load-balancer) plugin. Runs as a set of three binaries under one Debian package, plus an out-of-band tester built alongside: - **`maglevd`** — the long-running health-checker daemon. Probes backends (HTTP, TCP, ICMP), tracks their aggregate state, programs the VPP dataplane via the `lb` plugin binary API, and exposes everything over a gRPC API + Prometheus `/metrics` endpoint. - **`maglevc`** — the interactive CLI client. Tab-completing shell with inline help; also runs one-shot commands for scripting. - **`maglevd-frontend`** — optional web dashboard. One binary with a SolidJS Single-Page-App; connects to one or more maglevds over gRPC and serves a live HTTP view (read-only `/view/` and optional basic-auth `/admin/` with mutating commands). - **`maglevt`** — optional out-of-band VIP probe TUI. Reads a `maglev.yaml` and hits each frontend on a live HTTP path, reporting latency and a configurable response-header tally so operators can see failover as it happens. Does not talk gRPC; useful for validating a `maglevd` restart end-to-end from a client perspective. Built by `make` but not installed by the Debian package. ## Build and install ```sh make install-deps # installs all build-time dependencies make # builds build// binaries make test # runs all tests make pkg-deb # creates a Debian package for amd64 and arm64 ``` Requires Go 1.25+ and (for `make proto`) `protoc` with `protoc-gen-go` and `protoc-gen-go-grpc`. The SolidJS bundle under `cmd/frontend/web/` is built automatically via `make` through the `maglevd-frontend-web` target, which needs `npm`. Produces `vpp-maglev__amd64.deb` and `vpp-maglev__arm64.deb` in the `build/` directory by cross-compiling with `GOOS=linux GOARCH=`. Requires `dpkg-deb` (available on any Debian/Ubuntu host). The installed binaries report the exact git commit via `maglevd --version` (and similarly for `maglevc` / `maglevd-frontend`). ## Running After installing, `maglevd` is enabled automatically but `maglevd-frontend` is **not** — it's opt-in, so the web dashboard doesn't surprise anyone who just wanted the daemon: ```sh # edit /etc/vpp-maglev/maglev.yaml, then: systemctl enable --now vpp-maglev # optional: web dashboard. Edit /etc/default/vpp-maglev to set # MAGLEV_FRONTEND_ARGS and (optionally) MAGLEV_FRONTEND_USER / # MAGLEV_FRONTEND_PASSWORD for /admin/ access, then: systemctl enable --now vpp-maglev-frontend ``` Or run the components by hand: ```sh maglevd --config /etc/vpp-maglev/maglev.yaml --grpc-addr :9090 maglevd --version # print version and exit maglevc --server localhost:9090 # interactive shell maglevc show frontends # one-shot maglevc -color=false show backends # one-shot, no ANSI color maglevc set backend nginx0-ams pause maglevd-frontend -server localhost:9090 -listen :8080 ``` Send `SIGHUP` to `maglevd` to reload config without restarting. `maglevd` requires: - `CAP_NET_RAW` for ICMP health checks (raw sockets). - `CAP_SYS_ADMIN` when `healthchecker.netns` is set so probes can `setns(CLONE_NEWNET)` into the dataplane namespace. Without it, every probe errors out with `enter netns "": operation not permitted`. The Debian systemd unit grants both via `AmbientCapabilities` / `CapabilityBoundingSet`, so `systemctl start vpp-maglev` works out of the box. When running by hand under a non-root user, grant them via `setcap cap_net_raw,cap_sys_admin=eip /usr/sbin/maglevd` or equivalent. `maglevd-frontend` also ignores `SIGHUP` so a controlling-terminal disconnect (e.g. closing the SSH session it was started from) doesn't kill the daemon; `SIGTERM` / `SIGINT` remain the clean shutdown signals. Every flag on every binary also has an environment-variable equivalent (e.g. `MAGLEV_CONFIG`, `MAGLEV_GRPC_ADDR`, `MAGLEV_SERVER`, `MAGLEV_SERVERS`, `MAGLEV_LISTEN`, `MAGLEV_LOG_LEVEL`) so all three programs can be driven entirely via env in containerized deployments. ## Documentation - [docs/design.md](docs/design.md) — architecture, components, and numbered functional / non-functional requirements. Start here if you want the big picture before diving into the code. - A minimal configuration file in [debian/maglev.yaml](debian/maglev.yaml) shows every knob. - [docs/user-guide.md](docs/user-guide.md) — flags, signals, and `maglevc` command reference. - [docs/config-guide.md](docs/config-guide.md) — full YAML reference. - [docs/healthchecks.md](docs/healthchecks.md) — health state machine, probe scheduling, rise/fall semantics. - Manpages: `maglevd(8)`, `maglevc(1)`, `maglevd-frontend(8)`. ## Docker A single multi-stage Alpine `Dockerfile` produces two images, driven from `docker-compose.yaml` at the repo root: - `git.ipng.ch/ipng/vpp-maglevd:latest` — the health-checker daemon. - `git.ipng.ch/ipng/vpp-maglevd-frontend:latest` — the read-only web dashboard. Both services are **opt-in** via Docker Compose profiles, so the same stack file works for operators who want the daemon only, the frontend only (IPng's own deployment), or both on one host. Copy the example env file, choose which services to run, and start the stack: ```sh cp .env.example .env $EDITOR .env # set COMPOSE_PROFILES and any overrides docker compose up -d # starts whichever profiles are active ``` Valid `COMPOSE_PROFILES` values are `maglevd`, `frontend`, or both comma-separated. Leaving it empty starts nothing. The daemon container runs with all capabilities granted (`cap_add: ALL`) so ICMP probes and `netns`-scoped probes both work without re-plumbing the container; the frontend runs with no extra privileges. The `MAGLEV_*` variables in `.env.example` mirror `/etc/default/vpp-maglev` on a Debian install, so muscle memory carries over between the two deployment modes. Build or push the images: ```sh make docker # buildx --load, native arch only (local smoke test) make docker-push # buildx --push linux/amd64,linux/arm64 multi-arch manifest ``` `make docker` loads a single-arch image into the local daemon so you can run it immediately; `make docker-push` produces a true multi-arch manifest and pushes it to `git.ipng.ch/ipng/...`. Both use `docker buildx`, and the Dockerfile cross-compiles from the host's `$BUILDPLATFORM` to each `$TARGETARCH` via `make build-`, so no qemu-emulated builder is involved.