PENCTL(1)PENCTL(1)NAMEpenctl - control a running pen load balancer
SYNOPSISpenctl host:port|/path/to/socket command
EXAMPLEpenctl lbhost:8888 roundrobin
Turns off client tracking on the load balancer running on lbhost.
penctl /var/run/pen/tmp/ctrl status
Prints status information in html format.
DESCRIPTION
Penctl connects to the optional control socket on a pen load balancer.
It reads commands from the command line, performs minimal syntax check‐
ing and sends them to pen. Replies, if any, are printed on stdout.
The program can also be used through the cgi script penctl.cgi, which
allows pen to be controlled from any web browser.
OPTIONS
host:port
Specifies a control port where the load balancer listens for
commands.
COMMANDS
abort_on_error
Call abort() when a fatal error is encountered. This will create
a core file which allows further troubleshooting. Disabled by
default.
no abort_on_error
Exit normally on fatal error with an error code which indicates
failure.
acl N permit|deny sourceip4 [mask]
Adds an entry to access list N, where N is a number from 0 to 9.
The source and mask addresses are in the usual dotted quad nota‐
tion. If mask is omitted, it defaults to 255.255.255.255.
acl N permit|deny sourceip6[/length]
If the source address contains the character ':', the address is
interpreted as IPv6. Unlike IPv4 access entries, a length is
used to indicate the mask. If length is omitted, it defaults to
128.
acl N permit|deny country NN
If the source address is the special word "country", a two-let‐
ter country code can be used to restrict access to the load bal‐
ancer. For this to work, pen must be built with geoip support.
no acl N
Deletes all entries from access list N. The resulting access
list permits all traffic.
ascii Communication dumps in ascii format (cf option -a).
no ascii
Communication dumps in hex format.
blacklist
Return current blacklist time in seconds.
blacklist T
Set the blacklist time in seconds.
block Do not make sockets nonblocking. This is obsolete as of 0.26.0
and does nothing.
no block
Make sockets nonblocking.
client_acl N
Check connecting clients against access list N (default 0).
clients_max [N]
With argument, increase the maximum number of known clients.
Returns max number of clients.
close N
Close connection N
connection N
Display some basic information about connection N.
conn_max [N]
With argument, increase the max number of simultaneous connec‐
tions. Returns max number.
control
Return address and port where pen listens for control connec‐
tions.
control_acl N
Check accesses to the control port against access list N
(default 0).
debug Return current debug level.
debug N
Set debug level to N.
delayed_forward
Always wait for the next round of the main loop before forward‐
ing data. Normally pen tries to do that immediately. This is
obsolete as of 0.26.0 and does nothing.
no delayed_forward
Try to forward data immediately, to avoid the overhead of copy‐
ing it to a temporary buffer and waiting for the next main loop
round.
dsr_if IF
Use IF as the interface for Direct Server Return.
dummy Act as a dummy web server with very limited functionality but
high performance. Only useful for testing. Disabled by default.
no dummy
Do not act as a dummy web server.
epoll Use epoll for event management (Linux). This is the default on
Linux.
exit Exit. Only available if pen was started with the -X option.
hash Use a hash on the client IP address for initial server selec‐
tion.
no hash
Do not use a hash.
http Add X-Forwarded-For headers to http requests.
no http
Do not add X-Forwarded-For headers.
idle_timeout N
Close connections that have been inactive for N seconds. Default
0 = never close.
idlers [N]
Create N reliable idle connections to the backend servers. With‐
out argument, display the current/requested number of reliable
idlers.
include FILE
Read commands from file.
kqueue Use kqueue for event management (FreeBSD, NetBSD, OpenBSD).
This is the default on the systems that have it.
listen Return local address and port pen listens to for incoming client
connections.
listen [address:]:port
Close the listening socket and reopen using specified address
(optional) and port.
log Show where pen is logging, if anywhere.
log FILE
Log to FILE.
mode Write a summary of the current mode of operation. The listed
modes are block, delayed_forward, hash, roundrobin, stubborn.
no log Turn off logging.
pending_max N
Max allowed number of pending nonblocking connections. Default
100, minimum 1.
pid Return the process id of the running daemon.
poll Use poll for event management.
prio Use the priority based algorithm.
no prio
Do not use the priority based algorithm.
recent [N]
Shows which clients have connected in the last N seconds
(default 300).
roundrobin
Use round-robin server selection without client tracking
no roundrobin
select Use select for event management.
server N [ acl A |�address A | port P | max M | hard H | blacklist T |
weight W | prio P ]
Change acl, address, port, weight, priority and/or max connec‐
tions for server N, or blacklist it for T seconds.
servers
List address, port, weight, priority and max number of simulta‐
neous connections for each remote server.
socket N
Show to which connection socket N belongs.
ssl_ciphers CIPHERS
Choose list of available SSL ciphers, specified in the format
described in https://www.openssl.org/docs/apps/ciphers.html.
ssl_client_renegotiation_interval S
Allowing the client to request renegotiation is a potential
denial of service vector. This command specifies the minimum
number of seconds the client has to wait between requests for
renegotiation requests. Default 3600 = effectively disabled.
ssl_ocsp_response FILENAME
Specifies the location of a file containing a pre-fetched OCSP
response. The file must be refreshed regularly by a cron job or
similar and the ssl_ocsp_response command repeated to make Pen
re-read the file..
ssl_option OPTION
Manipulate SSL options. The available options are no_sslv2,
no_sslv3, no_tlsv1, no_tlsv1.1, no_tlsv1.2, cipher_server_pref‐
erence. Use the command multiple times to specify multiple
options.
ssl_sni_path PATH
This command enables the Server Name Indication TLS extension by
specifying a directory where domain.key, domain.crt and
domain.ca files can be found.
status Print status information in html format.
stubborn
If the initial server selection is unavailable, close the client
connection without trying another
no stubborn
tarpit_acl [N]
Used in DSR mode. If N is an existing access list, Pen will
reply to ARP requests for IP addresses that match the access
list, and reply with SYN+ACK to TCP SYN requests to these
addresses. The result is that someone trying to scan a network
will be slowed down by a large number of false positives.
tcp_fastclose up|down|both|off
Close both sockets to upstream and downstream if one of them
closes theirs. Default = off.
tcp_nodelay
Set TCP_NODELAY on sockets, effectively turning off the Nagle
algorithm.
no tcp_nodelay
Do not set TCP_NODELAY on sockets. This is the default.
timeout
Return current connect timeout in seconds.
timeout N
Set connect timeout to N seconds.
tracking N
Set tracking time, i.e. how long clients will be remembered. The
default 0 will never expire clients based on time.
transparent
On compatible platforms, use the client's address as source
address in the connection to the backend server.
no transparent
Use Pen's address as source address in the connection to the
backend server.
web_stats
Return file name of html status reports, if any.
web_stats FILE
Set the name of html status reports.
no web_stats
Do not generate html status reports.
weight Use weight for server selection.
no weight
Do not use weight for server selection.
write [FILE]
Write the current configuration into a file which can be used to
start pen. If FILE is omitted, the configuration is written into
pen's original configuration file.
SEE ALSOpen(1)AUTHOR
Copyright (C) 2002-2015 Ulric Eriksson, <ulric@siag.nu>.
LOCAL PENCTL(1)
