# lbcd 3.4.2

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](#license) below for more information.

## 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](https://www.stanford.edu/~riepel/lbnamed/).  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.

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 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.

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 GCC compiler warnings (requires a relatively current version of GCC).

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.

## Support

The [lbcd web page](https://www.eyrie.org/~eagle/software/lbcd/) will
always have the current version of this package, the current
documentation, and pointers to any additional resources.

New lbcd releases are announced on the lbnamed-users mailing list.  To
subscribe or see the list archives, go to the [lbnamed-users management
page](https://mailman.stanford.edu/mailman/listinfo/lbnamed-users).

I welcome bug reports and patches for this package at eagle@eyrie.org.
However, please be aware that I tend to be extremely busy and work
projects often take priority.  I'll save your report and get to it as soon
as I can, but it may take me a couple of months.

## Source Repository

lbcd is maintained using Git.  You can access the current source on
[GitHub](https://github.com/rra/lbcd) or by cloning the repository at:

https://git.eyrie.org/git/system/lbcd.git

or [view the repository on the
web](https://git.eyrie.org/?p=system/lbcd.git).

The eyrie.org repository is the canonical one, maintained by the author,
but using GitHub is probably more convenient for most purposes.  Pull
requests are gratefully reviewed and normally accepted.

## 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.

For any copyright range specified by files in this package as YYYY-ZZZZ,
the range specifies every single year in that closed interval.
