.TH MAGLEV\-FRONTEND 8 "April 2026" "vpp\-maglev" "System Administration"
.SH NAME
maglev\-frontend \- web dashboard for one or more running maglevd instances
.SH SYNOPSIS
.B maglev\-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 maglev\-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 maglev\-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 maglev\-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.
.SH OPTIONS
Each flag may also be supplied via an environment variable (shown in
parentheses); the flag takes precedence.
.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_SERVERS )
.TP
.BI \-listen " addr"
HTTP bind address for the dashboard.
.RI "(default: " :8080 "; env: " MAGLEV_LISTEN )
.TP
.BI \-log\-level " level"
Structured\-log verbosity:
.BR debug ,
.BR info ,
.BR warn ,
or
.BR error .
Affects
.B maglev\-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_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).
.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.
.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.
.TP
.I /healthz
Liveness endpoint; returns 200 if the HTTP server is up.
.TP
.I /admin/
Placeholder for a future basic\-auth mutation surface. Currently
returns
.B 501 Not Implemented .
.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 maglev\-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 maglev\-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
.TP
.B MAGLEV_SERVERS
Default value of
.BR \-server .
.TP
.B MAGLEV_LISTEN
Default value of
.BR \-listen .
.TP
.B MAGLEV_LOG_LEVEL
Default value of
.BR \-log\-level .
.SH FILES
.TP
.I /etc/default/vpp-maglev
Environment file sourced by the systemd unit before starting
.BR maglev\-frontend .
The same file is shared with
.BR maglevd (8);
the
.B MAGLEV_FRONTEND_ARGS
variable there is passed on the command line to
.B maglev\-frontend .
.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>