NAME¶
pen - Load balancer for "simple" tcp based protocols
SYNOPSIS¶
pen [-b sec] [-S N] [-c N] [-e host:port] [-t sec] [-x N] [-j dir] [-u
user] [-F cfgfile] [-l logfile] [-p file ] [-w file] [-C port|/path/to/socket]
[-T sec] [-HWXadfhnrs] [-o option] [-E certfile] [-K keyfile] [-G cacertfile]
[-A cacertdir] [-Z] [-R] [-L protocol] [host:]port|/path/to/socket
h1[:p1[:maxc1[:hard1[:weight1[:prio1]]]]]
[h2[:p2[:maxc2[:hard2[:weight2[:prio2]]]]]] ...
EXAMPLE¶
pen 80 www1:8000:10 www2:80:10 www3
Here three servers cooperate in a web server farm. Host www1 runs its web server
on port 8000 and accepts a maximum of 10 simultaneous connections. Host www2
runs on port 80 and accepts 10 connections. Finally, www3 runs its web server
on port 80 and allows an unlimited number of simultaneous connections.
DESCRIPTION¶
Pen is a load balancer for tcp based protocols such as http or smtp. It
allows several servers to appear as one to the outside and automatically
detects servers that are down and distributes clients among the available
servers. This gives high availability and scalable performance.
The load balancing algorithm keeps track of clients and will try to send them
back to the server they visited the last time. The client table has a number
of slots (default 2048, settable through command-line arguments). When the
table is full, the least recently used one will be thrown out to make room for
the new one.
This is superior to a simple round-robin algorithm, which sends a client that
connects repeatedly to different servers. Doing so breaks applications that
maintain state between connections in the server, including most modern web
applications.
When pen detects that a server is unavailable, it scans for another starting
with the server after the most recently used one. That way we get load
balancing and "fair" failover for free.
Correctly configured, pen can ensure that a server farm is always available,
even when individual servers are brought down for maintenance or
reconfiguration. The final single point of failure, pen itself, can be
eliminated by running pen on several servers, using vrrp to decide which is
active.
Sending pen a USR1 signal will make it print some useful statistics on stderr,
even if debugging is disabled. If pen is running in the background (i.e.
without the -f option), syslog is used rather than stderr. If the -w option is
used, the statistics is saved in HTML format in the given file.
Sending pen a HUP signal will make it close and reopen the logfile, if logging
is enabled, and reload the configuration file.
Rotate the log like this (assuming pen.log is the name of the logfile):
mv pen.log pen.log.1 kill -HUP `cat <pidfile>`
where <pidfile> is the file containing pen's process id, as written by the
-p option.
Sending pen a TERM signal will make it exit cleanly, closing the log file and
all open sockets.
OPTIONS¶
- -C port|/path/to/socket
- Specifies a control port where the load balancer listens for commands. See
penctl.1 for a list of the commands available. The protocol is
unauthenticated and the administrator is expected to restrict access using
an access control list (for connections over a network) or Unix file
permissions (for a Unix domain socket). Pen will normally refuse to open
the control port if running as root; see -u option. If you still insist
that you want to run pen as root with a control port, use "-u
root".
- -F cfgfile
- Names a configuration file with commands in penctl format (see penctl.1).
The file is read after processing all command line arguments, and also
after receiving a HUP signal.
- -H
- Adds X-Forwarded-For header to http requests.
- -P
- Use poll() for event notification.
- -Q
- Use kqueue() for event notification (BSD).
- -W
- Use weight for server selection.
- -X
- Adds an exit command to the control interface.
- -a
- Used in conjunction with -dd to get communication dumps in ascii rather
than hexadecimal format.
- -b sec
- Servers that do not respond are blacklisted, i.e. excluded from the server
selection algorithm, for the specified number of seconds (default
30).
- -T sec
- Clients are tracked for the specified number of seconds so they can be
sent to the same server as the last time (default 0 = never expire
clients).
- -S N
- Max number of servers (default 16).
- -c N
- Max number of clients (default 2048).
- -d
- Debugging (repeat -d for more). The output goes to stderr if we are
running in the foreground (see -f) and to syslog (facility user, priority
debug) otherwise.
- -e host:port
- host:port specifies the emergency server to contact if all regular servers
become unavailable.
- -f
- Stay in foreground.
- -h
- Use a hash on the client IP address for the initial server selection. This
makes it more predictable where clients will be connected.
- -j dir
- Run in a chroot environment.
- -l file
- Turn on logging.
- -n
- Nonblocking.
- -p file
- Write the pid of the running daemon to file.
- -r
- Go straight into round-robin server selection without looking up which
server a client used the last time.
- -s
- Stubborn server selection: if the initial choice is unavailable, the
client connection is closed without trying another server.
- -t sec
- Connect timeout in seconds (default 5).
- -u user
- Run as a different user.
- -x N
- Max number of simultaneous connections (default 256).
- -w file
- File for status reports in HTML format.
- -o option
- Use option in penctl format.
- -E certfile
- Use the given certificate in PEM format.
- -K keyfile
- Use the given key in PEM format (may be contained in cert).
- -G cacertfile
- File containing the CA's certificate.
- -A cacertdir
- Directory containing CA certificates in hashed format.
- -Z
- Use SSL compatibility mode.
- -R
- Require valid peer certificate.
- -L protocol
- ssl23, ssl3 or tls1 (default).
- [host:]port OR /path/to/socket
- The local address and port pen listens to. By default pen listens to all
local addresses. Pen can also use a Unix domain socket as the local
listening address.
- h1:p1:soft:hard:weight:prio
- The address, port and maximum number of simultaneous connections for a
remote server. By default, the port is the same as the local port, and the
soft limit on the number of connections is unlimited. The hard limit is
used for clients which have accessed the server before. The weight and
prio are used for the weight- and priority-based server selection
algorithms.
LIMITATIONS¶
Pen runs in a single process, and opens two sockets for each connection.
Depending on kernel configuration, pen can run out of file descriptors.
SSL support is available if pen was built with the --with-ssl option.
GeoIP support is available if pen was built with the --with-geoip option.
SEE ALSO¶
penctl(1), dwatch(1),
mergelogs(1), webresolve(1)
AUTHOR¶
Copyright (C) 2001-2014 Ulric Eriksson, <ulric@siag.nu>.
ACKNOWLEDGEMENTS¶
In part inspired by balance by Thomas Obermair.