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] [-T sec] [-HWXadfhnrs] [-o option] [-E certfile] [-K keyfile] [-G
       cacertfile] [-A cacertdir] [-Z] [-R] [-L protocol] [host:]port 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
              Specifies a control port where the load balancer listens for commands.

       -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
              The local address and port pen listens to. By default pen listens to all local addresses.

       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.

       The SSL support is only available if pen was built with the --with-ssl option.

SEE ALSO

       penctl(1), dwatch(1), mergelogs(1), webresolve(1)

AUTHOR

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

ACKNOWLEDGEMENTS

       In part inspired by balance by Thomas Obermair.

                                                      LOCAL                                               PEN(1)