Provided by: pen_0.34.1-1build1_amd64 bug


       penctl - control a running pen load balancer


       penctl host:port|/path/to/socket command


       penctl 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.


       Penctl  connects to the optional control socket on a pen load balancer.  It reads commands
       from the command line, performs minimal syntax checking 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.


              Specifies a control port where the load balancer listens for commands.


              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  notation.  If  mask  is  omitted,  it
              defaults to

       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-letter country code can
              be used to restrict access to the load balancer. 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

       ascii  Communication dumps in ascii format (cf option -a).

       no ascii
              Communication dumps in hex format.

              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

       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 connections. Returns max

              Return address and port where pen listens for control connections.

       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.

              Always wait for the next round of the main loop before  forwarding  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 copying 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 selection.

       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. Without 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).

              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 connections for server N, or
              blacklist it for T seconds.

              List address, port, weight, priority and max number of simultaneous connections for
              each remote server.

       socket N
              Show to which connection socket N belongs.

       source IP
              Set the local address to IP for upstream connections, i.e. where  Pen  connects  to
              backend servers.

       ssl_ciphers CIPHERS
              Choose  list  of  available  SSL  ciphers,  specified  in  the  format described in

       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_preference. 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 files can be found.

       status Print status information in html format.

              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.

              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.

              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.

              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.

              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.




       Copyright (C) 2002-2015 Ulric Eriksson, <>.

                                              LOCAL                                     PENCTL(1)