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

FreeBSD Manual Pages

  
 
  

home | help
POUNDCTL(8)		    System Manager's Manual		   POUNDCTL(8)

NAME
       poundctl	- control the pound daemon

SYNOPSIS
       poundctl	 [-kVvh]  [-C  FILE] [-f FILE] [-i N] [-j] [-K FILE] [-S NAME]
       [-s SOCKET] [-T	TEMPLATE-FILE]	[-t  TEMPLATE-NAME]  COMMAND  [/L/S/B]
       [ARG]

DESCRIPTION
       Displays	status and controls various objects in the running instance of
       pound(8)	proxy server.

       The program communicates	with the running pound program via a UNIX con-
       trol  socket,  or remotely, via HTTP.  The URL of the control socket is
       looked up in the	following locatiions, in that order:

       ~/.poundctl
	      Main poundctl configuration file.

       pound.cfg
	      The program scans	it for a Control statement and obtains control
	      socket name from it.

       Argument	of the
	      -s command line option.

       The COMMAND argument instructs the program what action it  is  supposed
       to  perform.  Missing COMMAND is	equivalent to list.  All commands take
       the /L/S/B argument, which specifies the	pound object to	apply the com-
       mand to.	 Here, L, S, and B stand for the identifiers of	listener, ser-
       vice and	backend, correspondingly.  For listeners  and  services,  both
       numeric identifiers or symbolic names are allowed.  Numeric identifiers
       refer  to the ordinal number of the listener in the configuration file,
       or service within the enclosing listener	(or in the configuration file,
       if L is -, see below).  Symbolic	names refer to the names assigned with
       the corresponding ListenHTTP, ListenHTTPS, or Service statement in  the
       configuration  file.   The identifier B is always numeric and refers to
       the ordinal number of the backend in the	service.

       Depending on the	command, either	B or both /S/B/	may be	omitted.   For
       example,	 the  following	command	will disable backend 2 in service 1 of
       listener	0:

       poundctl	disable	/0/1/2

       In contrast, the	following command disables the listener	0 itself:

       poundctl	disable	/0

       A dash in place of L stands for global scope.  Thus, e.g.:

       poundctl	disable	/-/1

       disables	the service 1 defined in the global scope of pound.cfg.

       The following commands are available:

       list /L/S/B
	      List status of the given object and its  subordinates.   Without
	      argument,	shows all listeners and	underlying objects.

       enable /L/S/B
	      Enable listener, service,	or backend.

       on /L/S/B
	      Same as enable.

       disable /L/S/B
	      Disable listener,	service, or backend.

       off /L/S/B
	      Same as disable.

       delete /L/S KEY
	      Delete  the session with the given key.  Notice that backend may
	      not be specified.

       add /L/S/B KEY
	      Add a session with the given key.

CONFIGURATION
       Configuration is	read from file .poundctl located in the	user home  di-
       rectory.	 It is not an error if that file does not exist.

       Alternative location of the configuration file can be specified via the
       POUNDCTL_CONF  environment variable.  Setting that variable to an empty
       value disables the configuration.

       The file	consists of simple statements and sections, delimited  by  any
       amount  of  newlines.  Comments are introduced by #R sign and extend to
       the end of physical line	where it appears.

       Simple statements consist of a  keyword	and  value  separated  by  any
       amount of whitespace.  Leading and trailing whitespace is ignored.

       Sections	 begin	with  a	 keyword  and value separated by any amount of
       whitespace as well.  They are followed by a newline and any  number  of
       statements  belonging to	that section.  Sections	end with a word	End on
       a line by itself.

       The following statements	are defined:

       URL "URL"
	      Sets the URL of  the  @command{pound}  management	 socket.   The
	      value  is	 either	a file name of a UNIX socket file, or a	remote
	      URL (http	or https).

       CAFile "FILE"
	      Read certificate authority certificate from FILE.

       CAPath "DIR"
	      Read certificate authority certificates from PEM	files  located
	      in the directory DIR.

       ClientCert "FILE"
	      Read  client certificate and private key from FILE.  Use this if
	      pound configuration requires  client  authentication  using  the
	      ClientCert statement.

       Verify bool
	      Enables  or disables peer	certificate verification.  The default
	      is on.

       TemplateFile "FILE"
	      Name of the template file	(see below).

       TemplateName "NAME"
	      Name of the template to use.

       TemplatePath "FILE"
	      Search path for template files.

       Multiple	Server sections	can appear in the file.	 They provide a	conve-
       nient way to organize management	of multiple pound servers.  You	define
       the settings for	each remote pound servers (URL,	etc.)  in  a  separate
       Server  section	identified  by	a unique name.	Then, when you need to
       manage that particular server, you identify it by  using	 the  -S  NAME
       command line option.

       Syntactically, each section is

       Server "NAME"
	 ...
       End

       where  ellipsis	denotes	 one or	more of	the following statements: URL,
       CAFile, CAPath, ClientCert, Verify.

TEMPLATES
       Information received from pound is formatted as a JSON object.  To pro-
       duce human-readable output, poundctl uses a template, i.e. a text writ-
       ten in a	domain-specific	language expressly designed for	that  purpose.
       The  template  language complies, in general, with the specification in
       <https://pkg.go.dev/text/template>.  Refer to poundctl.tmpl(5),	for  a
       detailed	description.

       Templates  are  looked up in template file poundctl.tmpl.  This file is
       searched	in template search path	which is, by default, the file .pound-
       ctl.tmpl	in the user home directory and the file	poundctl.tmpl (without
       the  leading   dot)   in	  the	program	  data	 directory,   normally
       /usr/share/pound.  The default search path can be changed from configu-
       ration  file,  using the	TemplatePath statement of by setting the envi-
       ronment variable	POUND_TMPL_PATH, which see.  To	 examine  the  default
       value of	the search path, use the -V command line option.

       The  template file to use can be	requested from the configuration file,
       via the TemplateFile statement, or from the command line	using  the  -t
       option.	 In  this  case,  template search path in not searched and the
       supplied	file is	used verbatim.

       Unless instructed otherwise, poundctl uses the template "default".  You
       can request another template name using the TemplateName	 configuration
       statement, or from command line,	using the -T option.

       The default poundctl.tmpl file defines two templates: default and xml.

OPTIONS
       -C FILE
	      Load  certificate	authority files	from FILE.  FILE can also be a
	      directory	containing CA certificates in PEM format.

       -f FILE
	      Location of pound	configuration file.

       -i N   Sets indentation level for JSON output.

       -j     JSON output format.

       -K FILE
	      Load client certificate and key from FILE	and send them  to  the
	      server during handshake for authentication.

       -k     Disable peer verification.

       -h     Shows a short help output	and exit.

       -S NAME
	      Operate  on  server  defined  in	.poundctl file,	section	Server
	      "NAME".

       -s SOCKET
	      Sets control socket pathname.  SOCKET can	also be	a URL  in  the
	      form:

	      {http|https}://[USER[:PASS]@]HOSTNAME[:PORT][/PATH]

	      where  {|}  denote  alternative  forms  and  [] enclose optional
	      parts.

       -T TEMPLATE-FILE
	      Sets the name of the template file to use.

       -t TEMPLATE-NAME
	      Defines the name of the template to  use	instead	 of  the  "de-
	      fault".

       -V     Print program version, compilation settings, and exit.

       -v     Increases	output verbosity level.

ENVIRONMENT
       POUNDCTL_CONF
	      Alternative name for the default configuration file.  Unless ab-
	      solute,  the file	is searched in the user	home directory.	 Empty
	      value restores built-in defaults.

       POUND_TMPL_PATH
	      Overrides	the template search path.  The value is	 a  column-de-
	      limited  list  of	directories or file names.  To locate the tem-
	      plate file, the path is scanned left-to right.  If an element is
	      a	regular	file name (or a	hard or	symbolic  link	to  a  regular
	      file), poundctl tries to open that file.	If an element is a di-
	      rectory  name,  the program tries	to open	the file poundctl.tmpl
	      in that directory.  If opening succeeds, further scanning	 stops
	      and templates are	read from that file.

SEE ALSO
       pound(8), poundctl.tmpl(5).

AUTHOR
       Written by Robert Segall, Apsis GmbH, and Sergey	Poznyakoff.

REPORTING BUGS
       Report  bugs  to	<gray@gnu.org>.	 You may also use github issue tracker
       at https://github.com/graygnuorg/pound/issues.

COPYRIGHT
       Copyright (C) 2002-2010 Apsis GmbH.
       Copyright (C) 2018-2025 Sergey Poznyakoff

       License GPLv3+: GNU GPL version 3 or later <http://gnu.org/li-
       censes/gpl.html>

       This is free software: you are free  to	change	and  redistribute  it.
       There is	NO WARRANTY, to	the extent permitted by	law.

poundctl			January	2, 2025			   POUNDCTL(8)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=poundctl&sektion=8&manpath=FreeBSD+Ports+14.3.quarterly>

home | help