Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
PEN(1)			    General Commands Manual			PEN(1)

       pen - Load balancer for udp and tcp based protocols

       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

       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 con-
       nections.  Host www2 runs on port 80 and	accepts	 10  connections.  Fi-
       nally, www3 runs	its web	server on port 80 and allows an	unlimited num-
       ber of simultaneous connections.

       Pen is a	load balancer for udp and tcp based  protocols	such  as  dns,
       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

       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 ta-
       ble 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, in-
       cluding 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  mainte-
       nance  or  reconfiguration.  The	final single point of failure, pen it-
       self, 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	 back-
       ground  (i.e.   without	the  -f	 option),  syslog  is used rather than
       stderr. If the -w option	is used, the statistics	is saved in HTML  for-
       mat 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.

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

       -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 sec-
	      onds (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 regu-
	      lar servers become unavailable.

       -f     Stay in foreground.

       -h     Use  a  hash on the client IP address for	the initial server se-
	      lection.	This makes it more predictable where clients  will  be

       -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  lis-
	      tens  to	all  local  addresses.	Pen can	also use a Unix	domain
	      socket as	the local listening address.

	      The address, port	and maximum number of simultaneous connections
	      for a remote server. By default, the port	is the same as the lo-
	      cal port,	and the	soft limit on the number of connections	is un-
	      limited.	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.

       Pen  runs  in  a	single process,	and opens two sockets for each connec-
       tion.  Depending	on kernel configuration, pen can run out of  file  de-

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

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

       Copyright (C) 2001-2016 Ulric Eriksson, <>.

       In part inspired	by balance by Thomas Obermair.

				     LOCAL				PEN(1)


Want to link to this manual page? Use this URL:

home | help