Provided by: lbcd_3.5.2-3_amd64 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/>.