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.
137 lines
3.8 KiB
Groff
137 lines
3.8 KiB
Groff
.TH MAGLEVD 8 "April 2026" "vpp\-maglev" "System Administration"
|
|
.SH NAME
|
|
maglevd \- Maglev health\-checker daemon and VPP load\-balancer controller
|
|
.SH SYNOPSIS
|
|
.B maglevd
|
|
[\fB\-config\fR \fIfile\fR]
|
|
[\fB\-grpc\-addr\fR \fIaddr\fR]
|
|
[\fB\-log\-level\fR \fIlevel\fR]
|
|
[\fB\-reflection\fR[=\fIbool\fR]]
|
|
[\fB\-version\fR]
|
|
.SH DESCRIPTION
|
|
.B maglevd
|
|
has two responsibilities:
|
|
.IP \(bu 2
|
|
It monitors backends with active health checks (HTTP, TCP, ICMP) and
|
|
aggregates the results into a state machine per backend. Probe
|
|
intervals adapt automatically: a faster interval is used while a
|
|
backend is degraded, and a slower one once it has been continuously
|
|
down. Operators can also
|
|
.B pause/resume
|
|
or
|
|
.B disable/enable
|
|
a backend out of band.
|
|
.IP \(bu 2
|
|
It programs the VPP dataplane via the
|
|
.B lb
|
|
(load\-balancer) plugin. Each frontend in the config becomes a VPP
|
|
load\-balancer VIP; each healthy backend becomes an application server
|
|
under its frontend's VIPs. State transitions drive
|
|
application\-server weight updates over the VPP binary API so that
|
|
unhealthy backends stop receiving new flows. Drift between the
|
|
running config and VPP's view is reconciled periodically
|
|
.RB ( maglev.vpp.lb.sync-interval ,
|
|
default 30s), on
|
|
.B SIGHUP
|
|
reloads, and on operator request via
|
|
.BR maglevc .
|
|
.PP
|
|
The aggregated backend state, VPP dataplane state, and per\-VIP /
|
|
per\-backend stats\-segment counters are exposed via a gRPC API (and
|
|
scraped into Prometheus when the
|
|
.B /metrics
|
|
endpoint is enabled).
|
|
See
|
|
.BR maglevc (1)
|
|
for the interactive CLI client.
|
|
.PP
|
|
Configuration is loaded from a YAML file. A running daemon reloads
|
|
its configuration when it receives
|
|
.BR SIGHUP .
|
|
.SH OPTIONS
|
|
Each flag may also be supplied via an environment variable (shown in
|
|
parentheses); the flag takes precedence.
|
|
.TP
|
|
.BI \-config " file"
|
|
Path to the YAML configuration file.
|
|
.RI "(default: " /etc/vpp-maglev/maglev.yaml "; env: " MAGLEV_CONFIG )
|
|
.TP
|
|
.BI \-grpc\-addr " addr"
|
|
TCP address on which the gRPC server listens.
|
|
.RI "(default: " :9090 "; env: " MAGLEV_GRPC_ADDR )
|
|
.TP
|
|
.BI \-log\-level " level"
|
|
Structured\-log verbosity:
|
|
.BR debug ,
|
|
.BR info ,
|
|
.BR warn ,
|
|
or
|
|
.BR error .
|
|
.RI "(default: " info "; env: " MAGLEV_LOG_LEVEL )
|
|
.TP
|
|
.B \-reflection
|
|
Enable gRPC server reflection so that clients such as
|
|
.BR grpcurl (1)
|
|
can introspect the API without access to the
|
|
.I .proto
|
|
file.
|
|
Enabled by default; pass
|
|
.B \-reflection=false
|
|
to disable.
|
|
.TP
|
|
.B \-version
|
|
Print version, commit hash, and build date, then exit.
|
|
.SH SIGNALS
|
|
.TP
|
|
.B SIGHUP
|
|
Reload the configuration file without restarting. New backends are
|
|
added, removed backends are stopped, and unchanged backend workers
|
|
keep running. After the reload, the VPP dataplane is reconciled so
|
|
added/removed frontends and application servers are programmed
|
|
immediately.
|
|
.TP
|
|
.BR SIGTERM ", " SIGINT
|
|
Gracefully shut down: drain active gRPC streams, then exit. VPP
|
|
dataplane state is left in place so that existing VIPs continue to
|
|
forward traffic during a restart.
|
|
.SH FILES
|
|
.TP
|
|
.I /etc/vpp-maglev/maglev.yaml
|
|
Default configuration file (YAML).
|
|
.TP
|
|
.I /etc/default/vpp-maglev
|
|
Environment file sourced by the systemd unit before starting
|
|
.BR maglevd .
|
|
.TP
|
|
.I /run/vpp/api.sock
|
|
VPP binary\-API socket
|
|
.BR maglevd
|
|
connects to when programming the
|
|
.B lb
|
|
plugin.
|
|
.TP
|
|
.I /run/vpp/stats.sock
|
|
VPP stats\-segment socket used to scrape per\-VIP and per\-backend
|
|
packet/byte counters.
|
|
.SH "FULL DOCUMENTATION"
|
|
This manpage documents only the invocation of
|
|
.BR maglevd .
|
|
For the configuration file reference (including the
|
|
.B maglev.vpp.lb
|
|
section controlling the VPP integration), the health\-check state
|
|
machine, and the full operational guide, see:
|
|
.PP
|
|
.RS
|
|
https://git.ipng.ch/ipng/vpp-maglev/docs/config-guide.md
|
|
.br
|
|
https://git.ipng.ch/ipng/vpp-maglev/docs/healthchecks.md
|
|
.br
|
|
https://git.ipng.ch/ipng/vpp-maglev/docs/user-guide.md
|
|
.RE
|
|
.SH SEE ALSO
|
|
.BR maglevc (1),
|
|
.BR maglevd\-frontend (8),
|
|
.BR vpp (8)
|
|
.SH AUTHOR
|
|
Pim van Pelt <pim@ipng.ch>
|