gdnsd-plugin-weighted man page on Alpinelinux

Man page or keyword search:  
man Server   18016 pages
apropos Keyword Search (all sections)
Output format
Alpinelinux logo
[printable version]

GDNSD-PLUGIN-WEIGHTED(8)	     gdnsd	      GDNSD-PLUGIN-WEIGHTED(8)

NAME
       gdnsd-plugin-weighted - gdnsd plugin implementing "weighted" records

SYNOPSIS
       Example plugin config:

	 plugins => {
	   weighted => {
	     multi = false # default
	     service_types = none
	     up_thresh => 0.5 # default
	     corpwww => {
	       lb01 = [ lb01.example.com., 99 ]
	       lb02 = [ lb02.example.com., 15 ]
	       lb03 = [ lb03, 1 ]
	     }
	     frontwww6 => {
	       service_types = up
	       multi = true
	       wwwhost01 = [ 2001:db8::123, 4 ]
	       wwwhost02 = [ 2001:db8::456, 1 ]
	       wwwhost03 = [ 2001:db8::789, 2 ]
	     }
	     pubwww => {
	       service_types = [ web_check, foo ]
	       up_thresh => 0.01,
	       pubhost01 = [ 192.0.2.1, 44 ]
	       pubhost02 = [ 192.0.2.2, 11 ]
	       pubhost02 = [ 192.0.2.3, 11 ]
	       pubhost02 = [ 192.0.2.4, 11 ]
	     }
	     cdnwww => {
	       service_types = web_check
	       datacenter1 => {
		 d1-lb1 = [ 127.0.0.1, 2 ]
		 d1-lb2 = [ 127.0.0.2, 2 ]
	       }
	       datacenter2 => {
		 d2-lb1 = [ 127.0.0.3, 2 ]
		 d2-lb2 = [ 127.0.0.4, 2 ]
		 d2-lb3 = [ 127.0.0.5, 1 ]
	       }
	     }
	     mixed => {
	       multi => false,
	       addrs_v4 => {
		 lb1 = [ 127.0.0.3, 2 ]
		 lb2 = [ 127.0.0.4, 2 ]
	       }
	       addrs_v6 => {
		 multi => true
		 www6set1 = {
		   lb01 => [ 2001:db8::123, 4 ]
		   lb02 => [ 2001:db8::456, 1 ]
		 }
		 www6set2 = {
		   lb01 => [ 2001:db8::789, 4 ]
		   lb02 => [ 2001:db8::ABC, 1 ]
		 }
	       }
	     }
	     cn => {
	       cnames => {
		 foo = [ lb01.example.com., 99 ]
		 bar = [ lb02.example.com., 15 ]
	       }
	     }
	   }
	 }

       Zonefile RRs referencing the above:

	 www.corp   300 DYNC weighted!corpwww
	 www6.front 300 DYNA weighted!frontwww6
	 www	    300 DYNA weighted!pubwww
	 cdn	    300 DYNA weighted!cdnwww
	 mixed-a    300 DYNA weighted!mixed
	 cnames	    300 DYNC weighted!cn

DESCRIPTION
       gdnsd-plugin-weighted can be used to return one (or a subset) of
       several address records, or one of several CNAME records based on
       dynamic-weighted probabilities.

CONFIGURATION - TOP LEVEL
       At the top level, there are three special parameter keys:
       "service_types", "up_thresh", and "multi".  These only affect the
       behavior of address ("DYNA") lookups.  They are ignored for CNAME
       ("DYNC") lookups.  All of these keys are inherited and override-able at
       the per-resource and per-address-family levels.

       The top-level default "service_types" is "default", which is a built-in
       service type provided by gdnsd.	For more information about configuring
       non-default service type's, see the main gdnsd.config(5) documentation.
       The default polls the "/" URL at each IP address on port 80 for a "200
       OK" response every 10 seconds, and has some anti-flap parameters that
       stabilize the state against isolated, intermittent failures.

       "multi" is a boolean that can be "true" or "false", and defaults to
       "false".	 "multi" controls the behavior of the algorithm for selecting
       result addresses, discussed in detail later.

       "up_thresh" defines a floating point fraction of summed address weights
       in the range "(0.0 - 1.0]", defaulting to 0.5, and is used to influence
       failure/failover behavior.

       Other than those three, the rest of the top level keys are the names of
       your resources, and their values are the configuration of each
       resource.

CONFIGURATION - PER-RESOURCE
       Inside a given resource's configuration hash, again the three address-
       related parameters "services_types", "multi", and "up_thresh" may be
       specified to override their settings per-resource.

       There are two basic configuration modes within a resource:

       1) Explicit per-family/type sub-stanzas.	 In this mode, the resource
       contains one or more of the keys "addrs_v4", "addrs_v6", and "cnames".
       "addrs_v4" and/or "addrs_v6" can both be specified in the same
       resource, but "cnames" cannot co-exist with either of the other two.

       The contents of each stanza configure response RRs of the given type
       for this resource, and in the addrs_v4/addrs_v6 cases, the 3 behavioral
       parameters "service_types", "multi", and "up_thresh" can be overridden
       per-address-family as well.

       2) Automatic top-level detection of just one family/type.  In this
       mode, you can configure the top-level of a resource with valid contents
       for one of the stanzas "addrs_v4", "addrs_v6", or "cnames", and the
       family/type will be autodetected, and be the only type available in
       this resource.

CONFIGURATION - CNAMES
       When configuring cnames, the value of each item should be "[ CNAME,
       WEIGHT ]", and the resource will be useful for "DYNC" zonefile records,
       resolving to a weighted CNAME record in responses.  The weighting
       decision will return a single CNAME answer, with the probability of
       each choice being "weight / total_weight".

       If the CNAMEs are not fully-qualified (do not end in "."), the current
       $ORIGIN value for the zonefile RR being queried will be appended to
       complete the name, much as you would expect if the same not-fully-
       qualified name were substituted into the zonefiles everywhere the
       relevant DYNC record exists.

CONFIGURATION - ADDRESSES
       With the exception that "addrs_v4" and "addrs_v6" must contain only
       addresses of the correct family (or in the top-level auto-detect case,
       the top level entries must all be of the same family), the two stanzas
       behave identically.  When both are present, they are both used in every
       "DYNA" response (as gdnsd always includes opposite-family records in
       the Additional section of A/AAAA queries).

       Within either address family type, there are two different binary
       dimensions (multi -> true/false, and grouped-vs-ungrouped) upon which
       the configuration and behavior hinge, leading to four different
       possible cases: ungrouped-single, ungrouped-multi, grouped-single, and
       grouped-multi.  Each will be discussed in detail below:

THE UNGROUPED SINGLE CASE
       This is the simplest case.  The code detects this case when it sees
       that "multi" is false (the default), and that the values of the keys
       are arrays rather than sub-hashes.  Each hash key is an address label,
       and each value is an array of "[ IPADDR, WEIGHT ]".

       When answering a query in this case, first the weights are converted to
       dynamic weights.	 The dynamic weight of an address is its configured
       weight if the monitored state is "UP" or "DANGER", or zero if the
       monitored state is "DOWN".  The dynamic weights are summed to produce a
       dynamic weight total, and then a single address to respond with is
       chosen from the set, with each address having the odds
       "addr_dynamic_weight / total_dynamic_weight".

       However, if the "total_dynamic_weight" is less than "ceil(up_thresh *
       total_configured_weight)", then the dynamic weights are all reset to
       their configured full values so that the response odds are the same as
       if all were "UP", and resource-level failure is signalled to any upper-
       layer meta-plugin (e.g. metafo or geoip) when applicable.

       Example (X could be a whole resource, or an addrs_v4 stanza):

	 X => {
	   multi => false # default
	   # odds below assume no addresses are down:
	   lb01 => [ 192.0.2.1, 45 ] # 25% chance (45/180)
	   lb02 => [ 192.0.2.1, 60 ] # 33% chance (60/180)
	   lb03 => [ 192.0.2.1, 75 ] # 42% chance (75/180)
	 }

THE UNGROUPED MULTI CASE
       This case is detected when, (as above) the values of the keys are
       arrays of "[ IPADDR, WEIGHT]", but the parameter "multi" is true.  The
       change from the above behavior is primarily that multiple addresses
       from the weighted set can be returned in each response.	The "maximum",
       rather than the sum, of the dynamic weights (again, zero for down
       addresses, configured-weight otherwise), is found, and the odds of each
       address's inclusion in the response set is "addr_dyanmic_weight /
       max_dynamic_weight".

       This means all non-"DOWN" addresses which share the group's maximum
       dynamic weight value will always be included, whereas others will be
       optionally included depending on the odds.  At least one address is
       always returned (because logically, at least one address has the
       maximum weight, giving it a 100% chance), and sometimes the full
       non-"DOWN" set will be returned.

       "up_thresh" behaves as in the previous case: If the sum of the dynamic
       weight values is less than "ceil(up_thresh * total_configured_weight)",
       then the dynamic weights are all set to their configured values and the
       result set is calculated as if all were "UP", while signalling
       resource-level failure to upstream meta-plugins (geoip or metafo).

       Example:

	 X => {
	   multi => true
	   # odds below assume no addresses are down:
	   lb01 => [ 192.0.2.1, 45 ] # 75% chance (45/60)
	   lb02 => [ 192.0.2.1, 60 ] # 100% chance (60/60)
	   lb03 => [ 192.0.2.1, 60 ] # 100% chance (60/60)
	   # overall possible result-sets:
	   # lb01,lb02,lb03 -> 75%
	   # lb02,lb03 -> 25%
	 }

THE GROUPED SINGLE CASE
       The grouped cases are detected when the keys' values are sub-hashes at
       the outer level rather than arrays of "[ IPADDR, WEIGHT]".  In the
       grouped case, first the set is divided into named groups, and then
       within each group individual addresses are configured as "addrlabel =>
       [ IPADDR, WEIGHT ]".

       Example:

	  X => {
	    group1 => {
	      lb01 => [ 192.0.2.1, 10 ]
	      lb02 => [ 192.0.2.1, 20 ]
	      lb03 => [ 192.0.2.1, 30 ]
	    }
	    group2 => {
	      lb01 => [ 192.0.2.7, 10 ]
	      lb02 => [ 192.0.2.8, 20 ]
	      lb03 => [ 192.0.2.9, 30 ]
	    }
	  }

       The grouped single case, of course, occurs when the configuration
       layout is as shown above, and the "multi" parameter is "false" (the
       default).

       In grouped-single mode, essentially the groups are weighted against
       each other similarly to the single case for ungrouped addresses,
       resulting in the choice of a single group from the set of groups. Then
       the addresses within the chosen group are weighted against each other
       in multi-style, returning potentially more than one address from the
       chosen group.

       Specifically, each group's odds of being the single group chosen is
       "group_dyn_weight / total_dyn_weight", where the group's dynamic weight
       is the sum of the dynamic weights within it ("DOWN" addresses are
       zero), and the total dynamic weight is the dynamic sum of all groups.
       Then within each group, the odds of each address being included in the
       multi-response set is "addr_dyn_weight / group_max_dyn_weight".

       "up_thresh" operates on all groups as a whole, and if the non-"DOWN"
       sum of all weights in all groups fails to meet the standard of
       "ceil(up_thresh * total_sum_configured_weight)", then all addresses
       will be treated as if they are "UP" for selection purposes, and
       resource-level failure will be signalled upstream.

THE GROUPED MULTI CASE
       You can probably infer this one's behavior from reading about the
       previous three cases.  The difference from the previous grouped-single
       case is that the multi-vs-single behaviors are reversed.	 Multiple
       groups are chosen based on the dynamic maximum weight between the
       groups, and a single weighted address is returned from the subset
       within each chosen group.  All of the details above logically apply in
       the way you would expect, as all of these four cases internally share
       the same code and logic, they just apply different bits of it to
       different subsets of the problem.

GENERAL NOTES ON ADDRESS MODE CASES ABOVE
       Note that any time multi-selection is in effect at a layer (the top
       layer when multi is true, or within a group when when multi is false),
       the minimum count of chosen items will be the count of items that share
       the maximum weight within the set.  e.g. a set of items with weights
       "30, 30, 30, 20, 20" will always choose at least 3/5 items (because the
       first three have 100% odds of inclusion), and the total response set
       will range as high as all 5 items with some probability.

       A practical use-case example for grouped-single:

       Splitting groups on subnet boundaries in grouped-single mode gives the
       result that a single response packet never mixes subnets.  This would
       enable your DNS-based balancing to defeat certain forms of client-level
       Destination Address Selection interference, while still returning
       multiple addresses per response (all from one subnet).

       A practical use-case for grouped-multi:

       Suppose you have a large set of addresses which can be logically
       grouped into subsets that have some shared failure risk (e.g.
       subpartitions of a datacenter which share infrastructure).  With
       grouped-multi behavior, clients will get up to N (count of groups)
       addresses in a round-robin response, but a given response set will
       never contain two addresses from the same group/subset.	This maximizes
       the chance that the client can successfully fail over to another
       address in the list when its primary selection fails, since the total
       set in each response does not share any per-subset failure mode.

LIMITS
       All weights must be positive integer values greater than zero and less
       than 2^20 (1048576).

       There is a limit of 64 addresses, address-groups, or cnames at the top
       level of a resource (or per address family in the addrs_v4/addrs_v6
       cases), and a limit of 64 addresses within each address group in the
       grouped modes.

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

       The gdnsd manual.

COPYRIGHT AND LICENSE
       Copyright (c) 2012 Anton Tolchanov <me@knyar.net>, Brandon L Black
       <blblack@gmail.com> and Jay Reitz <jreitz@gmail.com>

       This file is part of gdnsd-plugin-weighted.

       gdnsd-plugin-weighted 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-plugin-weighted 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-plugin-weighted.  If not, see
       <http://www.gnu.org/licenses/>.

gdnsd 1.11.0			  2013-12-06	      GDNSD-PLUGIN-WEIGHTED(8)
[top]

List of man pages available for Alpinelinux

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net