doc/load-balance.txt

   1   As of version 2.0.0, the load balance documentation is in the
   2 available in the "unlang" man page.  The text below may not be up to
   3 date, and is here only for historical purposes.
   4
   5   As of version 1.1.0, FreeRADIUS supports load balancing in module
   6 sections.  Please see the "configurable_failover" file in this
   7 directory for a more complete description of module sections.
   8
   9   The short summary is that you can use a "load-balance" section in
  10 any place where a module name may be used.  The semantics of the
  11 "load-balance" section are that one of the modules in the section will
  12 be chosen at random, evenly spread over the modules in the list.
  13
  14   An example is below:
  15
  16 accounting {
  17         load-balance {
  18                 sql1
  19                 sql2
  20                 sql2
  21         }
  22 }
  23
  24   In this case, 1/3 of the RADIUS requests will be processed by
  25 "sql1", one third by "sql2", and 1/3 by "sql3".
  26
  27   The "load-balance" section can be nested in a "redundant" section,
  28 or vice-versa:
  29
  30 accounting {
  31         load-balance {          # between two redundant sections below
  32                 redundant {
  33                         sql1
  34                         sql2
  35                 }
  36                 redundant {
  37                         sql2
  38                         sql1
  39                 }
  40         }
  41 }
  42
  43   This says "load balance between sql1 and sql2, but if sql1 is down,
  44 use sql2, and if sql2 is down, use sql1".  That way, you can guarantee
  45 both that load balancing occurs, and that the requests are *always*
  46 logged to one of the databases.
  47
  48 accounting {
  49         redundant {
  50                 load-balance {
  51                         sql1
  52                         sql2
  53                 }
  54                 detail
  55         }
  56 }
  57
  58   This says "load balance between sql1 and sql2, but if the one being
  59 used is down, then log to detail".
  60
  61   And finally,
  62
  63 accounting {
  64         redundant {                     # between load-balance & detail
  65                 load-balance {          # between two redundant sections
  66                         redundant {
  67                                 sql1
  68                                 sql2
  69                         }
  70                         redundant {
  71                                 sql2
  72                                 sql1
  73                         }
  74                 }
  75                 detail
  76         }
  77 }
  78
  79 This says "try to load balance between sql1 and sql2; if sql1 is down,
  80 use sql2; if sql2 is down use sql1; if both sql1 and sql2 are down,
  81 then log to the detail file"
  82
  83
  84         More complicated scenarios
  85         ==========================
  86
  87   If you want to do redundancy and load-balancing among three
  88 modules, the configuration is quite complex:
  89
  90 ...
  91   load-balance {
  92       redundant {
  93           sql1
  94           load-balance {
  95               redundant {
  96                   sql2
  97                   sql3
  98               }
  99               redundant {
 100                   sql3
 101                   sql2
 102               }
 103           }
 104       } # sql1, etc.
 105       redundant {
 106           sql2
 107           load-balance {
 108               redundant {
 109                   sql3
 110                   sql1
 111               }
 112               redundant {
 113                   sql1
 114                   sql3
 115               }
 116           }
 117       } # sql2, etc.
 118       redundant {
 119           sql3
 120           load-balance {
 121               redundant {
 122                   sql1
 123                   sql2
 124               }
 125               redundant {
 126                   sql2
 127                   sql1
 128               }
 129           }
 130       } # sql3, etc.
 131    }
 132 ...
 133
 134   For four or more modules, it quickly becomes unmanageable.
 135
 136   The solution is to use the "redundant-load-balance" section, which
 137 combines the features of "load-balance", with "redundant" fail-over
 138 between members.  The above complex configuration for three modules
 139 then becomes:
 140
 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.
 173
 174 ----------------------------------------------------------------------
 175 $Id$