Skip to content

suspend_when_proxy_unhealthy

Since: Version 2026.09.22-a276d4a8

The functionality described in this section requires version 2026.09.22-a276d4a8 of KumoMTA, or a more recent version.

Optional table.

Automatically suspend this egress source for the specified duration when the configured proxy server appears unreachable. The following kinds of failure count toward this rule:

  • The proxy is unreachable, refuses the connection, or times out (ConnectError with is_proxy = true).
  • The proxy server itself reports a bind failure for the requested source address (ProxyBindError).

See ha_proxy_server and socks5_proxy_server for the configuration that selects the proxy.

While a source is suspended, pool selection skips it, which allows other sources in the pool to be used instead of delaying the message. If every source in a pool is suspended, messages assigned to that pool are delayed until the earliest suspension expires.

The configuration is a table with the following fields:

  • trigger - when to fire the rule. Defaults to 'Immediate' — a single matching failure trips the rule. Use { Threshold = "N/period" } (the same syntax used by TSA shaping rules) to tolerate transient noise: the rule fires only after N matching failures within the rolling window.
  • duration - how long the source stays suspended once the rule fires. Required.
suspend_when_proxy_unhealthy = {
  trigger = { Threshold = '3/5m' }, -- optional; defaults to Immediate
  duration = '10m',
}

Suspension is process-local — there is no cluster coordination.

Observability:

A transition into the suspended state is also logged at WARN; the auto-clear is logged at INFO.

See also suspend_when_unplumbed.

Examples

Tolerate a few transient proxy hiccups by requiring N failures within a rolling window before suspending. This is the typical configuration for proxy-backed sources, since proxies sometimes flap briefly without warranting the source being removed from pool selection.

kumo.on('get_egress_source', function(source_name)
  return kumo.make_egress_source {
    name = source_name,
    socks5_proxy_server = 'proxy.example.com:1080',
    socks5_proxy_source_address = '10.0.0.1',
    suspend_when_proxy_unhealthy = {
      trigger = { Threshold = '3/5m' },
      duration = '10m',
    },
  }
end)

If you're using the sources helper, you can define the same source using the following syntax:

[source."ip-1"]
socks5_proxy_server = "proxy.example.com:1080"
socks5_proxy_source_address = "10.0.0.1"
suspend_when_proxy_unhealthy = { trigger = { Threshold = "3/5m" }, duration = "10m" }

{
  "source": {
    "ip-1": {
      "socks5_proxy_server": "proxy.example.com:1080",
      "socks5_proxy_source_address": "10.0.0.1",
      "suspend_when_proxy_unhealthy": {
        "trigger": {
          "Threshold": "3/5m"
        },
        "duration": "10m"
      }
    }
  }
}

If your proxy infrastructure is intended to be rock-solid and a single failure indicates a real outage worth acting on immediately, omit trigger (defaults to 'Immediate') so the first matching failure trips the rule and removes the source from pool selection.

kumo.on('get_egress_source', function(source_name)
  return kumo.make_egress_source {
    name = source_name,
    socks5_proxy_server = 'proxy.example.com:1080',
    socks5_proxy_source_address = '10.0.0.1',
    suspend_when_proxy_unhealthy = {
      -- trigger defaults to 'Immediate'
      duration = '10m',
    },
  }
end)

Or, in the sources-helper TOML form:

[source."ip-1"]
socks5_proxy_server = "proxy.example.com:1080"
socks5_proxy_source_address = "10.0.0.1"
suspend_when_proxy_unhealthy = { duration = "10m" }

{
  "source": {
    "ip-1": {
      "socks5_proxy_server": "proxy.example.com:1080",
      "socks5_proxy_source_address": "10.0.0.1",
      "suspend_when_proxy_unhealthy": {
        "duration": "10m"
      }
    }
  }
}