Description
-----------

A Python-based Gearman worker that handles work for the job queue named
'lbaas-<IP>'. It receives JSON data describing a load balancer, and
returns this same JSON object, but with status fields added to describe
the state of the LB.


Running Tests
-------------

Tox is the best way to run the tests. Tox, if unavailable, can be installed
via the Python pip command:

   $ pip install tox

Once it is installed, run the tests:

   $ tox


Installing the Tools
--------------------

You must have Python setuptools installed. On Ubuntu:

    $ sudo apt-get install python-setuptools

Now you may install the Libra toolset:

    $ sudo python setup.py install

The worker also needs some packages installed in order to be used with
HAProxy. The commands below will install them on Ubuntu:

    $ sudo apt-get install haproxy
    $ sudo apt-get install socat


Edit /etc/sudoers
-----------------

The worker needs to be able to run some commands as root without being
prompted for a password. It is suggested that you run the worker as
the `haproxy` user and `haproxy` group on Ubuntu systems. Then add the
following line to /etc/sudoers:

    %haproxy ALL = NOPASSWD: /usr/sbin/service, /bin/cp, /bin/mv, /bin/rm, /usr/bin/socat

The above lets everyone in the `haproxy` group run those commands
as root without being prompted for a password.


Running the Worker
------------------

The worker can run in either daemon or non-daemon mode. Daemon mode requires
escalated privileges so that it can behave like a proper daemon. Non-daemon
mode (--nodaemon option) is useful for testing.

Basic commands:

    # Getting help
    $ libra_worker -h

    # Start up as a daemon running as the `haproxy` user and
    # connecting to the local Gearman job server.
    $ sudo libra_worker --user haproxy --group haproxy --server 127.0.0.1:4730

    # Start up with debugging output in non-daemon mode
    $ libra_worker --debug --nodaemon

NOTE: When running the worker in daemon mode, you must make sure that the
directory where the PID file will be (-p/--pid option) is writable by the
user/group specified with the --user and --group options.

You can verify that the worker is running by using the sample Gearman
client in the bin/ directory:

    $ bin/client.py


Configuration File
------------------

It can be easier to give options via a configuration file. See the sample
configuration file etc/sample_libra.cfg for an example and further
documentation. Use the -c/--config option to specify the configuration
file to read.