Split Debian package into vpp-maglevd + vpp-maglev; add maglevt.1 manpage
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.
This commit is contained in:
141
docs/maglevt.1
Normal file
141
docs/maglevt.1
Normal file
@@ -0,0 +1,141 @@
|
||||
.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>
|
||||
Reference in New Issue
Block a user