Configuration of txLoadBalancer
-------------------------------

A load balancer sits between client systems and a number of server
systems. Client TCP connections connect to the loadbalancer, and
it in turn distributes the connections to the various backend
servers.

A txLoadBalancer config consists of a number of XML directives.

One of the simplest possible configs would be

    <config>
      <service name="web">
        <listen ip="0.0.0.0:80"/>
        <group name="servers" scheduler="roundr" enable="true">
          <host name="server1" ip="192.168.10.1:80"/>
          <host name="server2" ip="192.168.10.2:80"/>
        </group>
      </service>
    </config>

This configuration would produce a server listening on all addresses
(0.0.0.0), port 80, and would alternate hits to the backend servers
192.168.10.1 and 192.168.10.2.

The configuration file is defined completely in doc/reference.txt or
in config.dtd for the XML-savvy.


Top-Level Overview
------------------
A configuration consists of one or more 'service', plus an optional
'admin' and 'logging' section.


Service Section
---------------
The 'service' sections describe a service to be handled. Inside this
section is a listen directive that specifies the port and address the
service will accept connections on.

The meat of the service section is one or more 'group' sections.
These are a group of backend servers and the description of how to
distribute hits between them. Only one group can be active at a time.
You'd use multiple groups, for instance, to specify a set of main
hosts, and a set of backup hosts to use when the main hosts are
undergoing maintenance. You don't need to specify more than one
group, but it is useful. One of the groups need an "enable" attribute
set to a true/on/yes/1 value.


Admin Section
-------------
The admin section controls the administrative web interface. If you
don't have an admin section, there will be no admin web interface
started - as a result, you'll have to re-start the python director
to make any changes. The admin directive takes a listen argument to
specify what address to listen for connections. Use either '*' or
'0.0.0.0' to mean 'listen on all addresses'.

Inside the admin section are one or more 'user' entries. These have
attributes 'name' (the login name), 'password' (the unix crypt password,
see documentation for python module 'crypt'), and 'access'. Access can
be 'full' or 'readonly'. A readonly user can view the current state,
but cannot make changes to the system.

Here is an example admin section:

  <admin>
    <web listen="localhost:7001" enable="true">
    <user name="admin" password="..xpoEyRReGzk" access="full"/>
  </admin>

Additionally, one can add the child node <ssh> for turning on support for
conntecting to the load-balancer's Python interpreter via SSH.


Manager Section
---------------
The manager section provides configuration information for txLoadBalancers's
regularly scheduled tasks.


Log Section
-----------
This section is  optional, and specifies a log file target. If this section is
not specified, the python director will write log entries to stderr.


Control Section
---------------
The control section was introduced by Apple's Calendar Server project and is
used for accurate logging of connected IP addresses. I haven't seen an example
from Apple, but my guess is that usage is something like this:

  <control socket="/path/to/my.socket" />


Comment Sections
----------------
You may also add comments, notes, and cdata to your config files:
<!--
  Here's my comment
/-->

<![CDATA[
  Here's another comment
]]>

<note>
  Here's a note that I have
</note>

Additionally, you may add text to any node; it will be ignored:

 <admin listen="localhost:7001">
    This text will be ignored.
 </admin>
