Ubuntu Manpage: poundctl - control the pound daemon

NAME

       poundctl - control the pound daemon

SYNOPSIS

       poundctl  [-Vvh] [-f FILE] [-i N] [-j] [-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. The pound.cfg file
must contain a Control statement for this to work. By default, poundctl will open the default pound.cfg
file, look up for this statement and use the pathname defined by it as the control socket file. This can
be altered in two ways. First, if using the configuration file in a non-standard location, the pathname
of this file can be given to the program using the -f command line option. Secondly, the socket name can
be supplied in the command line explicitly, using the -s 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.

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 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 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 -T command line option.

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

OPTIONS

       -f FILE
              Location of pound configuration file.

       -i N   Sets indentation level for JSON output.

       -j     JSON output format.

       -h     Shows a short help output and exit.

       -s SOCKET
              Sets control socket pathname.

       -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

       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.

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-2024 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                                        February 21, 2024                                    POUNDCTL(8)