.TH MAGLEVT 1 "April 2026" "vpp\-maglev" "User Commands"
.SH NAME
maglevt \- Maglev out\-of\-band VIP probe TUI
.SH SYNOPSIS
.B maglevt
[\fB\-config\fR \fIfile\fR]...
[\fB\-interval\fR \fIdur\fR]
[\fB\-timeout\fR \fIdur\fR]
[\fB\-host\fR \fIstr\fR]
[\fB\-uri\fR \fIpath\fR]
[\fB\-header\fR \fIname\fR]
[\fB\-insecure\fR[=\fIbool\fR]]
[\fB\-keepalive\fR]
[\fB\-filter\fR \fIregex\fR]
[\fB\-version\fR]
.SH DESCRIPTION
.B maglevt
is an out\-of\-band VIP probe TUI for
.B vpp\-maglev
deployments. It reads one or more
.B maglev.yaml
configuration files, enumerates the configured TCP/HTTP frontends, and
probes each one on a configurable HTTP path at a configurable interval.
It does not talk gRPC, does not depend on a running
.BR maglevd (8),
and reports its results as a live full\-screen TUI rather than to any
machine\-readable channel.
.PP
Typical uses:
.IP \(bu 2
Validate a
.B maglevd
restart end\-to\-end from a client perspective. The probe tally keeps
running independently of the control plane, so a brief dataplane blip
or a missed failover is visible directly in the TUI.
.IP \(bu 2
Debug pool failover. With keep\-alives off (the default), each probe
opens a fresh TCP connection and is reshuffled by VPP's Maglev hash,
so the response\-header tally visibly changes the moment a standby
pool takes over.
.IP \(bu 2
Sanity\-check VIP reachability across sites when the gRPC control
plane is unavailable or out of reach from the operator's machine.
.SH OPTIONS
.TP
.BI \-config " file"
Path to a
.B maglev.yaml
configuration file. The flag is repeatable and also accepts a
comma\-separated list. Frontends are unioned across all supplied files
and de\-duplicated by
.IR "(scheme, address, port)" ,
so the same VIP is never probed twice even when multiple files
reference it.
.RI "(default: " /etc/vpp-maglev/maglev.yaml )
.TP
.BI \-interval " dur"
Probe interval per VIP. Uniform
.B \(+-10%
jitter is applied per probe to prevent phase\-locking after a
restart.
.RI "(default: " 100ms )
.TP
.BI \-timeout " dur"
Per\-request timeout. Bounds a single probe attempt; the interval
bounds the time between the
.I start
of consecutive attempts.
.RI "(default: " 2s )
.TP
.BI \-host " str"
Override for the HTTP
.B Host
header. When unset,
.B maglevt
uses the VIP's address literal as the
.B Host
header.
.TP
.BI \-uri " path"
HTTP request path used in the
.B GET
request. The flag
.B \-path
is accepted as an alias.
.RI "(default: " /.well-known/ipng/healthz )
.TP
.BI \-header " name"
Response header whose value is extracted and tallied, so the TUI can
show which backend served each request.
.RI "(default: " X-IPng-Frontend )
.TP
.B \-insecure
Skip TLS certificate verification for HTTPS frontends.
.RI "(default: " true )
.TP
.BR \-keepalive ", " \-k
Enable HTTP keep\-alives. Off by default: every probe opens a fresh
connection, which is necessary for failover visibility because a
pinned keep\-alive would mask a Maglev reshuffle.
.RI "(default: " false )
.TP
.BI \-filter " regex"
Regular expression restricting which frontends are probed; only
frontends whose name matches are included.
.TP
.B \-version
Print version, commit hash, and build date, then exit.
.SH "USER INTERFACE"
The TUI is built with Bubble Tea and shows a deterministic grid: one
tile per VIP, with IPv6 tiles before IPv4 and HTTPS before HTTP so the
layout is stable across runs and across machines. Each tile carries a
rolling latency summary (min, max, average, and several percentiles),
running success and failure counts, and a tally of the configured
response\-header values seen from that VIP.
.PP
Press
.B d
to toggle reverse\-DNS resolution on the addresses shown in the tile
headers. Press
.B q
or Ctrl\-C to exit. There is no machine\-readable output; use the
Prometheus
.B /metrics
endpoint on
.BR maglevd (8)
when you need metrics.
.SH "FULL DOCUMENTATION"
This manpage documents only the invocation of
.BR maglevt .
For the full operational guide see the user guide at:
.PP
.RS
https://git.ipng.ch/ipng/vpp-maglev/docs/user-guide.md
.RE
.SH "SEE ALSO"
.BR maglevd (8),
.BR maglevc (1),
.BR maglevd\-frontend (8)
.SH AUTHOR
Pim van Pelt <pim@ipng.ch>