doc/load-balance.txt

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