Adding upstream version 3.2.1+dfsg.upstream/3.2.1+dfsgupstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 172 insertions, 0 deletions

diff --git a/doc/configuration/load_balance.rst b/doc/configuration/load_balance.rst
new file mode 100644
index 0000000..7926444
--- /dev/null
+++ b/doc/configuration/load_balance.rst
@@ -0,0 +1,172 @@
+Load Balancing
+==============
+
+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.