Match relayd backup activation to the primary health check

Bottom line: Review the health-check meaning before relying on a backup table. Keep a failed individual host and a completely failed primary table as different cases in the failover plan.

Source fact: what the authority says

The OPNsense relayd reference groups hosts into tables and allows a host to belong to more than one table. A table check determines whether a host group is ready, with examples ranging from ICMP to an HTTP URI and response-code check. A virtual server can use primary and backup tables; the backup is used when all primary-table hosts are down according to the configured check. Its server type distinguishes transparent layer-three redirection from layer-seven relay operation.

What the source does not establish

This article covers the documented table-check and backup-selection boundary. It does not provide an application availability guarantee, a universal probe design or permission to create a production failure to demonstrate failover.

Applicability questions

• What does the configured table check actually test?
• Which hosts belong to the primary and backup tables?
• What should happen when one primary host fails versus all primary hosts?
• Which server type and application observation are required for this service?

DSE recommendation: controlled next steps

The following steps are DSE recommendations based on the cited source.

DSE recommends describing the intended failure in operational terms before choosing a probe. Ask the application owner whether a network response or a named HTTP response is the observation needed for this particular service. Document the selected check and expected healthy response without treating either example as a universal availability test.

Build a table-membership map that names every primary and backup host. Mark any host used in more than one table so the operator can explain the test population. Keep a single failed primary member and a fully unavailable primary table as separate proposed scenarios with separately written expectations.

Review the virtual server’s type and the relevant traffic path with the network owner. Select a harmless application transaction that can be observed independently of the health check. Avoid describing a successful probe as proof of every application dependency or promising an interruption duration that has not been measured.

Use an isolated relayd arrangement or an expressly approved maintenance exercise for failure testing. Name the person who may withdraw a test host and the condition for restoring it. Preserve the original table and check settings, and agree how the normal primary arrangement will be reconciled after the exercise.

Verification and evidence

Proposed verification: record the initial host-check states and perform the approved partial-primary case. Observe the selected destination and application transaction without assuming the backup table should activate. Then, only within the approved exercise, test the complete-primary-unavailable case and compare the actual selection with the documented condition.

Retain check results, table membership, timestamps and the independent application observations for both cases. Restore the intended host population and verify the resulting normal arrangement separately. Keep an unexpected probe result or connection failure as an unresolved finding rather than modifying the check merely to produce a green display.

Official references

• OPNsense — Relayd — official product documentation; confirm the installed release and configuration.

Source review completed October 30, 2026. Recheck the official documentation and deployment-specific applicability before a production change.