lbcd 3.4.2
(responder for load balancing)
Maintained by Russ Allbery <eagle@eyrie.org>
Copyright 1993-1994, 1996-1998, 2000, 2003-2009, 2012-2013 The Board of
Trustees of the Leland Stanford Junior University. This software is
distributed under a BSD-style license. Please see the section LICENSE
below for more information.
WARNING
This package is not maintained. Although I believe it is still useful,
I no longer use this method of DNS load balancing and am no longer
maintaining this package. If you would like to pick up maintenance of
it, please feel free. Contact me if you would like this page to
redirect to its new home.
BLURB
lbcd is a daemon that runs on a UNIX system and answers UDP queries with
information about system load, number of logged-on users, uptime, and
free /tmp space. This information can be used to accumulate system
status across a cluster with light-weight queries or can be used as
input to a load-balancing system to choose the best system to which to
direct new incoming connections.
DESCRIPTION
lbcd provides a lightweight way to query a system via unauthenticated
UDP for system load information plus some related information that may
be relevant to determining which system to hand out. It was designed
for use with the lbnamed DNS load balancer [1]. System load, number of
logged-in users, free /tmp space, and system uptime are always returned.
lbcd can also be configured to probe various local services and modify
the returned weights based on whether those services are reachable, or
to return a static weight for round-robin load balancing.
[1] https://www.stanford.edu/~riepel/lbnamed/
The information provided isn't particularly sophisticated, and a good
hardware load balancer will be able to consider such things as
connection latency and responsiveness to make better decisions.
However, lbcd with lbnamed works quite well for smaller scale problems,
scales well to multiple load balance pools for different services,
provides a simple UDP health check service, and is much simpler and
cheaper to understand and deploy.
Included in this package is a small client program, lbcdclient, which
can query an lbcd server and display a formatted version of the returned
information.
It was originally written by Roland Schemers. Larry Schwimmer rewrote
it to add protocol version 3 with some additional features and service
probing, and then I rewrote it again to update the coding style and use
my standard portability layer.
REQUIREMENTS
lbcd is written in C, so you'll need a C compiler. It also uses kernel
calls to obtain load and uptime information, and at present has only
been ported to Linux, Solaris, AIX, various BSD systems, Mac OS X,
HP-UX, IRIX, and Tru64. It is currently primarily tested on Linux.
Platforms not listed may require some porting effort, as may old or
unusual platforms that aren't regularly tested.
The lbcdclient program requires Perl 5.6 or later and requires the
IO::Socket::INET6 module for IPv6 support.
To bootstrap from a Git checkout, or if you change the Automake files
and need to regenerate Makefile.in, you will need Automake 1.11 or
later. For bootstrap or if you change configure.ac or any of the m4
files it includes and need to regenerate configure or config.h.in, you
will need Autoconf 2.64 or later.
BUILDING AND INSTALLATION
You can build and install lbcd with the standard commands:
./configure
make
make install
If you are building from a Git clone, first run ./bootstrap in the
source directory to generate the build files. make install will
probably have to be done as root. Building outside of the source
directory is also supported, if you wish, by creating an empty directory
and then running configure with the correct relative path.
lbcd looks for $sysconfdir/nolbcd and returns the maximum load if that
file is present, allowing one to effectively drop a system out of a
load-balanced pool by touching that file. By default, the path is
/usr/local/etc/nolbcd, but you may want to pass --sysconfdir=/etc to
configure to use /etc/nolbcd.
lbcdclient is written in Perl, so you may have to edit the first line of
the script to point to the correct Perl location on your system. It
does not use any sophisticated Perl features or add-on modules.
Pass --enable-silent-rules to configure for a quieter build (similar to
the Linux kernel). Use make warnings instead of make to build with full
compiler warnings (requires either GCC or Clang and may require a
relatively current version of the compiler).
You will generally want to start lbcd at system boot. All that is
needed is a simple init script to start lbcd with the appropriate
options or kill it again. It writes its PID into /var/run/lbcd.pid by
default (and this can be changed with the -P option). On many systems,
lbcd will need to run as root or as a member of particular groups to
obtain system load average and uptime information.
TESTING
lbcd comes with a test suite, which you can run after building with:
make check
If a test fails, you can run a single test with verbose output via:
tests/runtests -o <name-of-test>
Do this instead of running the test program directly since it will
ensure that necessary environment variables are set up.
Currently, the test suite only checks the portability and utility
libraries, not the functionality of lbcd or lbcdclient.
To enable tests that don't detect functionality problems but are used to
sanity-check the release, set the environment variable RELEASE_TESTING
to a true value. To enable tests that may be sensitive to the local
environment or that produce a lot of false positives without uncovering
many problems, set the environment variable AUTHOR_TESTING to a true
value.
SUPPORT
This package is not currently maintained and will not get further
releases or bug fixes. I do not recommend using it unless you're
willing to take over maintenance.
The lbcd web page at:
https://www.eyrie.org/~eagle/software/lbcd/
has the last released version, its documentation, and pointers to any
additional resources.
SOURCE REPOSITORY
lbcd was maintained using Git. You can access the current source on
GitHub at:
https://github.com/rra/lbcd
or by cloning the repository at:
https://git.eyrie.org/git/system/lbcd.git
or view the repository via the web at:
https://git.eyrie.org/?p=system/lbcd.git
LICENSE
The lbcd package as a whole is covered by the following copyright
statement and license:
Copyright 1993-1994, 1996-1998, 2000, 2003-2009, 2012-2013
The Board of Trustees of the Leland Stanford Junior University
Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:
The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Some files in this distribution are individually released under
different licenses, all of which are compatible with the above general
package license but which may require preservation of additional
notices. All required notices, and detailed information about the
licensing of each file, are recorded in the LICENSE file.
Files covered by a license with an assigned SPDX License Identifier
include SPDX-License-Identifier tags to enable automated processing of
license information. See https://spdx.org/licenses/ for more
information.
For any copyright range specified by files in this package as YYYY-ZZZZ,
the range specifies every single year in that closed interval.