1PENCTL(1)                   General Commands Manual                  PENCTL(1)
2
3
4

NAME

6       penctl - control a running pen load balancer
7
8

SYNOPSIS

10       penctl host:port|/path/to/socket command
11
12

EXAMPLE

14       penctl lbhost:8888 roundrobin
15
16       Turns off client tracking on the load balancer running on lbhost.
17
18       penctl /var/run/pen/tmp/ctrl status
19
20       Prints status information in html format.
21
22

DESCRIPTION

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
28       The  program  can also be used through the cgi script penctl.cgi, which
29       allows pen to be controlled from any web browser.
30
31

OPTIONS

33       host:port
34              Specifies a control port where the  load  balancer  listens  for
35              commands.
36
37

COMMANDS

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
44       no abort_on_error
45              Exit  normally on fatal error with an error code which indicates
46              failure.
47
48       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
53
54       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
60
61       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
66       no acl N
67              Deletes  all  entries  from  access list N. The resulting access
68              list permits all traffic.
69
70       ascii  Communication dumps in ascii format (cf option -a).
71
72       no ascii
73              Communication dumps in hex format.
74
75       blacklist
76              Return current blacklist time in seconds.
77
78       blacklist T
79              Set the blacklist time in seconds.
80
81       block  Do not make sockets nonblocking. This is obsolete as  of  0.26.0
82              and does nothing.
83
84       no block
85              Make sockets nonblocking.
86
87       client_acl N
88              Check connecting clients against access list N (default 0).
89
90       clients_max [N]
91              With  argument,  increase  the  maximum number of known clients.
92              Returns max number of clients.
93
94       close N
95              Close connection N
96
97       connection N
98              Display some basic information about connection N.
99
100       conn_max [N]
101              With argument, increase the max number of  simultaneous  connec‐
102              tions. Returns max number.
103
104       control
105              Return  address  and  port where pen listens for control connec‐
106              tions.
107
108       control_acl N
109              Check accesses  to  the  control  port  against  access  list  N
110              (default 0).
111
112       debug  Return current debug level.
113
114       debug N
115              Set debug level to N.
116
117       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
122       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
127       dsr_if IF
128              Use IF as the interface for Direct Server Return.
129
130       dummy  Act  as  a  dummy web server with very limited functionality but
131              high performance. Only useful for testing. Disabled by default.
132
133       no dummy
134              Do not act as a dummy web server.
135
136       epoll  Use epoll for event management (Linux).  This is the default  on
137              Linux.
138
139       exit   Exit. Only available if pen was started with the -X option.
140
141       hash   Use  a  hash  on the client IP address for initial server selec‐
142              tion.
143
144       no hash
145              Do not use a hash.
146
147       http   Add X-Forwarded-For headers to http requests.
148
149       no http
150              Do not add X-Forwarded-For headers.
151
152       idle_timeout N
153              Close connections that have been inactive for N seconds. Default
154              0 = never close.
155
156       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
161       include FILE
162              Read commands from file.
163
164       kqueue Use  kqueue  for  event  management  (FreeBSD, NetBSD, OpenBSD).
165              This is the default on the systems that have it.
166
167       listen Return local address and port pen listens to for incoming client
168              connections.
169
170       listen [address:]:port
171              Close  the  listening  socket and reopen using specified address
172              (optional) and port.
173
174       log    Show where pen is logging, if anywhere.
175
176       log FILE
177              Log to FILE.
178
179       mode   Write a summary of the current mode  of  operation.  The  listed
180              modes are block, delayed_forward, hash, roundrobin, stubborn.
181
182       no log Turn off logging.
183
184       pending_max N
185              Max  allowed  number of pending nonblocking connections. Default
186              100, minimum 1.
187
188       pid    Return the process id of the running daemon.
189
190       poll   Use poll for event management.
191
192       prio   Use the priority based algorithm.
193
194       no prio
195              Do not use the priority based algorithm.
196
197       recent [N]
198              Shows which  clients  have  connected  in  the  last  N  seconds
199              (default 300).
200
201       roundrobin
202              Use round-robin server selection without client tracking
203
204       no roundrobin
205
206
207       select Use select for event management.
208
209       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
214       servers
215              List  address, port, weight, priority and max number of simulta‐
216              neous connections for each remote server.
217
218       socket N
219              Show to which connection socket N belongs.
220
221       source IP
222              Set the local address to IP for upstream connections, i.e. where
223              Pen connects to backend servers.
224
225       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
229       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
235       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
241       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
247       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
252       status Print status information in html format.
253
254       stubborn
255              If the initial server selection is unavailable, close the client
256              connection without trying another
257
258       no stubborn
259
260       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
267       tcp_fastclose up|down|both|off
268              Close both sockets to upstream and downstream  if  one  of  them
269              closes theirs. Default = off.
270
271       tcp_nodelay
272              Set  TCP_NODELAY  on  sockets, effectively turning off the Nagle
273              algorithm.
274
275       no tcp_nodelay
276              Do not set TCP_NODELAY on sockets. This is the default.
277
278       timeout
279              Return current connect timeout in seconds.
280
281       timeout N
282              Set connect timeout to N seconds.
283
284       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
288       transparent
289              On  compatible  platforms,  use  the  client's address as source
290              address in the connection to the backend server.
291
292       no transparent
293              Use Pen's address as source address in  the  connection  to  the
294              backend server.
295
296       web_stats
297              Return file name of html status reports, if any.
298
299       web_stats FILE
300              Set the name of html status reports.
301
302       no web_stats
303              Do not generate html status reports.
304
305       weight Use weight for server selection.
306
307       no weight
308              Do not use weight for server selection.
309
310       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
315

SEE ALSO

317       pen(1)
318
319

AUTHOR

321       Copyright (C) 2002-2015 Ulric Eriksson, <ulric@siag.nu>.
322
323
324
325                                     LOCAL                           PENCTL(1)
Impressum