User Commands PEN(1) NAME pen 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] [-E certfile] [-K keyfile] [-G cacertfile] [-A cacertdir] [-Z] [-R] [-L proto- col] [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 con- nections. 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 SunOS 5.11 Last change: 25 Mar 2008 1 User Commands PEN(1) 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 ` where 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 for- mat (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 SunOS 5.11 Last change: 25 Mar 2008 2 User Commands PEN(1) 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 SunOS 5.11 Last change: 25 Mar 2008 3 User Commands PEN(1) File for status reports in HTML 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), ssl2, ssl3 or tls1. host:port The local address and port pen listens to. By default pen listens to all local addresses. h1:p1:soft:hard 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. 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. The SSL code is currently experimental (release 0.13.0). SMF PROPERTIES Configuration of properties for the /usr/bin/pen program is managed by the service management facility, smf(5), under the service identifier: svc:/network/pen:default SunOS 5.11 Last change: 25 Mar 2008 4 User Commands PEN(1) Use svccfg(1M) and svcprop(1M) to change and display the configuration of this service. The following properties must be set before starting the service: pen/listenport (Type astring) The local address and port pen listens on. The value is set like [hostname:]port. If hostname is not specified, then all local address will be listened on. pen/servers (Type astring) The address, the port and the maximum number of simultaneous connections for remote servers. The value is set like "host1[:port1[:sconn1:hconn1]];host2[:port2[:sconn2:hconn2]];..." sconn and hconn are soft and hard limit of the number of connection. The default port value is the same as in pen/listenport. The following properties are optional: pen/blacklist (Type count) The blacklist time in seconds, default is 30. See also option -b above. pen/timeout (Type count) The connection timeout in seconds. default is 5. See also option -t above. pen/logfile (Type astring) The location of the log file, default is /var/log/pen.log. See also option -l above. pen/cfgfile (Type astring) The location of the configuration file (penctl style). See also option -F above. pen/pidfile (Type astring) The location of file into which the PID will be written. See also option -p above. pen/statusfile (Type astring) The location of the report file (in html format). See also option -w above. pen/tracking (Type count) The tracking time, default is 0 (never expire). See also option -T above. pen/emergency (Type astring) The emergency server address to contact SunOS 5.11 Last change: 25 Mar 2008 5 User Commands PEN(1) if all regular servers become unavailable. See also option -e above. pen/maxserver (Type count) The max number of servers, default is 16. See also option -S above. pen/maxclient (Type count) The max number of clients, default is 2048. See also option -c above. pen/chroot (Type astring) The directory for the chroot environ- ment. See also option -j above. pen/user (Type astring) The different user to run pen. See also option -u above. pen/maxconn (Type count) The max number of simultaneous connec- tions, default is 256. See also option -x above. pen/ctrlport (Type count) The control port on which pen daemon listens for commands, default is -1 (not use ctrlport). See also option -C above. pen/Xforward (Type boolean) If X-Forwarded-For header will be added for http requests, default is false. See also option -H above. pen/allowexit (Type boolean) If an exit command is added for the con- trol interface, default is false. See also option -X above. pen/certfile (Type astring) The certificate file (in PEM format) used by pen. See also option -E above. pen/keyfile (Type astring) The key file (in PEM format, may be con- tained in cert) used by pen. See also option -K above. pen/cacertfile (Type astring) The file containing the CA's certifi- cate. See also option -G above. pen/cacertdir (Type astring) The directory containing CA certificates SunOS 5.11 Last change: 25 Mar 2008 6 User Commands PEN(1) in hashed format. See also option -A above. pen/usessl (Type boolean) If SSL compatibility mode is used, default is false. See also option -Z above. pen/peercert (Type boolean) If valid peer certificate is required, default is false. See also option -R above. pen/protocol (Type astring) The ssl protocol version, default is ssl23. See also option -L above. pen/weight (Type boolean) If weight way is used for server selec- tion, default is false. See also option -W above. pen/nonblock (Type boolean) If nonblocking mode is used, default is false. See also option -n above. pen/hash (Type boolean) If hash way is used on client IP addresses for the initial server selection. Enabling it makes pen more predictable which server will be used when a client connects. Default is false. See also option -h above. pen/roundrobin (Type boolean) If straight round-robin server selection is used without looking up which server the client used the last time, default is false. See also option -r above. pen/stubborn (Type boolean) If stubborn server selection is used. If it's enabled, the client connection will be closed without trying another server if the first choice is unavailable. Default is false. See also option -s above. The other command line options are not supported in SMF property. Example 1: Start pen as a http load balancer The following commands will start pen at host myhost as a http load balancer for host foo and bar: svccfg -s network/pen setprop pen/listenport = "myhost:80" svccfg -s network/pen setprop pen/servers = "foo:80;bar:80" svcadm refresh svc:/network/pen:default svcadm disable svc:/network/pen:default SunOS 5.11 Last change: 25 Mar 2008 7 User Commands PEN(1) svcadm enable svc:/network/pen:default Example 2: Start pen with a different log file The following commands will start pen at current host as a http load balancer for host foo and bar, with log file at the location /var/tmp/my.log: svccfg -s network/pen setprop pen/listenport = 80 svccfg -s network/pen setprop pen/servers = "foo:80;bar:80" svccfg -s network/pen setprop pen/logfile = "/var/tmp/my.log" svcadm refresh svc:/network/pen:default svcadm disable svc:/network/pen:default svcadm enable svc:/network/pen:default SEE ALSO penctl(1), mergelogs(1) AUTHOR Copyright (C) 2001-2004 Ulric Eriksson, . ACKNOWLEDGEMENTS In part inspired by balance by Thomas Obermair. ATTRIBUTES See attributes(5) for descriptions of the following attri- butes: _______________________________________ | ATTRIBUTE TYPE | ATTRIBUTE VALUE| |_______________________________________ | Availability | SUNWpen | |_______________________________________ | Interface Stability| Uncommitted | |____________________|_________________| NOTES The Pen project is located at http://siag.nu/pen. Source for Pen is available on http://opensolaris.org. SunOS 5.11 Last change: 25 Mar 2008 8