Provided by: pen_0.32.0-1_amd64 
NAME
pen - Load balancer for udp and tcp based protocols
SYNOPSIS
pen [-b sec] [-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] [-UHWXadfhrs] [-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]]]]]] ...
Windows only:
pen -i service_name
pen -u service_name
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.
-U Use udp protocol support
-O command
Allows most penctl commands to be used on the Pen command line.
-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).
-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.
-i service_name
Windows only. Install pen as a service.
-j dir Run in a chroot environment.
-l file
Turn on logging.
-m multi_accept
Accept up to multi_accept incoming connections at a time.
-p file
Write the pid of the running daemon to file.
-q backlog
Allow the queue of pending incoming connections to grow up to a maximum of backlog
entries.
-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
Posix only. Run as a different user.
-u service_name
Windows only. Uninstall the service.
-x N Max number of simultaneous connections (default 500).
-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 (default), ssl3 or tls1.
[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-2015 Ulric Eriksson, <ulric@siag.nu>.
ACKNOWLEDGEMENTS
In part inspired by balance by Thomas Obermair.
LOCAL PEN(1)