Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
PENCTL(1)		    General Commands Manual		     PENCTL(1)

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

	      Specifies	a control port where the  load	balancer  listens  for

	      Call abort() when	a fatal	error is encountered. This will	create
	      a	core file which	allows further	troubleshooting.  Disabled  by

       no abort_on_error
	      Exit  normally on	fatal error with an error code which indicates

       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

       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

       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.

	      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. Re-
	      turns 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.

	      Return  address  and  port where pen listens for control connec-

       control_acl N
	      Check accesses to	the control port against access	 list  N  (de-
	      fault 0).

       debug  Return current debug level.

       debug N
	      Set debug	level to N.

	      Always  wait for the next	round of the main loop before forward-
	      ing data.	Normally pen tries to do that immediately. This	is ob-
	      solete 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

       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

       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-

       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

       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

       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  (de-
	      fault 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  connec-
	      tions for	server N, or blacklist it for T	seconds.

	      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.

       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  de-
	      nial  of service vector. This command specifies the minimum num-
	      ber of seconds the client	has to wait between requests for rene-
	      gotiation	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  op-

       ssl_sni_path PATH
	      This command enables the Server Name Indication TLS extension by
	      specifying a directory  where  domain.key,  domain.crt  and  do- 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  re-
	      ply 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

       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 ad-
	      dress 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)


Want to link to this manual page? Use this URL:

home | help