vpp-maglev/README.md

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

make install-deps # installs all build-time dependencies
make              # builds build/<arch>/ 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_<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:

# 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:

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 "<name>": 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 — 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 shows every knob.
• docs/user-guide.md — flags, signals, and maglevc command reference.
• docs/config-guide.md — full YAML reference.
• docs/healthchecks.md — health state machine, probe scheduling, rise/fall semantics.
• Manpages: maglevd(8), maglevc(1), maglevd-frontend(8).

Docker

docker build -t maglevd .
docker run --cap-add NET_RAW \
  -v /etc/vpp-maglev:/etc/vpp-maglev maglevd

# With netns-scoped health checks (maglev.yaml sets healthchecker.netns):
docker run --cap-add NET_RAW --cap-add SYS_ADMIN \
  -v /etc/vpp-maglev:/etc/vpp-maglev \
  -v /var/run/netns:/var/run/netns maglevd