GDNSD-PLUGIN-MULTIFO(8)

📦

version 3.8.3 · 7 versions

3.8.3 · debian trixie, ubuntu questing (latest)
3.8.3 · alpine 3.24
3.8.3 · arch rolling
3.8.3 · ubuntu stonking
3.8.2 · ubuntu noble
3.8.1 · debian bookworm
3.8.3 · ubuntu resolute

💖 gdnsd-plugin-multifo — the `gdnsd-plugin-multifo(8)` era 💖

okay bestie, sit down, grab a boba, because we're about to talk about multi-address all-active failover groups and honestly? it's giving genius. this whole page is from the gdnsd manual, section 8, and it's about to be your new hyperfixation. 🦋

✨ NAME ✨

gdnsd-plugin-multifo — a gdnsd plugin for multi-address, all-active failover groups. no cap, that's literally the whole job. 💅

🌸 SYNOPSIS 🌸

here's a lil example plugin config, and yes you're gonna want to screenshot this:

plugins => {
  multifo => {
    up_thresh => 0.3
    service_types => up,
    v4www => {
      lb01 => 192.0.2.200,
      lb02 => 192.0.2.201,
      lb03 => 192.0.2.202,
    }
    v6smtp => {
      service_types => [ smtp ],
      up_thresh => 0.1,
      lb01_v6 => 2001:DB8::1,
      lb02_v6 => 2001:DB8::2,
      lb03_v6 => 2001:DB8::3,
    }
    pubwww => {
      up_thresh => 0.5
      service_types => corpwww_type
      addrs_v4 => [ 192.0.2.100, 192.0.2.101, 192.0.2.102 ]
      addrs_v6 => {
        service_types => [ up ],
        up_thresh => 0.7
        lb01_v6 => 2001:DB8::1,
        lb02_v6 => 2001:DB8::2,
        lb03_v6 => 2001:DB8::3,
      }
    }
  }
}

and now the zonefile RRs, because the vibes have to be complete:

web4 180 DYNA multifo!v4www
smtp 180 DYNA multifo!v6smtp
www 180 DYNA multifo!pubwww

🌈 DESCRIPTION 🌈

so gdnsd-plugin-multifo is designed to do multi-address all-active failover grouping. basically, for every resource name you set up, you hand it a labeled list of addresses. then multifo monitors those addresses according to service_types, and it answers DYNA address queries using the non-DOWN subset. 👑

and then — and this is the cute part — the core gdnsd code will round-robin rotate the records on the way out, exactly like it does for all address RR-sets. it's iconic, it's consistent, we love it. ✨

🎀 TOP-LEVEL PLUGIN CONFIG 🎀

at the top level of the plugin's config stanza, three special parameters get to hang out: up_thresh, service_types, and ignore_health. these set the default per-resource options of the same name for any resources that don't define them explicitly. so like, defaults are inherited, bestie, it's a whole family tree. 🌸

the rest of the hash entries at the top level? those are the names of the resources you define. each resource gets a configuration hash of its own, for holding resource-specific parameters and the actual address data. two jobs, one hash, main character energy. 💅

🦋 RESOURCE CONFIG 🦋

inside a resource you've got two basic options:

you can directly specify a set of label => address pairs that are all the same family (IPv4 or IPv6), or
you can use the sub-stanzas addrs_v4 and/or addrs_v6 to specify one or both families in the same resource.

the up_thresh, service_types, and ignore_health parameters are inherited through every level, and can be overridden at any level (yes, even per-address-family, go off):

up_thresh — floating point, default 0.5, range (0.0 - 1.0]. this configures the per-resource up_thresh threshold. more deets in UP THRESH down below. ⭐
service_types — array of strings, or a single string. default default. this sets the monitored service_types for this resource. if you give it an array of more than one, all of them will be monitored for each address, and the net monitored state will be the minimum (worst) of the set. check gdnsd.config(8) for more details on service_types. 📋
ignore_health — boolean, default false. if you set it to true, the health of individual addresses will not affect whether multifo adds them to the set of output addresses — but it will still be checked and used for the up_thresh calculation, which gets consumed by meta-plugins like geoip and metafo. those might use that info to fail over to a completely different datacenter as a result. sneaky but make it functional. 🙈

💜 SHORTCUT CONFIG 💜

okay so if you have no parameters (service_types, up_thresh, ignore_health) to configure in a given stanza — whether that's single-family direct resource config, or addrs_v[46] — and you don't care about the descriptive per-address labels used in monitoring, you can just replace the hash with an array of addresses. 🎉

the labels get generated for you as a series of integers starting with 1. so for example, these two are equivalent:

res1 => { addrs_v4 => [ 192.0.2.1, 192.0.2.2 ] }
res1 => { addrs_v4 => { 1 => 192.0.2.1, 2 => 192.0.2.2 } }

same thing, less typing, slay. 💅

🔥 OPERATIONAL MECHANICS 🔥

all of the addresses for all of the resources are monitored using the per-address-family inherited service_types you specified (and the default would be the static virtual monitor up).

when the core daemon requests a lookup for address records of a given family on one of this plugin's resources, it goes through essentially this process to determine the set of response addresses for that address family:

add all non-DOWN addresses to the result set.
if the set of non-DOWN addresses fail the up_thresh check, add all addresses to the result set as a fallback.
if any address is in the DOWN state, cut the zonefile-specified TTL in half.

bestie the TTL halving is real. one DOWN address and that TTL is getting a haircut. 😭

if ignore_health is true, all addresses are added to the result set regardless of health — but the up_thresh and TTL effects still happen, and the final resource-level state still reflects the overall state as it would without ignore_health. the drama continues either way. 🎭

this process is repeated independently for each of the IPv4 and IPv6 address subsets, in the case that a resource has both address families configured (the TTL is only cut in half once of course, we're not monsters). details on the up_thresh check follow:

👑 UP THRESH 👑

if there are not enough UP addresses to pass the threshold (per address family), then all addresses (of a given address family) will be returned as a fallback. all of them. the whole squad. 🫶

the threshold is implemented mathematically as in the following pseudo-code:

if(non_down >= ceil(thresh * total)) threshold_passed;

for example, if thresh is at the default value of 0.5, and there are 3 total IPv4 addresses, then 2 of them must be non-down to pass the threshold. the net result is that with the default threshold, the plugin will never return an isolated single address from a set of 3. it will either return all 3, or it will return 2/3 if a single address from the set has failed. no lonely single addresses here, they always have a buddy. 🥺

when the threshold check fails (and all addresses are returned) for either address family, resource-level total failure will also be signaled to any applicable upstream meta-plugins such as metafo or geoip. so everybody knows. 📢

general rules for the results of the up_thresh formula:

a threshold of 1.0 will only pass if all addresses are not-down. this is mostly pointless, you might as well not monitor anything and set up these addresses as a static set in a zonefile.
a threshold of 0.01 will pass even if only one address is alive and return just that one address, even if it's e.g. the only one left out of 40.
because a threshold of 0.0 is illegal, if all addresses are down the threshold will always fail, returning all addresses.

intermediate value examples: (threshold: non-down/total required to pass threshold):

0.1: 1/1 1/2 1/3 1/4 1/5 1/6 1/7 1/8 2/16
0.2: 1/1 1/2 1/3 1/4 1/5 2/6 2/7 2/8 4/16
0.3: 1/1 1/2 1/3 2/4 2/5 2/6 3/7 3/8 5/16
0.4: 1/1 1/2 2/3 2/4 2/5 3/6 3/7 4/8 7/16
0.5: 1/1 1/2 2/3 2/4 3/5 3/6 4/7 4/8 8/16
0.6: 1/1 2/2 2/3 3/4 3/5 4/6 5/7 5/8 10/16
0.7: 1/1 2/2 3/3 3/4 4/5 5/6 5/7 6/8 12/16
0.8: 1/1 2/2 3/3 4/4 4/5 5/6 6/7 7/8 13/16
0.9: 1/1 2/2 3/3 4/4 5/5 6/6 7/7 8/8 15/16

look at that math, it ate. 🔥

🌟 SEE ALSO 🌟

and obviously... The gdnsd manual. it's the source, iykyk. 📖

🎀 COPYRIGHT AND LICENSE 🎀

This file is part of gdnsd.

gdnsd is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

gdnsd is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with gdnsd. If not, see <http://www.gnu.org/licenses/>.

and that's the whole page, bestie!! this was gdnsd version 3.8.3, dated 2025-02-16, straight from the GDNSD-PLUGIN-MULTIFO(8) manual. go forth and fail over, all-active, all-iconic. mwah. 💖✨🎀🦋💅

📦 where this page comes from

debian trixie: gdnsd 3.8.3-2 · GPL-3.0-or-later
ubuntu questing: gdnsd 3.8.3-2
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-18: a language model's rewrite of the original, under its terms