Provided by: lbcd_3.3.0-1_amd64 bug

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.