External healthchecks: the Saphira check library

A normal health check is like checking whether a shop's door is unlocked. The Saphira checks walk in, buy something, and check the change: each one performs the exact transaction the service promises its customers. If that transaction works, the exit code is 0 and the balancer sends real traffic. If anything in the chain fails, the listener, the protocol, the database behind it, the check says so.

The package rule that makes this trustworthy: a named check is a named capability, with no silent fallbacks. https never degrades to "port open"; http3 never quietly becomes quic; dicom.echo never passes because a port answered. A pass verdict certifies exactly the promised transaction.

ldirectord, HAProxy's external-check and the ipvsadm toolchain all share one habit: they pass a fixed set of arguments to an external check and read its exit status. The Saphira checks accept that ABI as gospel; nothing beyond these five is ever assumed from a caller:

$1  virtual service / firewall mark     (e.g. 21, or the VIP)
$2  virtual port
$3  real server address                 ← the check target
$4  real server port
$5  virtual source where supplied       (optional)

# exit 0      healthy
# exit 1      unhealthy, the named capability failed
# exit 2      misconfiguration, fix the setup, do not flap the server

Everything beyond $5 is check-specific configuration, resolved in a fixed order so the same script works interactively, under ldirectord, and under HAProxy:

1. 1. Positional $6 and beyond

   Manual use and adapter wrappers, where the caller permits richer arguments; a convenience, never required.

2. 2. Environment variables

   LB_SAPHIRA_*; the highest-priority machine configuration, and the only place credentials may arrive.

3. 3. Check/service config file

   /etc/saphira/lb-healthchecks.d/<check>.conf for all services, or <check>/<service>.conf for one virtual service (the service token is $1 sanitized).

4. 4. Safe baked-in default

   What the check author chose when you have said nothing.

# /etc/saphira/lb-healthchecks.d/dicom.find.conf
LB_SAPHIRA_DICOM_PATIENT_ID=SAPHIRA-SYNTHETIC-HEALTHCHECK
LB_SAPHIRA_DICOM_MODALITY=CT
LB_SAPHIRA_DICOM_QUERY_LEVEL=PATIENT
LB_SAPHIRA_DICOM_AET=SAPHIRA-HC
LB_SAPHIRA_DICOM_AEC=MODALITY-SCP

# Per-service override (service token = sanitized $1):
#   /etc/saphira/lb-healthchecks.d/dicom.find/21.conf
# Format: KEY=VALUE lines, keys must match LB_SAPHIRA_[A-Z0-9_]+,
# '#' comments. Caller environment always wins over conf files.

Every check enforces a bounded timeout via LB_SAPHIRA_TIMEOUT (default 3 seconds); a check that hangs would otherwise hang the balancer's scheduler. All addresses resolve through getaddrinfo, so any check whose protocol permits IPv6 handles a v4 or v6 real server indifferently; raw-packet checks (gre, ipproto) are IPv4 in v1 and say so on their pages.

• Medical checks: DICOM, HL7 and FHIR explained
• The saphira-lb-probe engine reference

# ldirectord.cf
virtual = 21
    protocol = fwm
    scheduler = rr
    real = 192.168.20.21:0 gate 1
    checktype = external
    checkcommand = "/var/lib/lb/saphira/lb.saphira.dicom.echo"

# haproxy.cfg - external-check runs the same script with the
# same five arguments (drain-support requires HAProxy 2.2+ semantics)
global
    external-check

backend dicom_pool
    mode tcp
    option external-check
    external-check command "/var/lib/lb/saphira/lb.saphira.dicom.echo"
    server pacs1 192.168.20.21:104 check inter 5s fall 3 rise 2

Check-specific settings ride in the environment or the conf-file layer, not in the balancer config, which is exactly why one check serves both directors unchanged.