lbcd - Report system load for remote load balancing
[ -c command
[ -P file
] [-p port
[ -w weight
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
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
directory is full, and percentage full of the system
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
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 default 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-penalty> will be 1 if both are
less than 90% full and will range between 2 for 90-93% full up to 32 for 100%
full. If /tmp
are completely full, the maximum
possible weight will be returned. Different algorithms for determining the
weight can be used instead; see the -w
If you want to use a simple load average instead, pass the -S
and then the load service will use only the one-minute load. If
you want every system running lbcd
to return the same load, use the
If the file /etc/nolbcd
will force the weight of the
default service to the maximum value regardless of the normal service
calculation. This allows one to effectively remove a host from a load-balanced
pool by touching a file without having to stop the lbcd
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
was given. If -S
was given, the values returned will
be left alone. (This means that -S
will override -R
two queries, since -R
is equivalent to specifying a service of
responds to any UDP packets on port 4330 (or the port given with the
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
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.
- -a allowed-service
- The version 3 lbcd protocol allows the client to request
weight information for a specific protocol. To prevent clients from
getting information about (and causing lbcd to probe) services that
shouldn't be exposed over protocol, only services specified with the
-a option are allowed. This option may be given multiple times to
allow multiple services to be queried. The service specified with
-w, if any, is always allowed, as is the "default"
For a list of the supported services, and therefore the allowed values for
allowed-service, see the -w option.
Client queries are compared exactly against the allowed-service
values, including any port information after a colon, so all service
values that should be queryable must be listed using this option.
- -b bind-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. This option may be given
multiple times to bind to multiple addresses. bind-address must be
an IP address (either IPv4 or IPv6), not a hostname.
This option is ignored if lbcd is passed already open sockets via the
systemd socket activation protocol. In that case, the bind addresses of
the sockets should be controlled via the systemd configuration.
- -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.)
- Run in the foreground (the same as with -f), send
informational messages to standard output instead of syslog, and send
errors to standard error instead of syslog. This is intended for
- Run in the foreground, meaning don't fork and don't detach
from the controlling terminal. This allows lbcd to be run more
simply via modern init systems such as upstart or systemd and work
properly with process supervisors such as daemontools or runit.
- Print out usage information and exit.
- Log every received request to syslog (or to standard output
if -d was given). The requests will be logged with the LOG_DAEMON
facility and the LOG_INFO priority.
- -P file
- Store the PID of the running daemon in file.
file will be deleted when lbcd exits normally (via a SIGTERM
or SIGINT signal).
- -p port
- Listen on port rather than the default of 4330.
This option is ignored if lbcd is passed already open sockets via the
systemd socket activation protocol. In that case, the listening port
should be controlled via the systemd configuration.
- 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).
- 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
- -T seconds
- Use a timeout of seconds when doing service probes
(including running a command with -c). The default is five
- Test mode. When run with the -t flag, lbcd
will do all the checks that it would do when receiving a query packet,
print out the results in a human-readable format to standard output, and
When run with this option, the remaining command-line arguments are taken as
services to probe. The valid service names are the same as the valid
service arguments to the -w option, with one exception. If the
first service is the string "v2", lbcd will behave as if
it received a protocol version two query packet and will manipulate its
reply information accordingly before printing it out.
- -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
This option only affects the default service. A version 3 protocol client
can query any of the supported services provided that the service is
listed as allowed, using the -a flag. This allows the client to get
weight and increment information for several different services.
- When lbcd has set up its network socket and is ready
to answer requests, raise SIGSTOP. This signals to upstart, when using
"expect stop", that the daemon is ready to accept connections,
and upstart will raise SIGCONT to allow lbcd to continue. This
option is probably only useful when using upstart as the init system.
as a daemon, using the default load service, and writing a PID
file to /var/run/lbcd.pid
lbcd -P /var/run/lbcd.pid
in the foreground, and log all client requests via syslog. This
is a typical invocation with systemd, using socket activation.
lbcd -f -l
The same, but raise SIGSTOP after lbcd
is ready to answer queries. This
is a typical invocation with upstart.
lbcd -f -l -Z
as a daemon, with default behavior, but use round-robin as the
default service. This will equally balance queries across machines instead of
trying to be sensitive to load.
Determine the weight of the system based on whether the local HTTP port is
responding. If it isn't, the system will return the maximum weight, which will
cause it to drop out of the pool.
lbcd -w http:80
Run the external program /usr/bin/lb-slapd
to determine the weight.
lbcd -c /usr/bin/ldap-check
This program should print, to standard output, two numbers separated by a space.
The first will be the weight and the second will be the load. In this case, it
does a query against a local LDAP search to determine its health. (A good
approach for LDAP slaves would be to check the syncrepl data to see if the
slave is up-to-date.)
- If these environment variables are set, lbcd will
expect to be provided its listening sockets via the systemd socket
activation protocol and will not attempt to bind its own sockets. For more
details on the protocol, see daemon(7) and
- If this environment variable is set, lbcd will
notify the socket named in this variable when it is ready to accept
incoming packets using the systemd status notification protocol. For more
details, see daemon(7) and sd_notify(3).
Note that using socket activation is recommended when running under systemd,
and status notification is not necessary or useful when using socket
- If this file exists, lbcd will force the weight of
the default service to the maximum possible value regardless of the normal
weight calculation. This allows one to effectively remove a host from a
load-balanced pool by touching a file without having to stop the
- If this file exists, lbcd will force the weight
returned by the default load algorithm to the maximum possible value. This
will only apply if the default load algorithm is used; if a different
algorithm is used, due to -R or -w, no change to the
returned weight will be made.
Originally written by Roland Schemers and Larry Schwimmer. Currently maintained
by Russ Allbery <email@example.com>.
Copyright 1993, 1994, 1996, 1997, 1998, 2000, 2003, 2004, 2005, 2006, 2009,
2012, 2013, 2014 The Board of Trustees of the Leland Stanford Junior
Copying and distribution of this file, with or without modification, are
permitted in any medium without royalty provided the copyright notice and this
notice are preserved. This file is offered as-is, without any warranty.
The current version of this program is available from its web page at