Pim van Pelt
35643fd774
Rename the web dashboard binary to maglevd-frontend and move it to /usr/sbin (it's a daemon and belongs with maglevd). The systemd unit name stays vpp-maglev-frontend.service since that prefix is the package name. Manpage, README, user-guide, and debian packaging all updated in lockstep; bump to 0.9.1 for the first real release. All frontend env vars are now prefixed MAGLEV_FRONTEND_ so a single /etc/default/vpp-maglev can be shared with maglevd without collisions. Every flag has an env equivalent for Docker use. MAGLEV_FRONTEND_USER and MAGLEV_FRONTEND_PASSWORD still gate the /admin surface. VPPInfoPanel now pulses "API: ↑↓" indicators in the zippy title whenever a vpp-api-send / vpp-api-recv log event arrives on the SSE stream for the scoped maglevd — 250ms blue flash, re-triggerable, with the two arrows tightly kerned via negative letter-spacing.
94 lines
3.4 KiB
Markdown
94 lines
3.4 KiB
Markdown
# 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:
|
|
|
|
- **`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 the
|
|
SolidJS SPA embedded via `//go:embed`; connects to one or more
|
|
maglevds over gRPC and serves a live HTTP view (read-only `/view/`
|
|
and optional basic-auth `/admin/`).
|
|
|
|
## Build and install
|
|
|
|
```sh
|
|
make # builds build/<arch>/{maglevd,maglevc,maglevd-frontend}
|
|
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_<version>_amd64.deb` and
|
|
`vpp-maglev_<version>_arm64.deb` in the `build/` directory by
|
|
cross-compiling with `GOOS=linux GOARCH=<arch>`. 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.
|
|
|
|
Every flag on every binary also has an environment-variable
|
|
equivalent (e.g. `MAGLEV_CONFIG`, `MAGLEV_GRPC_ADDR`,
|
|
`MAGLEV_SERVERS`, `MAGLEV_LISTEN`, `MAGLEV_LOG_LEVEL`) so all three
|
|
programs can be driven entirely via env in containerized
|
|
deployments.
|
|
|
|
## Documentation
|
|
|
|
- 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
|
|
|
|
```sh
|
|
docker build -t maglevd .
|
|
docker run --cap-add NET_RAW -v /etc/vpp-maglev:/etc/vpp-maglev maglevd
|
|
```
|