Pim van Pelt
744b1cb3d2
Makefile:
- New install-deps umbrella target split into three sub-targets:
install-deps-apt — Debian/Trixie-packaged build deps
(nodejs, npm, protobuf-compiler, git, make,
dpkg-dev, ca-certificates, curl, tar). Uses
sudo when not already root.
install-deps-go — ensures a Go toolchain >= GO_VERSION (go.mod
floor, default 1.25.0). Short-circuits when
the system Go is already recent enough;
otherwise downloads the upstream tarball
from go.dev/dl/ into /usr/local/go. Trixie
only ships 1.24 so this step is load-bearing.
install-deps-go-tools — go install protoc-gen-go, protoc-gen-go-grpc,
and golangci-lint/v2/cmd/golangci-lint. Then
asserts the installed golangci-lint version
parses as >= GOLANGCI_LINT_VERSION (default
1.64.0, the floor that supports Go 1.25
syntax) to catch stale binaries in $GOPATH
/bin before they silently run against Go
1.25 code.
- Parser bug fixed: golangci-lint v1.x prints "has version v1.64.8" but
v2.x dropped the 'v' prefix and prints "has version 2.11.4". The
original sed regex required the 'v' and returned an empty match on
v2.x, making the assertion explode with "could not parse version
output". Fixed by switching to extended regex (sed -En) with 'v?' so
both forms parse cleanly.
- GO_VERSION and GOLANGCI_LINT_VERSION exposed as Makefile variables
so operators can override on the command line, e.g.
make install-deps GO_VERSION=1.25.5 GOLANGCI_LINT_VERSION=2.0.0
- .PHONY extended with the four new target names.
Docs:
- README.md: capability note rewritten to cover CAP_NET_RAW (ICMP) and
the new CAP_SYS_ADMIN requirement when healthchecker.netns is set,
plus a paragraph explaining that the Debian systemd unit grants both
automatically. Docker example gained a second variant that shows the
additional --cap-add SYS_ADMIN and /var/run/netns bind mount for
netns-scoped deployments. Also notes that maglevd-frontend ignores
SIGHUP so controlling-terminal disconnects don't kill it.
- docs/user-guide.md: Capabilities section rewritten as a bulleted
list covering both caps, with the EPERM error string and three
different ways to grant them (systemd unit, setcap, systemd-run);
'show vpp lb counters' command description updated to explain that
per-backend packet counts are no longer shown (LB plugin's
forwarding node bypasses ip{4,6}_lookup_inline, so /net/route/to at
the backend's FIB entry never ticks for LB-forwarded traffic); new
~75-line "What the SPA shows" subsection covering the scope
selector + maglev_scope cookie, the per-maglevd frontend cards, the
health-cascade icon table (ok / bug-buckets / primary-drained /
degraded / unknown), the lb buckets column semantics, the
maglev_zippy_open cookie, the admin-mode lifecycle dialogs with
their plain-English consequence text, and the debug panel.
- docs/config-guide.md: healthchecker.netns field gains a capability-
requirement note spelling out setns(CLONE_NEWNET), the EPERM
symptom string, and the /var/run/netns/ readability requirement.
- docs/healthchecks.md: new "Jitter" subsection explaining the +/-10%
scaling on every computed interval, and a "Probe timing while a
probe is in flight" subsection that explains why fast-interval alone
doesn't give fast fault detection against hanging backends (the
probe loop is synchronous, so each iteration is timeout +
fast-interval; the advice is to lower timeout, not fast-interval).
- docs/maglevd.8: description paragraph corrected (dropped the
per-backend stats claim and added a short note pointing at the LB
plugin forwarding-path bypass); new CAPABILITIES section between
SIGNALS and FILES covering both CAP_NET_RAW and CAP_SYS_ADMIN with
the drop-in-override hint.
- docs/maglevd-frontend.8: new SIGNALS section documenting the
explicit SIGHUP ignore (so a controlling-terminal disconnect doesn't
kill the daemon); description extended with paragraphs on the two
persistence cookies (maglev_scope, maglev_zippy_open) and on the
health-cascade icon + lb buckets column.
- docs/maglevc.1: left untouched — intentionally minimal and delegates
to docs/user-guide.md.
Lint (26 issues across 12 files, all errcheck / ineffassign / S1021):
- cmd/frontend/handlers.go: _, _ = fmt.Fprintf(...) for the SSE retry
hint and resync control-event writes.
- cmd/maglevc/commands.go: bulk-prefix every fmt.Fprintf(w, ...) with
_, _ =; also merged 'var watchEventsOptSlot *Node; ... = &Node{...}'
into a single := declaration (staticcheck S1021) — the self-
referencing pattern still works because the Children back-ref is
assigned on the next statement, not inside the struct literal.
- cmd/maglevc/complete.go: _, _ = fmt.Fprintf(ql.rl.Stderr(), ...)
for the banner and help writes; removed the ineffectual
'partial = ""' assignment (nothing downstream reads partial after
that branch, so setting it was dead code flagged by ineffassign).
- cmd/maglevc/shell.go: defer func() { _ = rl.Close() }() for the
readline instance; _, _ = fmt.Fprintf(rl.Stderr(), ...) for error
display in the REPL loop.
- cmd/maglevc/main.go: defer func() { _ = conn.Close() }() for the
gRPC client connection.
- internal/grpcapi/server_test.go: _ = conn.Close() in the test
teardown closure.
- internal/prober/http.go: _ = c.Close() in the TLS-handshake-failed
path; defer func() { _ = conn.Close() }() and defer func() { _ =
resp.Body.Close() }() for the two deferred cleanups.
- internal/prober/http_test.go: defer func() { _ = resp.Body.Close()
}() plus three _, _ = fmt.Fprint(w, ...) in the httptest.Server
handlers and _, _ = fmt.Sscanf(...) when parsing the test listener's
port.
- internal/prober/icmp.go: defer func() { _ = pc.Close() }() for the
ICMP packet conn.
- internal/prober/netns.go: defer func() { _ = origNs.Close() }(),
defer func() { _ = netns.Set(origNs) }(), defer func() { _ =
targetNs.Close() }() — also dropped a stray //nolint:errcheck that
was no longer needed once the closure wrapping handled the discard.
- internal/prober/tcp.go: _ = conn.Close() in the L4-only path,
_ = tlsConn.Close() in the failed and succeeded handshake branches,
_ = tlsConn.SetDeadline(...) (also dropped a //nolint:errcheck
previously covering it).
Iterative 'make lint' runs were needed because golangci-lint v2.x
caps same-linter reports per pass, so the first pass reported 21,
then 4, then 3, then 1, then 0. Final pass: 0 issues. make test is
green across every package, and make build produces all three
binaries cleanly.
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 thelbplugin binary API, and exposes everything over a gRPC API + Prometheus/metricsendpoint.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).
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_RAWfor ICMP health checks (raw sockets).CAP_SYS_ADMINwhenhealthchecker.netnsis set so probes cansetns(CLONE_NEWNET)into the dataplane namespace. Without it, every probe errors out withenter 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_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 shows every knob.
- docs/user-guide.md — flags, signals, and
maglevccommand 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