doc/load-balance.rst

   1 Load Balancing
   2 ==============
   3
   4 As of version 2.0.0, the load balance documentation is in the
   5 available in the "unlang" man page.  The text below may not be up to
   6 date, and is here only for historical purposes.
   7
   8 As of version 1.1.0, FreeRADIUS supports load balancing in module
   9 sections.  Please see the "configurable_failover" file in this
  10 directory for a more complete description of module sections.
  11
  12 The short summary is that you can use a "load-balance" section in
  13 any place where a module name may be used.  The semantics of the
  14 "load-balance" section are that one of the modules in the section will
  15 be chosen at random, evenly spread over the modules in the list.
  16
  17 An example is below::
  18
  19     accounting {
  20             load-balance {
  21                     sql1
  22                     sql2
  23                     sql2
  24             }
  25     }
  26
  27 In this case, 1/3 of the RADIUS requests will be processed by
  28 "sql1", one third by "sql2", and 1/3 by "sql3".
  29
  30 The "load-balance" section can be nested in a "redundant" section,
  31 or vice-versa::
  32
  33     accounting {
  34             load-balance {              # between two redundant sections below
  35                     redundant {
  36                             sql1
  37                             sql2
  38                     }
  39                     redundant {
  40                             sql2
  41                             sql1
  42                     }
  43             }
  44     }
  45
  46 This says "load balance between sql1 and sql2, but if sql1 is down,
  47 use sql2, and if sql2 is down, use sql1".  That way, you can guarantee
  48 both that load balancing occurs, and that the requests are *always*
  49 logged to one of the databases::
  50
  51     accounting {
  52             redundant {
  53                     load-balance {
  54                             sql1
  55                             sql2
  56                     }
  57                     detail
  58             }
  59     }
  60
  61 This says "load balance between sql1 and sql2, but if the one being
  62 used is down, then log to detail".
  63
  64 And finally::
  65
  66     accounting {
  67             redundant {                 # between load-balance & detail
  68                     load-balance {              # between two redundant sections
  69                             redundant {
  70                                     sql1
  71                                     sql2
  72                             }
  73                             redundant {
  74                                     sql2
  75                                     sql1
  76                             }
  77                     }
  78                     detail
  79             }
  80     }
  81
  82 This says "try to load balance between sql1 and sql2; if sql1 is down,
  83 use sql2; if sql2 is down use sql1; if both sql1 and sql2 are down,
  84 then log to the detail file"
  85
  86
  87 More complicated scenarios
  88 --------------------------
  89
  90 If you want to do redundancy and load-balancing among three
  91 modules, the configuration is quite complex::
  92
  93     load-balance {
  94         redundant {
  95             sql1
  96             load-balance {
  97                 redundant {
  98                     sql2
  99                     sql3
 100                 }
 101                 redundant {
 102                     sql3
 103                     sql2
 104                 }
 105             }
 106         } # sql1, etc.
 107         redundant {
 108             sql2
 109             load-balance {
 110                 redundant {
 111                     sql3
 112                     sql1
 113                 }
 114                 redundant {
 115                     sql1
 116                     sql3
 117                 }
 118             }
 119         } # sql2, etc.
 120         redundant {
 121             sql3
 122             load-balance {
 123                 redundant {
 124                     sql1
 125                     sql2
 126                 }
 127                 redundant {
 128                     sql2
 129                     sql1
 130                 }
 131             }
 132         } # sql3, etc.
 133     }
 134
 135 For four or more modules, it quickly becomes unmanageable.
 136
 137 The solution is to use the "redundant-load-balance" section, which
 138 combines the features of "load-balance", with "redundant" fail-over
 139 between members.  The above complex configuration for three modules
 140 then becomes::
 141
 142     redundant-load-balance {
 143             sql1
 144             sql2
 145             sql3
 146     }
 147
 148
 149 Which means "load-balance evenly among all three servers.  If the
 150 one picked for load-balancing is down, load-balance among the
 151 remaining two.  If that one is down, pick the one remaining 'live'
 152 server".
 153
 154 The "redundant-load-balance" section can contain any number of
 155 modules.
 156
 157
 158 Interaction with "if" and "else"
 159 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 160
 161 It's best to have "if" and "else" blocks contain "load-balance" or
 162 "redundant-load-balance" sections, rather than the other way around.
 163 The "else" and "elsif" sections cannot appear inside of a
 164 "load-balance" or "redundant-load-balance" section, because the "else"
 165 condition would be chose as one of the modules for load-balancing,
 166 which is not what you want.
 167
 168 It's OK to have a plain "if" block inside of a "load-balance" or
 169 "redundant-load-balance" section.  In that case, the "if" condition
 170 checks the return code of the module or group that executed just
 171 before the "load-balance" section.  It does *not* check the return
 172 code of the previous module in the section.