Pim van Pelt
177d81cca1
vpp-maglevd ships maglevd, maglevd-frontend, both systemd units, and the config conffiles. vpp-maglev ships maglevc and maglevt as pure client tools so jump hosts and workstations can install them without pulling in the daemon. pkg-deb now emits four .debs per release (2 packages x 2 archs); build-deb.sh takes a package-name argument and dispatches accordingly.
142 lines
4.1 KiB
Groff
142 lines
4.1 KiB
Groff
.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>
|