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 control 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
       command  to.   Here,  L,  S,  and  B  stand  for  the  identifiers  of  listener,  service  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 directory.  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 convenient 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 produce human-readable output,
       poundctl uses a template, i.e. a text written 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  .poundctl.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  configuration  file,  using  the  TemplatePath  statement of by setting the
       environment 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 "default".

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

       -v     Increases output verbosity level.

ENVIRONMENT

       POUNDCTL_CONF
              Alternative name for the default configuration file.  Unless absolute, 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-delimited list of directories  or  file
              names.   To  locate  the  template  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 directory 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 © 2002-2010 Apsis GmbH.
       Copyright © 2018-2025 Sergey Poznyakoff

       License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/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)