RTFM · Healthchecks
lb.saphira.sip: does the phone system answer OPTIONS?
SIP has its own are-you-there message: OPTIONS. The check sends one, uses the virtual source address your balancer hands it, and accepts any live response from ringing to OK, because a PBX that answers a probe is a PBX that can take a call.
What it proves
A SIP transaction: OPTIONS request out, SIP/2.0 response back with a status in the 1xx/2xx range (100 Trying counts; a server that answers a probe is alive even when it is busy). LB_SAPHIRA_SIP_OK can cap the maximum healthy status for sites where only a full 200 OK should count.
How it works
The probe engine builds a standards-shaped OPTIONS: Via and From carry the virtual source ($5) when the caller supplied one, which is exactly what a balancer behind NAT needs for the reply to find its way home; plus a random branch/tag/Call-ID per probe. Transport is UDP by default; LB_SAPHIRA_SIP_PROTO=tcp for TCP-only peers.
Configuration
| Variable | Default | Meaning |
|---|---|---|
| LB_SAPHIRA_SIP_PROTO | udp | udp or tcp |
| LB_SAPHIRA_SIP_OK | - | Cap the maximum healthy status (default: any 1xx/2xx) |
| LB_SAPHIRA_TIMEOUT | 3 | Transaction deadline |
| $5 (vsource) | - | Used in Via/From when the director supplies it |
| (target port) | $4, else 5060 | 5061 requires the TLS-first dialect |
Wiring it up
# ldirectord.cf - trunk pool
virtual = 203.0.113.10:5060
protocol = udp
scheduler = sh
real = 192.168.20.91:5060 gate 1
real = 192.168.20.92:5060 gate 1
checktype = external
checkcommand = "/var/lib/lb/saphira/lb.saphira.sip"sh (source hash) pins a handset's registration and its calls to one registrar; the affinity VoIP almost always wants.
Run it by hand
/var/lib/lb/saphira/lb.saphira.sip sip-pool 5060 192.168.20.91 5060
echo $?
# 0 = a 1xx/2xx SIP response arrived
# 1 = no response, non-SIP garbage, or status above the capFailure modes
- Timeout on UDP: the classic NAT return-path problem: pass $5 or configure the per-service vsource so replies route back
- 4xx/5xx above the cap: the registrar answered but is unhappy: set LB_SAPHIRA_SIP_OK to your policy
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.