1PEN(1) General Commands Manual PEN(1)
2
6 pen - Load balancer for udp and tcp based protocols
7
10 pen [-b sec] [-c N] [-e host:port] [-t sec] [-x N] [-j dir] [-u user]
11 [-F cfgfile] [-l logfile] [-p file ] [-w file] [-C
12 port|/path/to/socket] [-T sec] [-UHWXadfhrs] [-o option] [-E certfile]
13 [-K keyfile] [-G cacertfile] [-A cacertdir] [-Z] [-R] [-L protocol]
14 [host:]port|/path/to/socket h1[:p1[:maxc1[:hard1[:weight1[:prio1]]]]]
15 [h2[:p2[:maxc2[:hard2[:weight2[:prio2]]]]]] ...
16 Windows only:
18 pen -i service_name
20 pen -u service_name
22
25 pen 80 www1:8000:10 www2:80:10 www3
26 Here three servers cooperate in a web server farm. Host www1 runs its
28 web server on port 8000 and accepts a maximum of 10 simultaneous con‐
29 nections. Host www2 runs on port 80 and accepts 10 connections.
30 Finally, www3 runs its web server on port 80 and allows an unlimited
31 number of simultaneous connections.
32
35 Pen is a load balancer for udp and tcp based protocols such as dns,
36 http or smtp. It allows several servers to appear as one to the outside
37 and automatically detects servers that are down and distributes clients
38 among the available servers. This gives high availability and scalable
39 performance.
40 The load balancing algorithm keeps track of clients and will try to
42 send them back to the server they visited the last time. The client ta‐
43 ble has a number of slots (default 2048, settable through command-line
44 arguments). When the table is full, the least recently used one will be
45 thrown out to make room for the new one.
46 This is superior to a simple round-robin algorithm, which sends a
48 client that connects repeatedly to different servers. Doing so breaks
49 applications that maintain state between connections in the server,
50 including most modern web applications.
51 When pen detects that a server is unavailable, it scans for another
53 starting with the server after the most recently used one. That way we
54 get load balancing and "fair" failover for free.
55 Correctly configured, pen can ensure that a server farm is always
57 available, even when individual servers are brought down for mainte‐
58 nance or reconfiguration. The final single point of failure, pen
59 itself, can be eliminated by running pen on several servers, using vrrp
60 to decide which is active.
61 Sending pen a USR1 signal will make it print some useful statistics on
63 stderr, even if debugging is disabled. If pen is running in the back‐
64 ground (i.e. without the -f option), syslog is used rather than
65 stderr. If the -w option is used, the statistics is saved in HTML for‐
66 mat in the given file.
67 Sending pen a HUP signal will make it close and reopen the logfile, if
69 logging is enabled, and reload the configuration file.
70 Rotate the log like this (assuming pen.log is the name of the logfile):
72 mv pen.log pen.log.1 kill -HUP `cat <pidfile>`
74 where <pidfile> is the file containing pen's process id, as written by
76 the -p option.
77 Sending pen a TERM signal will make it exit cleanly, closing the log
79 file and all open sockets.
80
83 -C port|/path/to/socket
84 Specifies a control port where the load balancer listens for
85 commands. See penctl.1 for a list of the commands available. The
86 protocol is unauthenticated and the administrator is expected to
87 restrict access using an access control list (for connections
88 over a network) or Unix file permissions (for a Unix domain
89 socket). Pen will normally refuse to open the control port if
90 running as root; see -u option. If you still insist that you
91 want to run pen as root with a control port, use "-u root".
92 -F cfgfile
94 Names a configuration file with commands in penctl format (see
95 penctl.1). The file is read after processing all command line
96 arguments, and also after receiving a HUP signal.
97 -H Adds X-Forwarded-For header to http requests.
99 -U Use udp protocol support
101 -O command
103 Allows most penctl commands to be used on the Pen command line.
104 -P Use poll() for event notification.
106 -W Use weight for server selection.
108 -X Adds an exit command to the control interface.
110 -a Used in conjunction with -dd to get communication dumps in ascii
112 rather than hexadecimal format.
113 -b sec Servers that do not respond are blacklisted, i.e. excluded from
115 the server selection algorithm, for the specified number of sec‐
116 onds (default 30).
117 -T sec Clients are tracked for the specified number of seconds so they
119 can be sent to the same server as the last time (default 0 =
120 never expire clients).
121 -c N Max number of clients (default 2048).
123 -d Debugging (repeat -d for more). The output goes to stderr if we
125 are running in the foreground (see -f) and to syslog (facility
126 user, priority debug) otherwise.
127 -e host:port
129 host:port specifies the emergency server to contact if all regu‐
130 lar servers become unavailable.
131 -f Stay in foreground.
133 -h Use a hash on the client IP address for the initial server
135 selection. This makes it more predictable where clients will be
136 connected.
137 -i service_name
139 Windows only. Install pen as a service.
140 -j dir Run in a chroot environment.
142 -l file
144 Turn on logging.
145 -m multi_accept
147 Accept up to multi_accept incoming connections at a time.
148 -p file
150 Write the pid of the running daemon to file.
151 -q backlog
153 Allow the queue of pending incoming connections to grow up to a
154 maximum of backlog entries.
155 -r Go straight into round-robin server selection without looking up
157 which server a client used the last time.
158 -s Stubborn server selection: if the initial choice is unavailable,
160 the client connection is closed without trying another server.
161 -t sec Connect timeout in seconds (default 5).
163 -u user
165 Posix only. Run as a different user.
166 -u service_name
168 Windows only. Uninstall the service.
169 -x N Max number of simultaneous connections (default 500).
171 -w file
173 File for status reports in HTML format.
174 -o option
176 Use option in penctl format.
177 -E certfile
179 Use the given certificate in PEM format.
180 -K keyfile
182 Use the given key in PEM format (may be contained in cert).
183 -G cacertfile
185 File containing the CA's certificate.
186 -A cacertdir
188 Directory containing CA certificates in hashed format.
189 -Z Use SSL compatibility mode.
191 -R Require valid peer certificate.
193 -L protocol
195 ssl23 (default), ssl3 or tls1.
196 [host:]port OR /path/to/socket
198 The local address and port pen listens to. By default pen lis‐
199 tens to all local addresses. Pen can also use a Unix domain
200 socket as the local listening address.
201 h1:p1:soft:hard:weight:prio
203 The address, port and maximum number of simultaneous connections
204 for a remote server. By default, the port is the same as the
205 local port, and the soft limit on the number of connections is
206 unlimited. The hard limit is used for clients which have
207 accessed the server before. The weight and prio are used for
208 the weight- and priority-based server selection algorithms.
209
212 Pen runs in a single process, and opens two sockets for each connec‐
213 tion. Depending on kernel configuration, pen can run out of file
214 descriptors.
215 SSL support is available if pen was built with the --with-ssl option.
217 GeoIP support is available if pen was built with the --with-geoip
219 option.
220
223 penctl(1), dwatch(1), mergelogs(1), webresolve(1)
224
227 Copyright (C) 2001-2016 Ulric Eriksson, <ulric@siag.nu>.
228
231 In part inspired by balance by Thomas Obermair.
232 LOCAL PEN(1)