PEN(1)

NAME
pen

SYNOPSIS
pen [-b sec] [-c N] [-t sec] [-x N] [-l logfile] [-p file ] [-w file] [-C port] [-adfhnrs] [host:]port h1[:p1[:maxc1]] [h2[:p2[:maxc2]]] ...

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 directory. Sending pen a HUP signal will make it close and reopen the logfile, if logging is enabled. 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 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
    Specifies a control port where the load balancer listens for commands.

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

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

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

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

-x N
    Max number of simultaneous connections (default 256).

-w file
    File for status reports in HTML format.

host:port
    The local address and port pen listens to. By default pen listens to all local addresses.

h1:p1:maxc1
    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 number of connections is unlimited.

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.

SEE ALSO
dwatch(1), mergelogs(1), webresolve(1)

AUTHOR
Copyright (C) 2001-2002 Ulric Eriksson, <ulric@siag.nu>.

ACKNOWLEDGEMENTS
In part inspired by balance by Thomas Obermair.