Provided by: pen_0.32.0-1_amd64 bug

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)