Back to files

                          .:. PURE LOAD BALANCER .:.
                         Documentation for version 0.3

------------------------ BLURB ------------------------

Pure Load Balancer is a high-performance software load balancer for the HTTP and SMTP protocols. It uses an asynchronous non-forking/non-blocking model, and provides fail-over abilities. When a backend server goes down, it automatically removes it from the server pool, and tries to bring it back to life later. Pure Load Balancer has full IPv6 support and works on OpenBSD, NetBSD, FreeBSD and Linux.

------------------------ INSTALLATION ------------------------

Pure Load Balancer relies on Niels Provos' excellent libevent library. This library makes it easy to write non-blocking servers, and it can take advantage of the native kernel event notification mechanism on BSD systems.

OpenBSD and MicroBSD ship with this library in the base installation, so you don't need to reinstall libevent on those systems.

On other systems, you can grab the source code at the following place :

http://monkey.org/~provos/libevent/

That library is also available for most operating systems in the ports tree, portage tree, or in binary form.

Once the library has been installed, compiling an installing PLB follows a very common procedure :

./configure
make install-strip

------------------------ CONFIGURATION ------------------------

Pure Load Balancer needs a configuration file. A sample can be found in the source tarball, and the file is probably installed in default example directories for binary distributions.

By default, the software will look for the configuration file in /etc/plb.conf, but you can override this with the --config command-line startup switch.

The configuration file is self-explanatory, so we'll describe some important points here.

When the server is started with super-user privileges, it will :

1. chroot() to a fixed directory. Its content is never used, this is just to restrict the field of action someone could have if a vulnerability is ever discovered. Having an empty dir is a good idea, and you probably already have one in /var/empty or /var/share/empty for OpenSSH.
2. definitely drop its root privileges to run as a non-privileged user.

It's recommended, but not mandatory to create a dedicated user/group pair for the load balancer.

The "user", "group" and "chroot_dir" control these settings.

Unless you bind privileged ports, the server can also be started as a non-privileged user. But this is not recommended, as chroot() will fail.

There's also a bunch of timeout_* settings. They define the maximal interval between a request and the related answer. Don't set them too low, in order to avoid loading your web servers with idle connections. Only raise those if the link between your servers and your clients is slow or unreliable.

"timeout_cleanup" is the delay between probes when a server has been detected as down. The lower value you put there, the faster recovery you will get.

A server is detected as "down" after a consecutive number of failures. Failures can be : timeouts (server too loaded), host/network unreachable or connection refused.

This number of failures can be as low as 1, to immediately remove it from the server pool as soon as something is wrong. But it might be a bad idea to immediately trigger an alarm, especially if you have a low number of backend servers. This is why you can raise the number of failures, though the "server_retry" field.

Last thing : the backlog. You can keep it low to save some memory, but it may refuse incoming connections when the load balancer host will be very loaded.

------------------------ RUNNING THE BALANCER ------------------------

Running the load balancer is as simple as launching :

/usr/local/bin/plb &

There are some command-line switches you may add, though :

--daemonize : detach ttys and run as a background process.

--config <configuration file> : parse an alternate configuration file.

Default is /etc/plb.conf.

--loglevel <verbosity level> : change the verbosity level. May be overriden

                                by the configuration file. You might
                                want to set this down to 1 during the
                                testing days.
                                
--logfile <log file>          : path to a log file, if none is defined
                                in the configuration file. If the log
                                file is an hyphen, or without this
                                option, logs are sent to STDERR.

--pidfile <pid file>          : write the pid into an alternate location.
                                Default is /var/run/plb.pid .

--help                        : basic help.

--version                     : show version.

           ------------------------ CAVEATS ------------------------

The SMTP protocol is not implemented yet.

Due to current limitations of the event library, the load balancer is more efficient on kqueue-enabled systems.

This includes OpenBSD, NetBSD, MicroBSD and FreeBSD.

Some other systems like Linux have similar, but incompatible kernel notification mechanisms. Third-party help to implement those is always welcome.

------------------------ SUPPORT ------------------------

Please have a look at the CONTACT file.