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

XML Reference
=============

A txLoadBalancer config consists of a number of XML directives.

<config> - the top level XML node.
  Attributes:
    No attributes.
  Children:
    Must contain one or more <service> nodes.
    Can contain an optional <admin> node.
    Can contain an optional <logging> node.
  Other notes:
    None

<service> - a load balancer service.
  Child of: <config>
  Attributes:
    name - the name of this service. A text label.
  Children:
    Must contain one or more <listen> nodes.
    Must contain one or more <group> nodes.
  Other notes:
    None

<listen> - listen on a network port
  Child of: <service>
  Attributes:
    ip - IP address to listen on, in format host:port
  Children:
    No children.
  Other notes:
    A service can listen on multiple host:ip ports.

<group> - a group of backend servers
  Child of: <service>
  Attributes:
    name - name of this group. Text label, should be unique in the service.
    scheduler - name of the scheduler to use for this group. Full list in
                doc/schedulers.txt
    enable - the group that should be enabled when the load balancer starts
             needs to have its value set to "true"
  Children:
    Should contain one or more <host> nodes.
  Other notes:
    None

<host> - a backend server
  Child of: <group>
  Attributes:
    name - name of this host
    ip - IP address to listen on, in format host:port
    weight - an optional integer attribute; higher relative values will
             increase the likelihood of host selection by the scheduler
  Children:
    No children.
  Other notes:
    This used to be called <client>. Should be no references to the old
    name left anywhere.

<admin> - administrative web interface
  Child of: <config>
  Attributes: None
  Children:
    Can contain one <web> node
    Can contain one <ssh> node
    Should contain one or more <user> nodes
  Other notes:
    Could you have multiple admin nodes, to listen on multiple ports with
    different user DBs? No reason why not...

<web> - For configuring the admin web UI
    listen - IP address to run admin web interface on, in host:port format
    enable - a boolean for starting the load-balancer with or without this
             service
    secure - a boolean for determining whether to run the admin web UI over SSL
    refresh - the rate at which the admin "running" page refreshes

<ssh> - For configuring admin SSH access to the load-balancer's Python
        interpreter
  Child of: <admin>
  Attributes:
    listen - IP address to run admin SSH interface on, in host:port format
    enable - a boolean for starting the load-balancer with or without this
             service
  Children:
    No children
  Other notes:
    None

<user> - user of administrative web interface
  Child of: <admin>
  Attributes:
    name - the user's login name
    password - the unix crypt() password of the user
    access - what rights the user has. One of "full" or "readonly"
  Children:
    No children.
  Other notes:
    Source users from somewhere else?

<logging> - logging for txLoadBalancer
  Child of: <config>
  Attributes:
    file - log file path
  Children:
    No children.
  Other notes:
    None

<manager> - configuration options for various tasks that txLoadBalanver
            manages, such as bad host checks
  Child of: <config>
  Attributes:
    hostCheckInterval - the time in seconds between re-checkign bad hosts
  Children:
    Can contain one <hostCheck> node
    Can contain one <configCheck> node
    Can contain one <heartbeat> node
  Other notes:
    None

<hostCheck> - configuration options for the manager that checks if a bad host
              can come back into rotation
  Child of: <manager>
  Attributes:
    interval - time interval in seconds (and fractions thereof) a check should
               be performed
  Children:
    No children.
  Other notes:
    None

<configCheck> - configuration options for the manager that checks if a
                configuration should be written to disk
  Child of: <manager>
  Attributes:
    interval - time interval in seconds (and fractions thereof) a check should
               be performed
  Children:
    No children.
  Other notes:
    None

<heartbeat> - configuration options for the manager that checks if proxied
              hosts are available for receiving load-balanced requests
  Child of: <manager>
  Attributes:
    interval - time interval in seconds (and fractions thereof) a check should
               be performed
  Children:
    No children.
  Other notes:
    None

<control> - configuration options for accurate tracking of connected IP
            addresses
  Child of: <config>
  Attributes:
    socket - the path and filename of the socket to connect to
  Children:
    None
  Other notes:
    None
