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.
306 lines
9.0 KiB
Groff
306 lines
9.0 KiB
Groff
.TH MAGLEVD\-FRONTEND 8 "April 2026" "vpp\-maglev" "System Administration"
|
|
.SH NAME
|
|
maglevd\-frontend \- web dashboard for one or more running maglevd instances
|
|
.SH SYNOPSIS
|
|
.B maglevd\-frontend
|
|
\fB\-server\fR \fIaddr\fR[,\fIaddr\fR...]
|
|
[\fB\-listen\fR \fIaddr\fR]
|
|
[\fB\-log\-level\fR \fIlevel\fR]
|
|
[\fB\-version\fR]
|
|
.SH DESCRIPTION
|
|
.B maglevd\-frontend
|
|
is a single\-binary web dashboard that connects to one or more running
|
|
.BR maglevd (8)
|
|
instances over gRPC and renders a live view of frontends, backends,
|
|
health checks, and VPP load\-balancer state. The SolidJS SPA is
|
|
embedded into the Go binary via
|
|
.BR embed.FS ,
|
|
so no runtime file dependencies are required; pointing the binary at
|
|
one or more maglevds with
|
|
.B \-server
|
|
is enough to serve the dashboard.
|
|
.PP
|
|
For each configured maglevd,
|
|
.B maglevd\-frontend
|
|
maintains:
|
|
.IP \(bu 2
|
|
A long\-lived
|
|
.B WatchEvents
|
|
gRPC stream subscribed at
|
|
.BR log_level=debug ,
|
|
which delivers backend transitions, frontend transitions, per\-probe
|
|
log records (used to drive the live probe heartbeat), and per\-mutation
|
|
VPP LB sync records so the UI reflects every dataplane change in real
|
|
time.
|
|
.IP \(bu 2
|
|
A 30\-second refresh loop that re\-fetches
|
|
.BR ListFrontends / GetFrontend ,
|
|
.BR ListBackends / GetBackend ,
|
|
.BR ListHealthChecks / GetHealthCheck ,
|
|
and
|
|
.B GetVPPInfo
|
|
as a safety net against missed events.
|
|
.IP \(bu 2
|
|
A 5\-second health probe that surfaces maglevd connection drops
|
|
quickly and flips the scope\-selector indicator dot red.
|
|
.PP
|
|
Browsers connect to
|
|
.B maglevd\-frontend
|
|
over HTTP. State is hydrated once via REST and then kept live via a
|
|
Server\-Sent Events stream. Short SSE disconnects (nginx idle timeout,
|
|
wifi flap, laptop wake) are handled silently via a 30\-second replay
|
|
ring buffer; longer outages fall through to a full refetch. The SPA
|
|
is stateless on reload so refreshing the page at any time returns a
|
|
consistent view.
|
|
.PP
|
|
The frontend exposes two base paths:
|
|
.B /view/
|
|
is the read\-only dashboard and serves without authentication;
|
|
.B /admin/
|
|
is a basic\-auth\-protected variant of the same SPA that exposes
|
|
lifecycle mutations (pause / resume / enable / disable a backend,
|
|
set configured weight within a pool). The admin surface is only
|
|
mounted when both
|
|
.B MAGLEV_FRONTEND_USER
|
|
and
|
|
.B MAGLEV_FRONTEND_PASSWORD
|
|
are set to non\-empty values at startup; otherwise
|
|
.B /admin/
|
|
returns 404 and the SPA hides the admin\-toggle button entirely.
|
|
.PP
|
|
Per\-user persistent state lives in two cookies:
|
|
.B maglev_scope
|
|
remembers which maglevd the user was last looking at (hydrated on
|
|
page load and reconciled against the fetched server list, so a
|
|
removed/renamed maglevd falls through cleanly instead of leaving a
|
|
ghost selection), and
|
|
.B maglev_zippy_open
|
|
remembers which collapsible cards are open, scoped per\-maglevd so
|
|
opening a frontend card on one server doesn't affect the equivalent
|
|
card on another. Both are
|
|
.BR "Path=/; Max-Age=1y; SameSite=Lax" ,
|
|
are best\-effort (a missing or corrupt value just falls back to
|
|
"everything closed" / "first maglevd"), and hold no sensitive data.
|
|
.PP
|
|
The SPA shows a health\-cascade icon next to every frontend name:
|
|
.B \(OK
|
|
for fully healthy, a double\-bang for a control\-plane vs dataplane
|
|
disagreement (eff_weight > 0 but zero VPP buckets), an exclamation
|
|
mark for a fully\-drained primary pool, a warning triangle for any
|
|
backend not in
|
|
.B up
|
|
state, and a question mark as a fallthrough for logic bugs in the
|
|
cascade. The
|
|
.B "lb buckets"
|
|
column on each backend row reports VPP's Maglev hash table share
|
|
for that AS, debounced to at most one
|
|
.B GetVPPLBState
|
|
fetch per second per maglevd and refreshed live on every backend
|
|
transition or weight edit.
|
|
.SH OPTIONS
|
|
Each flag may also be supplied via an environment variable (shown in
|
|
parentheses); the flag takes precedence when both are set. All env
|
|
vars are prefixed with
|
|
.B MAGLEV_FRONTEND_
|
|
so a single env file can be shared with
|
|
.BR maglevd (8)
|
|
without variables leaking across processes.
|
|
.TP
|
|
.BI \-server " addr[,addr...]"
|
|
Comma\-separated list of maglevd gRPC addresses. Required. Each
|
|
entry is in
|
|
.I host:port
|
|
form; a short display name is derived from the hostname label (for
|
|
IP literals the full address is used).
|
|
.RI "(env: " MAGLEV_FRONTEND_SERVERS )
|
|
.TP
|
|
.BI \-listen " addr"
|
|
HTTP bind address for the dashboard.
|
|
.RI "(default: " :8080 "; env: " MAGLEV_FRONTEND_LISTEN )
|
|
.TP
|
|
.BI \-log\-level " level"
|
|
Structured\-log verbosity:
|
|
.BR debug ,
|
|
.BR info ,
|
|
.BR warn ,
|
|
or
|
|
.BR error .
|
|
Affects
|
|
.B maglevd\-frontend 's
|
|
own logs, not the log level it subscribes to on the upstream maglevd
|
|
(which is always
|
|
.BR debug
|
|
so the probe heartbeat can animate).
|
|
.RI "(default: " info "; env: " MAGLEV_FRONTEND_LOG_LEVEL )
|
|
.TP
|
|
.B \-version
|
|
Print version, commit hash, and build date, then exit.
|
|
.SH HTTP ENDPOINTS
|
|
.TP
|
|
.I /view/
|
|
Static SPA (HTML, JS, CSS, assets). Read\-only.
|
|
.TP
|
|
.I /view/api/maglevds
|
|
JSON array describing the configured maglevds and their current
|
|
connection status.
|
|
.TP
|
|
.I /view/api/state
|
|
Full JSON state snapshot for every maglevd.
|
|
.TP
|
|
.I /view/api/state/{name}
|
|
Full JSON state snapshot for a single maglevd.
|
|
.TP
|
|
.I /view/api/version
|
|
Build version, commit hash, and build date, plus an
|
|
.B admin_enabled
|
|
flag the SPA uses to decide whether to show the admin toggle.
|
|
.TP
|
|
.I /view/api/events
|
|
Server\-Sent Events stream. Long\-lived HTTP/1.1 chunked response
|
|
fanning out log, backend, frontend, maglevd\-status, and vpp\-status
|
|
events to every connected browser. Supports
|
|
.B Last\-Event\-ID
|
|
replay from a 30\-second / 2000\-event ring buffer, plus a
|
|
.B resync
|
|
control event emitted after every maglevd config reload so the SPA
|
|
re\-hydrates from the now\-fresh server cache.
|
|
.TP
|
|
.I /healthz
|
|
Liveness endpoint; returns 200 if the HTTP server is up.
|
|
.TP
|
|
.I /admin/
|
|
SPA shell served behind basic auth when
|
|
.B MAGLEV_FRONTEND_USER
|
|
and
|
|
.B MAGLEV_FRONTEND_PASSWORD
|
|
are configured. Returns 404 when they're not.
|
|
.TP
|
|
.I "/admin/api/{maglevd}/backend/{name}/{action}"
|
|
Backend lifecycle POST. Action is
|
|
.BR pause ", " resume ", " enable ", or " disable .
|
|
Returns the fresh backend snapshot as JSON.
|
|
.TP
|
|
.I "/admin/api/{maglevd}/frontend/{fe}/pool/{pool}/backend/{name}/weight"
|
|
Weight change POST. Body is
|
|
.B {"weight": 0\-100, "flush": bool} .
|
|
Returns the fresh frontend snapshot as JSON.
|
|
.SH SIGNALS
|
|
.TP
|
|
.BR SIGTERM ", " SIGINT
|
|
Graceful shutdown: active gRPC streams are closed, the HTTP server
|
|
drains, then the process exits.
|
|
.TP
|
|
.B SIGHUP
|
|
Explicitly ignored. A controlling\-terminal disconnect (closing the
|
|
SSH session the dashboard was started from, for example) would
|
|
otherwise deliver
|
|
.B SIGHUP
|
|
under Go's default handler and terminate the process with
|
|
.BR Hangup .
|
|
Since
|
|
.B maglevd\-frontend
|
|
has no config file beyond its command\-line flags there is nothing
|
|
meaningful to
|
|
.I reload
|
|
on
|
|
.BR SIGHUP ,
|
|
and inheriting the default "exit on hangup" semantics is the wrong
|
|
behaviour for a long\-running network daemon. Use
|
|
.B SIGTERM
|
|
for clean shutdown instead.
|
|
.SH REVERSE PROXY NOTES
|
|
The SSE stream has a handful of operational requirements that every
|
|
reverse proxy must satisfy:
|
|
.IP \(bu 2
|
|
Disable buffering on the events endpoint. Nginx honours
|
|
.B X\-Accel\-Buffering: no
|
|
(sent by
|
|
.BR maglevd\-frontend )
|
|
but a global
|
|
.B proxy_buffering off;
|
|
in the server block is the more robust answer.
|
|
.IP \(bu 2
|
|
Raise
|
|
.B proxy_read_timeout
|
|
to at least
|
|
.BR 300s
|
|
so the stream isn't torn down between the 15\-second
|
|
.B :\ ping
|
|
heartbeats that
|
|
.B maglevd\-frontend
|
|
sends.
|
|
.IP \(bu 2
|
|
Do not wrap the events endpoint in a gzip/brotli middleware — response
|
|
compression buffers until its window fills and destroys the live\-stream
|
|
property.
|
|
.SH ENVIRONMENT
|
|
All environment variables are prefixed with
|
|
.B MAGLEV_FRONTEND_
|
|
so this daemon can share
|
|
.I /etc/default/vpp-maglev
|
|
(or a container env file) with
|
|
.BR maglevd (8)
|
|
— whose env vars use only the shorter
|
|
.B MAGLEV_
|
|
prefix — without cross\-contamination.
|
|
.TP
|
|
.B MAGLEV_FRONTEND_SERVERS
|
|
Default value of
|
|
.BR \-server .
|
|
.TP
|
|
.B MAGLEV_FRONTEND_LISTEN
|
|
Default value of
|
|
.BR \-listen .
|
|
.TP
|
|
.B MAGLEV_FRONTEND_LOG_LEVEL
|
|
Default value of
|
|
.BR \-log\-level .
|
|
.TP
|
|
.B MAGLEV_FRONTEND_USER
|
|
HTTP basic\-auth username for
|
|
.BR /admin/ .
|
|
When set together with
|
|
.B MAGLEV_FRONTEND_PASSWORD
|
|
the admin surface is enabled; when either is missing or empty the
|
|
admin surface is hidden entirely (the SPA doesn't render the admin
|
|
toggle button and
|
|
.B /admin/
|
|
itself returns 404).
|
|
.TP
|
|
.B MAGLEV_FRONTEND_PASSWORD
|
|
HTTP basic\-auth password for
|
|
.BR /admin/ .
|
|
See
|
|
.B MAGLEV_FRONTEND_USER
|
|
above.
|
|
.TP
|
|
.B MAGLEV_FRONTEND_ARGS
|
|
Extra command\-line arguments picked up by the systemd unit's
|
|
.B ExecStart
|
|
line. Not read directly by the process — the unit expands it before
|
|
exec\-ing the binary.
|
|
.SH FILES
|
|
.TP
|
|
.I /etc/default/vpp-maglev
|
|
Environment file sourced by the systemd unit before starting
|
|
.BR maglevd\-frontend .
|
|
The same file is shared with
|
|
.BR maglevd (8);
|
|
the
|
|
.B MAGLEV_FRONTEND_ARGS
|
|
variable there is passed on the command line to
|
|
.BR maglevd\-frontend ,
|
|
and
|
|
.B MAGLEV_FRONTEND_USER / MAGLEV_FRONTEND_PASSWORD
|
|
are read from the process environment.
|
|
.SH SEE ALSO
|
|
.BR maglevd (8),
|
|
.BR maglevc (1)
|
|
.SH "FULL DOCUMENTATION"
|
|
.PP
|
|
.RS
|
|
https://git.ipng.ch/ipng/vpp-maglev/docs/user-guide.md
|
|
.RE
|
|
.SH AUTHOR
|
|
Pim van Pelt <pim@ipng.ch>
|