LBCD(8)

📦 version 3.5.2, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 LBCD — section 8 of the manual, bestie 💖

okay so you opened lbcd in the man pages and you're like "what is this girl doing" — let me tell you. This is the system daemon girlie who reports your load. Let's get into it. 🫶

✨ NAME ✨

lbcd — Report system load for remote load balancing. that's the whole job. she reports, she balances, she slays. 💅

🎀 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 🌸

so lbcd runs as a daemon and reports a whole bunch of system utilization info — and, if you want, service status info too — over a UDP network protocol. She's literally designed to live on the client systems of a remote load balancing setup, like the DNS-based lbnamed load balancer. iykyk. ✨

lbcd speaks two different query protocols: version two and version three. (quick note: right now lbnamed only supports version two queries. so like, v3 is the future, not the vibe yet.) Either one will hand back:

  • 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
  • percentage full of the system /var/tmp directory
heads up though — see the note further down about how some of this data gets replaced with calculated weights for version two responses. don't get caught out. 😭

And the version three protocol can also return weight and increment information about a set of services. extra. we love her. 👑

🦋 the whole service model thing 🦋

okay so the service info is built on a model that returns two things:

  • a weight — this indicates the current utilization of the box. the higher, the busier.
  • an increment — an estimate of how much the utilization will increase for each additional connection directed to this box. this one defaults to one.

the intent here is that the load balancer queries the system periodically, uses the returned weight as the system load, and then estimates 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. math girlie behaviour, honestly. 🧚

🍓 the default service weight 🍓

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. Here's how <tmp-penalty> behaves:

  • it'll be 1 if both are less than 90% full
  • it ranges between 2 for 90-93% full up to 32 for 100% full
  • and 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. And if you want every system running lbcd to return the same load, use the -R option. periodt.

🌈 the /etc/nolbcd situation 🌈

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 lets you effectively remove a host from a load-balanced pool by touching a file — without having to stop the lbcd daemon. iconic. no downtime, just vibes. 💅

👀 the lbnamed version-two lore 👀

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
  • set all of the user numbers to zero unless -S was given

If -S was given, the values returned will be left alone. (which means -S will override -R for version two queries, since -R is equivalent to specifying a service of "rr".) the drama of it all 😭

💀 the security bit (read this one, bestie) 💀

lbcd responds to any UDP packets on port 4330 (or the port given with the -p option). She has no built-in security. none. zero. nada. 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. fr fr. 🚨

🌸 the multi-interface saga 🌸

By default, lbcd listens on all addresses and responds on whatever address the kernel picks for outgoing packets. Here's why that matters: lbnamed sends out all of its packets and then waits for replies, and it uses the source address of the reply packet to associate that reply with one of the queried hosts.

Which means — 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 make sure replies go out on the interface being queried. And if a host has multiple IP addresses that will be queried, run multiple instances of lbcd, one for each interface. multitasking queen. 👑

💅 OPTIONS 💅

  • -a allowed-service — The version 3 lbcd protocol lets the client request weight information for a specific protocol. To stop clients from getting info about (and causing lbcd to probe) services that shouldn't be exposed over the protocol, only services specified with -a 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. no fuzzy matching here, bestie. 🎀

  • -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.) cute little contract, respect it. ✨
  • -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. short and sweet. 💫
  • -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). tidy girlie behaviour. 🎀
  • -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). consistency queen. 👑
  • -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. so fun, honestly. 🦋

  • -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. don't forget the colon, bestie, she will not guess for you. 💀

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. niche but iconic. ✨

✨ EXAMPLES ✨

okay bestie, this is the part where we actually do the thing. real invocations, real vibes. 💅

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

ngl that last one is lowkey the most unhinged-but-brilliant thing in here — you're literally asking a whole other program to spill the tea on your machine's health 🫶

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

so like, someone else already did the socket work and lbcd is just the guest of honor arriving fashionably late ✨

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

fr fr though: pick one, bestie. socket activation is the moment, and status notification is giving redundancy 💀

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

touch a file, ghost the pool. iconic behavior honestly 👑

  • /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.

read that again bestie — it's only the default algorithm. -R and -w do not care about this file at all. periodt.

🦋 AUTHORS 🦋

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

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 🌈

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

and that's the whole page bestie, you ate 💅✨

this little legend was version 3.5.2, dated 2015-04-26 — go forth and load-balance like the main character you are 🎀🦋

📦 where this page comes from