NAME
lbcd - Report system load for remote load balancing
SYNOPSIS
lbcd [-dhlRrt] [-b address] [-c command] [-P file] [-p port]
[-T seconds] [-w weight]
lbcd -s [-P file]
DESCRIPTION
lbcd runs as a daemon and reports various system utilization
information and optionally service status information via a UDP network
protocol. It is designed to run on the client systems of a remote load
balancing system, such as the DNS-based lbnamed load balancer.
lbcd supports two different query protocols, version two and version
three. (Currently, lbnamed only supports version two queries.) Either
will return the current time according to that system, the time of the
last system boot, the time the information about logged in users last
changed, the load averages (one, five, and fifteen minute), the total
and unique logged in users, whether a user is logged in on console,
percentage full of the system /tmp directory is full, and percentage
full of the system /var/tmp directory. (See, however, the note below
about how some of this data is replaced with calculated weights for
version two responses.) The version three protocol can also return
weight and increment information about a set of services.
The service information is based around a model that returns a weight
(indicating the current utilization of the box -- the higher, the
busier) and an increment (an estimate of how much the utilization will
increase for each additional connection directed to this box) which
defaults to one. The intent is for the load balancer to query the
system periodically, using the returned weight as the system load, and
to estimate the system load between queries of lbcd as the last
returned weight plus the last returned increment times the number of
connections directed to that system. By default, only one service is
returned. That service weight is calculated as follows:
(<uniq-users> * 100 + 300 * <one-minute-load>
+ (<total-users> - <unique-users>) * 20) * <tmp-penalty>
where <tmp-penalty> is a multiplier applied for the most full of /tmp
and /var/tmp ranging between 2 for 90-93% full up to 32 for 100% full.
If /tmp or /var/tmp are completely full, the maximum possible weight
will be returned. If you want to use a simple load average instead,
pass the -S option to lbcd and then the load service will use only the
one-minute load.
Since lbnamed calculates the weight from the one minute load and the
number of logged-in users and currently only supports version two, lbcd
will replace the one-minute load with the weight of the primary service
when responding to a version two query and will set all of the user
numbers to zero unless -S was given. If -S was given, the values
returned will be left alone. (This means that -S will override -R for
version two queries, since -R is equivalent to specifying a service of
rr.)
lbcd responds to any UDP packets on port 4330 (or the port given with
the -p option). It has no built-in security, so if you do not want to
disclose the above information to random systems on the Internet, you
will want to limit access to this port using iptables, firewall rules,
or other similar measures.
By default, lbcd listens on all addresses and responds on whatever
address the kernel picks for outgoing packets. lbnamed sends out all
of its packets and then waits for replies and uses the source address
of the reply packet to associate that reply with one of the queried
hosts. This means that if lbnamed is not configured to query the same
address as the kernel picks for lbcd to respond on, the response may be
ignored and the host considered down. To work around this, use the -b
flag on hosts with multiple interfaces to ensure that replies go out on
the interface being queried. If a host has multiple IP addresses that
will be queried, run multiple instances of lbcd, one for each
interface.
OPTIONS
-b address
By default, lbcd binds to all available addresses. If this option
is given, lbcd binds only to the specified address and will only
answer UDP queries to that address.
-c command
Obtain the service weight and increment by running an external
command. This command should print to standard output one line
containing two integer numbers, separated by whitespace. The first
number is taken to be the weight and the second number is taken to
be the increment. (As mentioned above, when responding to version
two protocol queries, the weight is returned as the one-minute load
average.)
-d Don’t run as a daemon (meaning don’t fork and detach from a tty) to
make it easier to run lbcd inside a debugger.
-h Print out usage information and exit.
-l Currently does nothing. Eventually this will tell lbcd to log all
received requests, but this has not yet been implemented.
-P file
Use file to store the PID of the running lbcd process and as the
file to read for the -r and -s options, rather than the default of
/var/run/lbcd.pid.
-p port
Listen on port rather than the default of 4330.
-R Use round-robin as the service. This will always return a weight
of one and an increment of one. It is equivalent to -w rr. For
version two responses, it will always return a one-minute load of
one regardless of the actual load average of the system (unless -S
is used).
-r Restart a running lbcd process. This stops the existing lbcd
process by killing the PID named in /var/run/lbcd.pid or the file
given with the -P option and then starts as the new lbcd process.
-S When answering version two queries, do not attempt to adjust for
lbnamed’s logic and force it to use the service weight. Instead,
report the load averages and number of logged in users accurately.
This means that version two responses will not contain any
information derived from custom services or weight settings and the
-c, -w, and -R options will be ignored for version two repsonses.
-s Stop an existing lbcd process by killing the PID named in
/var/run/lbcd.pid or the file given with the -P option.
-T seconds
Use a timeout of seconds when doing service probes (including
running a command with -c). The default is five seconds.
-w weight
Specify either a service to probe or a weight and increment to
always return. weight can be a string of the form weight:increment
where both weight and increment are numbers, in which case that
weight and increment will always be returned. Alternately, it can
be the name of a service module, in which case that service will be
probed and its weight will be returned as the service weight (and
the one-minute load with version two queries).
The currently supported services are load (the default), ftp, http,
imap, nntp, ntp, pop, smtp, tcp, and rr (round-robin, the same as
-R). The http and tcp services must be followed by a colon and a
port number.
FILES
/var/run/lbcd.pid
The default location of the PID file. lbcd puts its PID in this
file when it starts, and refers to this file for the -r and -s
commands. The file location can be changed with -P.
SEE ALSO
lbcdclient(1)
The current version of this program is available from its web page at
<http://www.eyrie.org/~eagle/software/lbcd/>.
AUTHORS
Originally written by Roland Schemers and Larry Schwimmer. Currently
maintained by Russ Allbery <rra@stanford.edu>.
COPYRIGHT AND LICENSE
Copyright 1993, 1994, 1996, 1997, 1998, 2000, 2003, 2004, 2005, 2006
Board of Trustees, Leland Stanford Jr. 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.