Provided by: lbcd_3.5.2-1_i386 bug

NAME

       lbcd - Report system load for remote load balancing

SYNOPSIS

       lbcd [-dfhlRtZ] [-a allowed-service [-a allowed-service]]
           [-b bind-address [-b bind-address]] [-c command]
           [-P file] [-p port] [-T seconds]
           [-w weight]

       lbcd -t [v2] [service ...]

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 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
       and /var/tmp.  <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 or /var/tmp are completely full, the maximum possible weight will
       be returned.  Different algorithms for determining the weight can be
       used instead; see the -w option.

       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.  If
       you want every system running lbcd to return the same load, use the -R
       option.

       If the file /etc/nolbcd exists, lbcd 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
       daemon.

       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

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

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

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

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

       -h  Print out usage information and exit.

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

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

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

       -T seconds
           Use a timeout of seconds when doing service probes (including
           running a command with -c).  The default is five seconds.

       -t  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 then
           exit.

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

           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.

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

EXAMPLES

       Run lbcd as a daemon, using the default load service, and writing a PID
       file to /var/run/lbcd.pid:

           lbcd -P /var/run/lbcd.pid

       Run lbcd 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

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

           lbcd -R

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

ENVIRONMENT

       LISTEN_FDS
       LISTEN_PID
           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 sd_listen_fds(3).

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

FILES

       /etc/nolbcd
           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 lbcd daemon.

       /etc/nologin
           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.

AUTHORS

       Originally written by Roland Schemers and Larry Schwimmer.  Currently
       maintained by Russ Allbery <eagle@eyrie.org>.

COPYRIGHT AND LICENSE

       Copyright 1993, 1994, 1996, 1997, 1998, 2000, 2003, 2004, 2005, 2006,
       2009, 2012, 2013, 2014 The Board of Trustees of the Leland Stanford
       Junior University

       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.

SEE ALSO

       lbcdclient(1)

       The current version of this program is available from its web page at
       <http://www.eyrie.org/~eagle/software/lbcd/>.