1PENCTL(1) General Commands Manual PENCTL(1)
2
6 penctl - control a running pen load balancer
7
10 penctl host:port|/path/to/socket command
11
14 penctl lbhost:8888 roundrobin
15 Turns off client tracking on the load balancer running on lbhost.
17 penctl /var/run/pen/tmp/ctrl status
19 Prints status information in html format.
21
24 Penctl connects to the optional control socket on a pen load balancer.
25 It reads commands from the command line, performs minimal syntax check‐
26 ing and sends them to pen. Replies, if any, are printed on stdout.
27 The program can also be used through the cgi script penctl.cgi, which
29 allows pen to be controlled from any web browser.
30
33 host:port
34 Specifies a control port where the load balancer listens for
35 commands.
36
39 abort_on_error
40 Call abort() when a fatal error is encountered. This will create
41 a core file which allows further troubleshooting. Disabled by
42 default.
43 no abort_on_error
45 Exit normally on fatal error with an error code which indicates
46 failure.
47 acl N permit|deny sourceip4 [mask]
49 Adds an entry to access list N, where N is a number from 0 to 9.
50 The source and mask addresses are in the usual dotted quad nota‐
51 tion. If mask is omitted, it defaults to 255.255.255.255.
52 acl N permit|deny sourceip6[/length]
55 If the source address contains the character ':', the address is
56 interpreted as IPv6. Unlike IPv4 access entries, a length is
57 used to indicate the mask. If length is omitted, it defaults to
58 128.
59 acl N permit|deny country NN
62 If the source address is the special word "country", a two-let‐
63 ter country code can be used to restrict access to the load bal‐
64 ancer. For this to work, pen must be built with geoip support.
65 no acl N
67 Deletes all entries from access list N. The resulting access
68 list permits all traffic.
69 ascii Communication dumps in ascii format (cf option -a).
71 no ascii
73 Communication dumps in hex format.
74 blacklist
76 Return current blacklist time in seconds.
77 blacklist T
79 Set the blacklist time in seconds.
80 block Do not make sockets nonblocking. This is obsolete as of 0.26.0
82 and does nothing.
83 no block
85 Make sockets nonblocking.
86 client_acl N
88 Check connecting clients against access list N (default 0).
89 clients_max [N]
91 With argument, increase the maximum number of known clients.
92 Returns max number of clients.
93 close N
95 Close connection N
96 connection N
98 Display some basic information about connection N.
99 conn_max [N]
101 With argument, increase the max number of simultaneous connec‐
102 tions. Returns max number.
103 control
105 Return address and port where pen listens for control connec‐
106 tions.
107 control_acl N
109 Check accesses to the control port against access list N
110 (default 0).
111 debug Return current debug level.
113 debug N
115 Set debug level to N.
116 delayed_forward
118 Always wait for the next round of the main loop before forward‐
119 ing data. Normally pen tries to do that immediately. This is
120 obsolete as of 0.26.0 and does nothing.
121 no delayed_forward
123 Try to forward data immediately, to avoid the overhead of copy‐
124 ing it to a temporary buffer and waiting for the next main loop
125 round.
126 dsr_if IF
128 Use IF as the interface for Direct Server Return.
129 dummy Act as a dummy web server with very limited functionality but
131 high performance. Only useful for testing. Disabled by default.
132 no dummy
134 Do not act as a dummy web server.
135 epoll Use epoll for event management (Linux). This is the default on
137 Linux.
138 exit Exit. Only available if pen was started with the -X option.
140 hash Use a hash on the client IP address for initial server selec‐
142 tion.
143 no hash
145 Do not use a hash.
146 http Add X-Forwarded-For headers to http requests.
148 no http
150 Do not add X-Forwarded-For headers.
151 idle_timeout N
153 Close connections that have been inactive for N seconds. Default
154 0 = never close.
155 idlers [N]
157 Create N reliable idle connections to the backend servers. With‐
158 out argument, display the current/requested number of reliable
159 idlers.
160 include FILE
162 Read commands from file.
163 kqueue Use kqueue for event management (FreeBSD, NetBSD, OpenBSD).
165 This is the default on the systems that have it.
166 listen Return local address and port pen listens to for incoming client
168 connections.
169 listen [address:]:port
171 Close the listening socket and reopen using specified address
172 (optional) and port.
173 log Show where pen is logging, if anywhere.
175 log FILE
177 Log to FILE.
178 mode Write a summary of the current mode of operation. The listed
180 modes are block, delayed_forward, hash, roundrobin, stubborn.
181 no log Turn off logging.
183 pending_max N
185 Max allowed number of pending nonblocking connections. Default
186 100, minimum 1.
187 pid Return the process id of the running daemon.
189 poll Use poll for event management.
191 prio Use the priority based algorithm.
193 no prio
195 Do not use the priority based algorithm.
196 recent [N]
198 Shows which clients have connected in the last N seconds
199 (default 300).
200 roundrobin
202 Use round-robin server selection without client tracking
203 no roundrobin
205 select Use select for event management.
208 server N [ acl A | address A | port P | max M | hard H | blacklist T |
210 weight W | prio P ]
211 Change acl, address, port, weight, priority and/or max connec‐
212 tions for server N, or blacklist it for T seconds.
213 servers
215 List address, port, weight, priority and max number of simulta‐
216 neous connections for each remote server.
217 socket N
219 Show to which connection socket N belongs.
220 source IP
222 Set the local address to IP for upstream connections, i.e. where
223 Pen connects to backend servers.
224 ssl_ciphers CIPHERS
226 Choose list of available SSL ciphers, specified in the format
227 described in https://www.openssl.org/docs/apps/ciphers.html.
228 ssl_client_renegotiation_interval S
230 Allowing the client to request renegotiation is a potential
231 denial of service vector. This command specifies the minimum
232 number of seconds the client has to wait between requests for
233 renegotiation requests. Default 3600 = effectively disabled.
234 ssl_ocsp_response FILENAME
236 Specifies the location of a file containing a pre-fetched OCSP
237 response. The file must be refreshed regularly by a cron job or
238 similar and the ssl_ocsp_response command repeated to make Pen
239 re-read the file..
240 ssl_option OPTION
242 Manipulate SSL options. The available options are no_sslv2,
243 no_sslv3, no_tlsv1, no_tlsv1.1, no_tlsv1.2, cipher_server_pref‐
244 erence. Use the command multiple times to specify multiple
245 options.
246 ssl_sni_path PATH
248 This command enables the Server Name Indication TLS extension by
249 specifying a directory where domain.key, domain.crt and
250 domain.ca files can be found.
251 status Print status information in html format.
253 stubborn
255 If the initial server selection is unavailable, close the client
256 connection without trying another
257 no stubborn
259 tarpit_acl [N]
261 Used in DSR mode. If N is an existing access list, Pen will
262 reply to ARP requests for IP addresses that match the access
263 list, and reply with SYN+ACK to TCP SYN requests to these
264 addresses. The result is that someone trying to scan a network
265 will be slowed down by a large number of false positives.
266 tcp_fastclose up|down|both|off
268 Close both sockets to upstream and downstream if one of them
269 closes theirs. Default = off.
270 tcp_nodelay
272 Set TCP_NODELAY on sockets, effectively turning off the Nagle
273 algorithm.
274 no tcp_nodelay
276 Do not set TCP_NODELAY on sockets. This is the default.
277 timeout
279 Return current connect timeout in seconds.
280 timeout N
282 Set connect timeout to N seconds.
283 tracking N
285 Set tracking time, i.e. how long clients will be remembered. The
286 default 0 will never expire clients based on time.
287 transparent
289 On compatible platforms, use the client's address as source
290 address in the connection to the backend server.
291 no transparent
293 Use Pen's address as source address in the connection to the
294 backend server.
295 web_stats
297 Return file name of html status reports, if any.
298 web_stats FILE
300 Set the name of html status reports.
301 no web_stats
303 Do not generate html status reports.
304 weight Use weight for server selection.
306 no weight
308 Do not use weight for server selection.
309 write [FILE]
311 Write the current configuration into a file which can be used to
312 start pen. If FILE is omitted, the configuration is written into
313 pen's original configuration file.
314
317 pen(1)
318
321 Copyright (C) 2002-2015 Ulric Eriksson, <ulric@siag.nu>.
322 LOCAL PENCTL(1)