  As of version 2.0.0, the load balance documentation is in the
available in the "unlang" man page.  The text below may not be up to
date, and is here only for historical purposes.

  As of version 1.1.0, FreeRADIUS supports load balancing in module
sections.  Please see the "configurable_failover" file in this
directory for a more complete description of module sections.

  The short summary is that you can use a "load-balance" section in
any place where a module name may be used.  The semantics of the
"load-balance" section are that one of the modules in the section will
be chosen at random, evenly spread over the modules in the list.

  An example is below:

accounting {
	load-balance {
		sql1
		sql2
		sql2
	}
}

  In this case, 1/3 of the RADIUS requests will be processed by
"sql1", one third by "sql2", and 1/3 by "sql3".

  The "load-balance" section can be nested in a "redundant" section,
or vice-versa:

accounting {
	load-balance {		# between two redundant sections below
		redundant {
			sql1
			sql2
		}
		redundant {
			sql2
			sql1
		}
	}
}

  This says "load balance between sql1 and sql2, but if sql1 is down,
use sql2, and if sql2 is down, use sql1".  That way, you can guarantee
both that load balancing occurs, and that the requests are *always*
logged to one of the databases.

accounting {
	redundant {
		load-balance {
			sql1
			sql2
		}
		detail
	}
}

  This says "load balance between sql1 and sql2, but if the one being
used is down, then log to detail".

  And finally,

accounting {
	redundant {			# between load-balance & detail
		load-balance {		# between two redundant sections
			redundant {
				sql1
				sql2
			}
			redundant {
				sql2
				sql1
			}
		}
		detail
	}
}

This says "try to load balance between sql1 and sql2; if sql1 is down,
use sql2; if sql2 is down use sql1; if both sql1 and sql2 are down,
then log to the detail file"


	More complicated scenarios
	==========================

  If you want to do redundancy and load-balancing among three
modules, the configuration is quite complex:

...
  load-balance {
      redundant {
          sql1
          load-balance {
	      redundant {
	          sql2
		  sql3
	      }
	      redundant {
	          sql3
		  sql2
	      }
	  }
      } # sql1, etc. 
      redundant {
          sql2
          load-balance {
	      redundant {
	          sql3
		  sql1
	      }
	      redundant {
	          sql1
		  sql3
	      }
	  }
      } # sql2, etc. 
      redundant {
          sql3
          load-balance {
	      redundant {
	          sql1
		  sql2
	      }
	      redundant {
	          sql2
		  sql1
	      }
	  }
      } # sql3, etc. 
   }
...

  For four or more modules, it quickly becomes unmanageable.

  The solution is to use the "redundant-load-balance" section, which
combines the features of "load-balance", with "redundant" fail-over
between members.  The above complex configuration for three modules
then becomes:

...
  redundant-load-balance {
	sql1
	sql2
	sql3
  }
...

  Which means "load-balance evenly among all three servers.  If the
one picked for load-balancing is down, load-balance among the
remaining two.  If that one is down, pick the one remaining 'live'
server".

  The "redundant-load-balance" section can contain any number of
modules.


  Interaction with "if" and "else"
  --------------------------------

  It's best to have "if" and "else" blocks contain "load-balance" or
"redundant-load-balance" sections, rather than the other way around.
The "else" and "elsif" sections cannot appear inside of a
"load-balance" or "redundant-load-balance" section, because the "else"
condition would be chose as one of the modules for load-balancing,
which is not what you want.

  It's OK to have a plain "if" block inside of a "load-balance" or
"redundant-load-balance" section.  In that case, the "if" condition
checks the return code of the module or group that executed just
before the "load-balance" section.  It does *not* check the return
code of the previous module in the section.

----------------------------------------------------------------------
$Id$
