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)