RTFM · Healthchecks

saphira-lb-probe: the raw probe engine

The single binary-style helper behind the protocol checks: fourteen raw and protocol probes with one CLI, one exit-code contract, and dual-stack addressing. Check scripts call it; you can call it directly when debugging.

Why an engine

DNS, RADIUS, MySQL, PostgreSQL, SIP, QUIC, GRE, LDAP; each protocol check needs the same plumbing: resolve an address (any family), open a socket of the right kind, respect the timeout, send crafted bytes, match a reply. saphira-lb-probe packages that plumbing once, and the lb.saphira.* shell checks remain thin, readable wrappers that map configuration onto CLI flags.

v1 is python3 by design: auditably simple, present on every Saphira install. The CLI contract is stable; a future compiled binary must implement the same interface and simply replaces this payload, with no check script or config change.

The probes

Probe catalogue (exit 0 healthy · 1 unhealthy · 2 missing configuration)
Probe	Proves
tcp	TCP transport reachability (connect)
udp	UDP listener probe: connected socket, ICMP-error discrimination
banner	TCP connect + read banner + regex expect
sendexpect	TCP or UDP send-expect: the raw protocol escape hatch
dns	DNS query over UDP or TCP, ID/QR/rcode verified
sip	SIP OPTIONS round-trip (UDP or TCP)
radius	RADIUS Status-Server (RFC 5997) or PAP Access-Request
mysql	MySQL initial handshake parse
postgres	PostgreSQL SSLRequest negotiation
redis	Redis inline PING (optional AUTH)
quic	QUIC Version Negotiation handshake (RFC 9000 §6)
gre	GRE encapsulated-packet loopback (two-party contract)
ipproto	Generic raw IP protocol primitive (probe/accept modes)
ldap	LDAP anonymous bind + rootDSE response

The CLI

Interface contract (stable)

saphira-lb-probe <probe> [options]

# the probes and their default ports
dns 53 · radius 1812 · mysql 3306 · postgres 5432
redis 6379 · quic 443 · ldap 389 · sip 5060

# options worth knowing
--host H            target (required)
--port N            default per probe
--timeout S         LB_SAPHIRA_TIMEOUT, default 3
--family any|4|6    force an address family
--send / --send-hex / --send-file
text / hex / file payload for sendexpect & udp
--expect RE         regex over the response (matched latin-1, DOTALL)
--expect-rcode N    dns expected RCODE (default 0 NOERROR)
--proto tcp|udp     sendexpect transport
--tcp               dns over TCP
--name / --qtype    dns question
--expect-status N   sip: cap the maximum healthy status
--vsource S         sip: virtual source for Via/From ($5)
--pap               radius: PAP Access-Request fallback
--require-ssl       postgres: demand the S answer
--inner-src/--inner-dst/--inner-port/--key   gre two-party contract
--raw-proto N       ipproto: IP protocol number
--mode probe|accept ipproto semantics

Credentials (RADIUS secret, Redis password, PAP password) are read from LB_SAPHIRA_* environment variables only and are never printed by the engine.

Using it directly

The engine as a debugging tool

# Is the DNS server actually answering for our zone?
saphira-lb-probe dns --host 192.168.20.53 --name pacs.internal --qtype 1
echo $?

# Will the QUIC front-end do Version Negotiation?
saphira-lb-probe quic --host 2001:db8:10::10 --port 443 --family 6

# A custom binary protocol nobody wrote a check for:
saphira-lb-probe sendexpect --proto tcp --host 10.0.0.9 --port 7777 \
  --send-hex '01 00 00 00' --expect '^ACK'

Prove it works: Engine and wrapper agree

For any check, the manual saphira-lb-probe invocation shown on the check's page and the lb.saphira.* script verdict always match; if they do not, you have found a configuration gap (usually exit 2) worth fixing before trusting the balancer.

Did we miss something?

If this page left something unanswered, found an error, or there is another subject you would like documented, tell us. Saphira’s documentation grows from real problems people need to solve.

Send feedback or request a new section →

Prefer not to do it yourself?

Everything needed to do the work yourself is documented here and remains free; we charge for human time, not for withholding knowledge. Sometimes the missing resource is simply time. The same people who build Saphira can provide paid professional help with implementation, migration, troubleshooting and administration.

Ask about professional support →