Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help

       gdnsd-plugin-metafo - gdnsd plugin for address meta-failover

       Minimal example gdnsd config file using this plugin:

	 plugins => {
	   metafo => {
	     resources => {
	       prod_www	=> {
		 datacenters =>	[ dc-01, dc-02,	dc-03 ]
		 dcmap => {
		   dc-01 =>
		   dc-02 => { lb01 =>, lb02 => }
		   dc-03 => [,, ]
	       prod_foo	=> {
		 datacenters =>	[ dc-01, dc-02,	dc-bk ]
		 dcmap => {
		   dc-01 => { lb01 =>, lb02 => }
		   dc-02 => [,, ]
		   dc-bk =>

       Example zonefile	RRs in zone

	 www	  600 DYNA metafo!prod_www
	 www-dc01 600 DYNA metafo!prod_www/dc-01
	 foo	  700 DYNC metafo!prod_foo

       gdnsd-plugin-metafo is a	meta-plugin.  It does static-ordered address
       failover	between	multiple "datacenters" (which may or may not
       correspond with real datacenters, it's just a convenient	label).	 Each
       datacenter is defined in	terms of other plugins such as "multifo",
       "weighted", etc,	as described below.

       The top level of	the metafo plugin's configuration (i.e.	"plugins => {
       metafo => { ... } }") supports only one fixed, required key,
       "resources", whose value	must be	a hash.	 The contents of "resources"
       is a key	per named resource, with the value defining that resource.

       Any other keys present at the top level will be inherited down inside
       of each per-resource hash inside	the "resources"	stanza,	acting as per-
       resource	defaults for anything not defined explicitly there, as
       explained below.

       All keys	within the resources stanza represent named resources, which
       can be referenced by "DYNA" RRs in zonefiles (e.g. "www DYNA
       metafo!resource_name").	Each resource's	value must be a	key-value hash
       configuring the resource	itself.	 Lightweight structural	example:

	 plugins => {
	   metafo => {
	     resources => { resA => { ... }, resB => { ... } }

       Within a	resource, there	are only three specifically meaningful keys:

       "datacenters = [	A, B, C, ... ]"
	   Array of datacenter names, required.	 This is the set of datacenter
	   name	labels used for	this resource, in the order they will be
	   checked for failover.

       "dcmap =	{ ... }"
	   Hash, required.  The	"dcmap"	is a key-value hash where the keys
	   must	be exactly the list of datacenters defined in this resource's
	   "datacenters" list, and the values defined the address
	   configuration of each datacenter.  Another minimal structural
	   example down	to this	level:

	     plugins =>	{
	       metafo => {
		 resources => {
		   resA	=> {
		     datacenters => [ dc01, dc02 ],
		     dcmap => {
		       dc01 => ???
		       dc02 => ???

	   There are several forms the per-datacenter values ("???" above) can
	   take, documented in the next	section.

       "skip_first = true"
	   If this boolean configuration flag is set, the resolver code	will
	   skip	the first datacenter when resolving this resource.  This is
	   mostly useful in the	context	of the geoip plugin, and is discussed
	   in more detail there.

       Any keys	other than "datacenters" and "dcmap" at	the per-resource level
       serve as	inherited defaults for each per-datacenter configuration
       inside of the "dcmap".

       The value of the	datacenters within the "dcmap" section of a resource
       can take	several	forms.	It is important	to understand that for the
       most part, plugin_metafo	does not deal with this	level of results
       itself, but instead delegates the work at this scope to other plugins.
       These sub-plugins, in turn, also	notify metafo of complete failure at
       their level, which is the information metafo uses to know to fail over
       to the next datacenter in the list.

       The most	direct and obvious way to do this is with a direct reference
       of the form "%plugin!resource", as shown	here:

	 plugins => {
	   metafo => {
	     resources => {
	       resA => {
		 datacenters =>	[ dc1, dc2 ],
		 dcmap => {
		   dc1 => %multifo!res_mfo1
		   dc2 => %multifo!res_mfo2
	   multifo => {
	     res_mfo1 => { lb01	=>, lb02 =>	}
	     res_mfo2 => { lb01	=>,	lb02 => }

       However,	to make	life simpler in	the simple cases, plugin_metafo	can
       synthesize the lower-level plugin's configuration from a	hash, like so:

	 plugins => {
	   metafo => {
	     resources => {
	       resA => {
		 datacenters =>	[ dc1, dc2 ],
		 dcmap => {
		   dc1 => { plugin => multifo, lb01 =>, lb02 => }
		   dc2 => { lb01 =>, lb02 => }
		   # the above are effectively treated as:
		   # dc1 => %multifo!metafo_resA_dc1
		   # dc2 => %multifo!metafo_resA_dc2
	   # below does	not exist in your configfile, but is what plugin_metafo
	   #   synthesizes to support the above:
	   #multifo => {
	   #  metafo_resA_dc1 => { lb01	=>, lb02 =>	}
	   #  metafo_resA_dc2 => { lb01	=>,	lb02 => }

       Within a	hash like the above, the special key "plugin" will be stripped
       out internally and used to name the plugin we synthesize	the config
       for.  "plugin" defaults to "multifo" if not specified.  Note that
       "plugin"	could also be specified	at the resource	level (just inside of
       the "resA" stanza) to change the	default	for all	"dcmap"	entries	in one
       resource, and could also	be specified at	the outer-most scope (just
       inside the "metafo" stanza) to change the default for all resources.

       The defaulted-down "plugin" is also the default for the direct-
       reference "%plugin!resource" form discussed earlier.  With the correct
       default plugin name, it can be shortened	to just	"!resource".

       The same	sort of	key-value inheritance scheme (top-level	-> per-
       resource	level -> per-datacenter	level) can also	be used	for any	other
       parameter in synthesized	resource configurations	specific to the	per-
       datacenter plugin(s) you	are using.  A common example would be the
       "service_types" parameter that most plugins which support monitored
       address results have.  Note that	these other values (e.g.
       service_types) would only apply to synthesized resources, not to
       direct-references like "%multifo!foo", which must be configured
       entirely	separately within that plugin's	config.

       There are three other possible shortcut values for datacenters: a
       single direct address, an array of addresses, or	a single CNAME
       hostname.  If a single IP address or an array of	IP addresses are
       specified, plugin_metafo	will synthesize	a hash from them with the
       plugin forced to	"multifo" (since it cannot know	the syntax of hashes
       for all other plugins, which may	differ), and give them address labels
       1, 2, etc.

       If the value for	a datacenter is	a single CNAME hostname, no sub-plugin
       is used,	and that CNAME result is returned directly.  Note that any
       resource	with such an entry can only be used with "DYNC"	RRs, and not
       "DYNA" RRs (as is the case if any subplugin's configuration is capable
       of returning CNAME data).

       A much more complete example, showing off most of the features above:

	 plugins => {
	   metafo => {
	     plugin => multifo # change	default	for all	resources
	     service_types => [	bar ] #	default	service_types for synthesized below
	     resources => {
	       resA => {
		 plugin	=> multifo # change default for	this resource
		 service_types => [foo,	bar] # services	types for synthesized below:
		 datacenters =>	[ dc1, dc2, dc3, dc4, dc5, dc6,	dc7, dc8 ],
		 dcmap => {
		   dc1 => { plugin => multifo, lb01 =>, lb02 => }
		   dc2 => { lb01 =>, lb02 => }
		   dc3 => %simplefo!foo
		   dc4 => { plugin => simplefo,	primary	=>,	secondary => }
		   dc5 => !bar
		   dc6 =>
		   dc7 => [, ]
		   dc8 =>
	   # below, commented-out sections show	configuration synthesized
	   #   by plugin_metafo, whereas the rest are direct-references	that
	   #   had to be manually specified here:
	   multifo => {
	     # metafo_resA_dc1 => { lb01 =>, lb02 =>, service_types	=> [foo, bar] }
	     # metafo_resA_dc2 => { lb01 =>, lb02 =>, service_types => [foo, bar] }
	     bar => { asd =>, xyz => }
	     # metafo_resA_dc6 => { 1 =>, service_types => [foo, bar] }
	     # metafo_resA_dc7 => { 1 =>, 2	=>,	service_types => [foo, bar] }
	   simplefo => {
	     foo => { primary =>, secondary => }
	     # metafo_resA_dc4 => { primary =>, secondary =>, service_types => [foo, bar] }

       Note in the example above that "%multifo!bar" and "%simplefo!foo" would
       have had	their default "service_types = up" rather than the one
       specified at the	metafo level, because they were	not synthesized.  It
       would be	up to you to keep all of the service_types in sync when	using
       direct references.

       This plugin will	synthesize additional, per-datacenter resource names
       from your configuration.	 They are named	as "resname/dcname".  For
       example,	if you define a	metafo resource	named "prodwww"	with the
       datacenter list "[ pri, sec ]", the resource names "prodwww/pri"	and
       "prodwww/sec" will be sythesized	and can	be used	in zonefile records,

	 www-backup 300	DYNA metafo!prodwww/sec

       When used, these	per-datacenter synthetic resource names	cause a	given
       lookup to skip the normal failover process and directly return results
       from that particular datacenter.

       gdnsd.config(5),	gdnsd.zonefile(5), gdnsd(8)

       The gdnsd manual.

       Copyright (c) 2012 Brandon L Black <>

       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	<>.

gdnsd 3.7.0			  2021-11-06		GDNSD-PLUGIN-METAFO(8)


Want to link to this manual page? Use this URL:

home | help