.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
stats\-segment counters are exposed via a gRPC API (and scraped
into Prometheus when the
.B /metrics
endpoint is enabled). Per\-backend packet counters are intentionally
not exposed: VPP's LB plugin forwards by writing
.B adj_index[VLIB_TX]
directly and bypassing
.BR ip4_lookup_inline " / " ip6_lookup_inline ,
which is the only path that increments
.BR /net/route/to ,
so the backend's FIB entry stats index never ticks for LB\-forwarded
traffic.
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 CAPABILITIES
.TP
.B CAP_NET_RAW
Required when any health check uses
.BR "type: icmp" .
Raw sockets for ICMP echo. TCP and HTTP(S) checks use normal TCP
sockets and need no special capability.
.TP
.B CAP_SYS_ADMIN
Required when the
.B healthchecker.netns
field is set in the YAML configuration. The probe loop calls
.BR setns (2)
with
.B CLONE_NEWNET
to enter the target network namespace before each probe; the
kernel only permits that to processes holding
.B CAP_SYS_ADMIN
in the target namespace's user namespace. Without it, every probe
fails with
.B enter netns "<name>": operation not permitted
and every backend flips to
.B down
on its first probe. Omit the capability when the deployment doesn't
use namespace\-scoped health checks \(em the Debian systemd unit
ships with both
.B CAP_NET_RAW
and
.B CAP_SYS_ADMIN
in its
.B AmbientCapabilities
and
.B CapabilityBoundingSet
by default, and operators can drop
.B CAP_SYS_ADMIN
via a drop\-in override if they prefer the narrower surface.
.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>