1PEN(1) General Commands Manual PEN(1)
2
6 pen
7
10 pen [-b sec] [-S N] [-c N] [-e host:port] [-t sec] [-x N] [-j dir] [-u
11 user] [-F cfgfile] [-l logfile] [-p file ] [-w file] [-C port] [-T sec]
12 [-HWXadfhnrs] [-o option] [-E certfile] [-K keyfile] [-G cacertfile]
13 [-A cacertdir] [-Z] [-R] [-L protocol] [host:]port
14 h1[:p1[:maxc1[:hard1[:weight1[:prio1]]]]]
15 [h2[:p2[:maxc2[:hard2[:weight2[:prio2]]]]]] ...
16
19 pen 80 www1:8000:10 www2:80:10 www3
20 Here three servers cooperate in a web server farm. Host www1 runs its
22 web server on port 8000 and accepts a maximum of 10 simultaneous con‐
23 nections. Host www2 runs on port 80 and accepts 10 connections.
24 Finally, www3 runs its web server on port 80 and allows an unlimited
25 number of simultaneous connections.
26
29 Pen is a load balancer for tcp based protocols such as http or smtp. It
30 allows several servers to appear as one to the outside and automati‐
31 cally detects servers that are down and distributes clients among the
32 available servers. This gives high availability and scalable perfor‐
33 mance.
34 The load balancing algorithm keeps track of clients and will try to
36 send them back to the server they visited the last time. The client ta‐
37 ble has a number of slots (default 2048, settable through command-line
38 arguments). When the table is full, the least recently used one will be
39 thrown out to make room for the new one.
40 This is superior to a simple round-robin algorithm, which sends a
42 client that connects repeatedly to different servers. Doing so breaks
43 applications that maintain state between connections in the server,
44 including most modern web applications.
45 When pen detects that a server is unavailable, it scans for another
47 starting with the server after the most recently used one. That way we
48 get load balancing and "fair" failover for free.
49 Correctly configured, pen can ensure that a server farm is always
51 available, even when individual servers are brought down for mainte‐
52 nance or reconfiguration. The final single point of failure, pen
53 itself, can be eliminated by running pen on several servers, using vrrp
54 to decide which is active.
55 Sending pen a USR1 signal will make it print some useful statistics on
57 stderr, even if debugging is disabled. If pen is running in the back‐
58 ground (i.e. without the -f option), syslog is used rather than
59 stderr. If the -w option is used, the statistics is saved in HTML for‐
60 mat in the given file.
61 Sending pen a HUP signal will make it close and reopen the logfile, if
63 logging is enabled, and reload the configuration file.
64 Rotate the log like this (assuming pen.log is the name of the logfile):
66 mv pen.log pen.log.1 kill -HUP `cat <pidfile>`
68 where <pidfile> is the file containing pen's process id, as written by
70 the -p option.
71 Sending pen a TERM signal will make it exit cleanly, closing the log
73 file and all open sockets.
74
77 -C port
78 Specifies a control port where the load balancer listens for
79 commands.
80 -F cfgfile
82 Names a configuration file with commands in penctl format (see
83 penctl.1). The file is read after processing all command line
84 arguments, and also after receiving a HUP signal.
85 -H Adds X-Forwarded-For header to http requests.
87 -P Use poll() for event notification.
89 -Q Use kqueue() for event notification (BSD).
91 -W Use weight for server selection.
93 -X Adds an exit command to the control interface.
95 -a Used in conjunction with -dd to get communication dumps in ascii
97 rather than hexadecimal format.
98 -b sec Servers that do not respond are blacklisted, i.e. excluded from
100 the server selection algorithm, for the specified number of sec‐
101 onds (default 30).
102 -T sec Clients are tracked for the specified number of seconds so they
104 can be sent to the same server as the last time (default 0 =
105 never expire clients).
106 -S N Max number of servers (default 16).
108 -c N Max number of clients (default 2048).
110 -d Debugging (repeat -d for more). The output goes to stderr if we
112 are running in the foreground (see -f) and to syslog (facility
113 user, priority debug) otherwise.
114 -e host:port
116 host:port specifies the emergency server to contact if all regu‐
117 lar servers become unavailable.
118 -f Stay in foreground.
120 -h Use a hash on the client IP address for the initial server
122 selection. This makes it more predictable where clients will be
123 connected.
124 -j dir Run in a chroot environment.
126 -l file
128 Turn on logging.
129 -n Nonblocking.
131 -p file
133 Write the pid of the running daemon to file.
134 -r Go straight into round-robin server selection without looking up
136 which server a client used the last time.
137 -s Stubborn server selection: if the initial choice is unavailable,
139 the client connection is closed without trying another server.
140 -t sec Connect timeout in seconds (default 5).
142 -u user
144 Run as a different user.
145 -x N Max number of simultaneous connections (default 256).
147 -w file
149 File for status reports in HTML format.
150 -o option
152 Use option in penctl format.
153 -E certfile
155 Use the given certificate in PEM format.
156 -K keyfile
158 Use the given key in PEM format (may be contained in cert).
159 -G cacertfile
161 File containing the CA's certificate.
162 -A cacertdir
164 Directory containing CA certificates in hashed format.
165 -Z Use SSL compatibility mode.
167 -R Require valid peer certificate.
169 -L protocol
171 ssl23 (default), ssl2, ssl3 or tls1.
172 host:port
174 The local address and port pen listens to. By default pen lis‐
175 tens to all local addresses.
176 h1:p1:soft:hard:weight:prio
178 The address, port and maximum number of simultaneous connections
179 for a remote server. By default, the port is the same as the
180 local port, and the soft limit on the number of connections is
181 unlimited. The hard limit is used for clients which have
182 accessed the server before. The weight and prio are used for
183 the weight- and priority-based server selection algorithms.
184
187 Pen runs in a single process, and opens two sockets for each connec‐
188 tion. Depending on kernel configuration, pen can run out of file
189 descriptors.
190 The SSL support is only available if pen was built with the --with-ssl
192 option. The SSL code is currently experimental (release 0.13.0).
193
196 penctl(1), dwatch(1), mergelogs(1), webresolve(1)
197
200 Copyright (C) 2001-2008 Ulric Eriksson, <ulric@siag.nu>.
201
204 In part inspired by balance by Thomas Obermair.
205 LOCAL PEN(1)