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

FreeBSD Manual Pages

  
 
  

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

NAME
       penctl -	control	a running pen load balancer

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

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

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

       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  (de-
	      fault 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 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
	      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  (de-
	      fault 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.

       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 https://www.openssl.org/docs/apps/ciphers.html.

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

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

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

       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 ALSO
       pen(1)

AUTHOR
       Copyright (C) 2002-2015 Ulric Eriksson, <ulric@siag.nu>.

				     LOCAL			     PENCTL(1)

NAME | SYNOPSIS | EXAMPLE | DESCRIPTION | OPTIONS | COMMANDS | SEE ALSO | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=penctl&sektion=1&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help