RTFM · Healthchecks
lb.saphira.quic: is a QUIC listener really there?
QUIC lives on UDP, where "port open" means nothing. This check uses the protocol's own rule: send a packet with an unsupported version, and a genuine QUIC server must answer with Version Negotiation. No answer, no listener.
What it proves
The QUIC transport listener, per RFC 9000 §6: a long-header packet with an unsupported version is answered by a Version Negotiation packet; a long header whose version field is 0. That is a MUST for every QUIC server, so the check exploits the protocol itself rather than guessing with application payloads.
This proves the transport listener, not a working HTTP/3 service. The named capability for a real HTTP/3 transaction is the http3 check, and http3 never falls back to this one.
How it works
The probe engine sends one crafted long-header packet (random connection IDs, version 0x0A0A0A0A) and requires a reply whose long-header bit is set and whose version field is zero. Dual-stack: $3 may be IPv4 or IPv6.
Configuration
| Variable | Default | Meaning |
|---|---|---|
| LB_SAPHIRA_TIMEOUT | 3 | Handshake deadline |
| (target port) | $4, else 443 | Any UDP port a QUIC endpoint listens on |
Wiring it up
# ldirectord.cf - QUIC edge pool
virtual = [2001:db8:10::10]:443
protocol = udp
scheduler = rr
real = [2001:db8:20::11]:443 gate 1
checktype = external
checkcommand = "/var/lib/lb/saphira/lb.saphira.quic"Run it by hand
/var/lib/lb/saphira/lb.saphira.quic quic-edge 443 2001:db8:20::11 443
echo $?
# 0 = Version Negotiation returned
# 1 = silence (firewalled UDP or no QUIC endpoint) or a malformed replyFailure modes
- Silence: UDP blocked somewhere on the path, or the listener died: indistinguishable by design, both are unhealthy
- Short/malformed reply: something UDP answered that is not a QUIC endpoint
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.