RTFM · Healthchecks
lb.saphira.http3: a real HTTP/3 transaction, or nothing
The strictest web check in the library: a genuine HTTP/3 request over QUIC with TLS 1.3 and the h3 ALPN, and absolutely no fallback. If HTTP/3 is broken, this check says so even when TCP and TLS on 443 are fine.
What it proves
The complete HTTP/3 stack: QUIC handshake, TLS 1.3 with the h3 application protocol, an HTTP/3 request, and a response inside the status class you accept. The package rule in its purest form, named check = named capability, means there is no degradation: http3 never quietly becomes the quic listener probe, and never becomes TCP.
How it works
curl --http3-only does the transaction: if the curl build on your director lacks HTTP/3 support the check fails honestly, which is itself the right verdict for a director that cannot verify HTTP/3. Status mode matches the code against the class regex; body mode is not offered here because HTTP/3 responses are validated by curl end-to-end.
Configuration
| Variable | Default | Meaning |
|---|---|---|
| LB_SAPHIRA_HTTP3_PATH | / | Path to request |
| LB_SAPHIRA_HTTP3_HOST | - | Host: header override (drives SNI too) |
| LB_SAPHIRA_HTTP_OK | ^(2|3)[0-9][0-9]$ | Status-class regex |
| LB_SAPHIRA_TIMEOUT | 3 | Transaction deadline |
| (target port) | $4, else 443 | The QUIC/HTTPS port |
Wiring it up
# ldirectord.cf - HTTP/3 edge
virtual = [2001:db8:10::10]:443
protocol = udp
scheduler = wlc
real = [2001:db8:20::11]:443 gate 1
checktype = external
checkcommand = "/var/lib/lb/saphira/lb.saphira.http3"A common production shape: balance HTTP/3 with the udp virtual service and HTTP/2 with a tcp virtual service; same backends, two verdicts, neither hiding the other.
Run it by hand
/var/lib/lb/saphira/lb.saphira.http3 edge 443 2001:db8:20::11 443
echo $?
# 0 = real HTTP/3 transaction inside the status class
# 1 = QUIC/h3 handshake failed, or status outside the classFailure modes
- curl fell back to nothing and failed; exactly the intent: h3 broken while TCP works is a finding, not a false alarm
- Status outside the class: the h3 path works but the application answered badly
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.