.\" Pound - the reverse-proxy load-balancer
.\" Copyright (C) 2002-2010 Apsis GmbH
.\" Copyright (C) 2018-2025 Sergey Poznyakoff
.\"
.\" Pound is free software; you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation; either version 3 of the License, or
.\" (at your option) any later version.
.\"
.\" Pound is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with pound.  If not, see <http://www.gnu.org/licenses/>.
.TH POUNDCTL 8 "January 2, 2025" "poundctl" "System Manager's Manual"
.SH NAME
poundctl \- control the pound daemon
.SH SYNOPSIS
.B poundctl
[\fB\-kVvh\fR]
[\fB\-C \fIFILE\fR]
[\fB\-f \fIFILE\fR]
[\fB\-i \fIN\fR]
[\fB\-j\fR]
[\fB\-K \fIFILE\fR]
[\fB\-S \fINAME\fR]
[\fB\-s \fISOCKET\fR]
[\fB\-T \fITEMPLATE-FILE\fR]
[\fB\-t \fITEMPLATE-NAME\fR]
\fICOMMAND\fR
[\fB/\fIL\fB/\fIS\fB/\fIB\fR]
[\fIARG\fR]
.SH DESCRIPTION
Displays status and controls various objects in the running instance
of
.BR pound (8)
proxy server.
.PP
The program communicates with the running
.BR pound
program via a UNIX \fIcontrol socket\fR, or remotely, via HTTP.  The
URL of the control socket is looked up in the following locatiions,
in that order:
.TP
.B ~/.poundctl
Main
.B poundctl
configuration file.
.TP
.B pound.cfg
The program scans it for a
.B Control
statement and obtains control socket name from it.
.TP
Argument of the 
.B \-s
command line option.
.PP
The \fICOMMAND\fR argument instructs the program what action it
is supposed to perform.  Missing \fICOMMAND\fR is equivalent to
.BR list .
All commands take the \fB/\fIL\fB/\fIS\fB/\fIB\fR argument, which
specifies the
.B pound
object to apply the command to.  Here, \fIL\fR, \fIS\fR, and \fIB\fR
stand for the identifiers of \fIlistener\fR, \fIservice\fR and
\fIbackend\fR, 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 \fIL\fR is \fB\-\fR, see below).
Symbolic names refer to the names assigned with the corresponding
.BR ListenHTTP ,
.BR ListenHTTPS ,
or
.B Service
statement in the configuration file.  The identifier \fIB\fR is
always numeric and refers to the ordinal number of the backend in
the service.
.PP
Depending on the command, either
\fIB\fR or both /\fIS\fR/\fIB\fR/ may be omitted.  For example,
the following command will disable backend 2 in service 1 of listener 0:
.PP
.EX
poundctl disable /0/1/2
.EE
.PP
In contrast, the following command disables the listener 0 itself:
.PP
.EX
poundctl disable /0
.EE
.PP
A dash in place of \fIL\fR stands for global scope.  Thus, e.g.:
.PP
.EX
poundctl disable /-/1
.EE
.PP
disables the service 1 defined in the global scope of
.BR pound.cfg .
.PP
The following commands are available:
.TP
\fBlist\fR \fB/\fIL\fB/\fIS\fB/\fIB\fR
List status of the given object and its subordinates.  Without
argument, shows all listeners and underlying objects.
.TP
\fBenable\fR \fB/\fIL\fB/\fIS\fB/\fIB\fR
Enable listener, service, or backend.
.TP
\fBon\fR \fB/\fIL\fB/\fIS\fB/\fIB\fR
Same as \fBenable\fR.
.TP
\fBdisable\fR \fB/\fIL\fB/\fIS\fB/\fIB\fR
Disable listener, service, or backend.
.TP
\fBoff\fR \fB/\fIL\fB/\fIS\fB/\fIB\fR
Same as \fBdisable\fR.
.TP
\fBdelete\fR \fB/\fIL\fB/\fIS\fR \fIKEY\fR
Delete the session with the given key.  Notice that backend may not be
specified.
.TP
\fBadd\fR \fB/\fIL\fB/\fIS\fB/\fIB\fR \fIKEY\fR
Add a session with the given key.
.SH CONFIGURATION
Configuration is read from file
.B .poundctl
located in the user home directory.  It is not an error if that file
does not exist.
.PP
Alternative location of the configuration file can be specified via
the
.B POUNDCTL_CONF
environment variable.  Setting that variable to an empty value
disables the configuration.
.PP
The file consists of simple statements and sections, delimited by any
amount of newlines.  Comments are introduced by \fB#\dR sign and
extend to the end of physical line where it appears.
.PP
Simple statements consist of a keyword and value separated by any
amount of whitespace.  Leading and trailing whitespace is ignored.
.PP
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
.B End
on a line by itself.
.PP
The following statements are defined:
.TP
\fBURL "\fIURL\fB"\fR
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).
.TP
\fBCAFile "\fIFILE\fB"\fR
Read certificate authority certificate from \fIFILE\fR.
.TP
\fBCAPath "\fIDIR\fB"\fR
Read certificate authority certificates from PEM files located in the
directory \fIDIR\fR.
.TP
\fBClientCert "\fIFILE\fB"\fR
Read client certificate and private key from \fIFILE\fR.  Use this if
.B pound
configuration requires client authentication using the
.B ClientCert
statement.
.TP
.BI Verify " bool"
Enables or disables peer certificate verification.  The default is
.BR on .
.TP
\fBTemplateFile "\fIFILE\fB"\fR
Name of the template file (see below).
.TP
\fBTemplateName "\fINAME\fB"\fR
Name of the template to use.
.TP
\fBTemplatePath "\fIFILE\fB"\fR
Search path for template files.
.PP
Multiple
.B Server
sections can appear in the file.  They provide a convenient way to
organize management of multiple \fBpound\fR servers.  You define the
settings for each remote \fBpound\fR servers (URL, etc.) in a separate
.B Server
section identified by a unique name.  Then, when you need to manage
that particular server, you identify it by using the
\fB\-S \fINAME\fR command line option.
.PP
Syntactically, each section is
.PP
.EX
Server "\fINAME\fR"
  \fI...\fR
End  
.EE
.PP
where ellipsis denotes one or more of the following statements:
.BR URL ,
.BR CAFile ,
.BR CAPath ,
.BR ClientCert ,
.BR Verify .
.SH TEMPLATES
Information received from
.B pound
is formatted as a JSON object.  To produce human-readable output,
.B poundctl
uses a
.IR 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
.BR poundctl.tmpl (5),
for a detailed description.
.PP
Templates are looked up in template file
.BR poundctl.tmpl .
This file is searched in template search path which is, by default,
the file \fB.poundctl.tmpl\fR in the user home directory and the
file \fBpoundctl.tmpl\fR (without the leading dot) in the \fIprogram
data directory\fR, normally \fB/usr/share/pound\fR.  The default
search path can be changed from configuration file, using the
.B TemplatePath
statement of by setting the
environment variable
.BR POUND_TMPL_PATH ,
which see.  To examine the default value of the search path, use the
.B \-V
command line option.
.PP
The template file to use can be requested
from the configuration file, via the \fBTemplateFile\fR statement, or
from the command line using the
.B \-t
option.  In this case, template search path in not searched and the
supplied file is used verbatim.
.PP
Unless instructed otherwise,
.B poundctl
uses the template "default".  You can request another template name
using the \fBTemplateName\fR configuration statement, or from command
line, using the
.B \-T
option.
.PP
The default
.B poundctl.tmpl
file defines two templates: \fBdefault\fR and \fBxml\fR.
.SH OPTIONS
.TP
\fB\-C \fIFILE\fR
Load certificate authority files from \fIFILE\fR.  \fIFILE\fR can also
be a directory containing CA certificates in PEM format.
.TP
\fB\-f \fIFILE\fR
Location of \fBpound\fR configuration file.
.TP
\fB\-i \fIN\fR
Sets indentation level for JSON output.
.TP
\fB\-j\fR
JSON output format.
.TP
\fB\-K \fIFILE\fR
Load client certificate and key from \fIFILE\fR and send them to the
server during handshake for authentication.
.TP
.B \-k
Disable peer verification.
.TP
\fB\-h\fR
Shows a short help output and exit.
.TP
\fB\-S \fINAME\fR
Operate on server defined in
.B .poundctl
file, section \fBServer \(dq\fINAME\fB\(dq\fR.
.TP
\fB\-s \fISOCKET\fR
Sets control socket pathname.  \fISOCKET\fR can also be a URL in the
form:
.IP
{\fBhttp\fR|\fBhttps\fR}\fB://\fR[\fIUSER\fR[\fB:\fIPASS\fR]\fB@\fR]\fIHOSTNAME\fR[\fB:\fIPORT\fT][\fB/\fIPATH\fR]
.IP
where \fB{|}\fR denote alternative forms and \fB[]\fR enclose optional parts.
.TP
\fB\-T \fITEMPLATE-FILE\fR
Sets the name of the template file to use.
.TP
\fB\-t \fITEMPLATE-NAME\fR
Defines the name of the template to use instead of the "default".
.TP
.B \-V
Print program version, compilation settings, and exit.
.TP
.B \-v
Increases output verbosity level.
.SH ENVIRONMENT
.TP
.B 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.
.TP
.B 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),
.B poundctl
tries to open that file.  If an element is a directory name,
the program tries to open the file
.B poundctl.tmpl
in that directory.  If opening succeeds, further scanning stops and templates
are read from that file.
.SH SEE ALSO
.BR pound (8),
.BR poundctl.tmpl (5).
.SH AUTHOR
Written by Robert Segall, Apsis GmbH, and Sergey Poznyakoff.
.SH "REPORTING BUGS"
Report bugs to <gray@gnu.org>.  You may also use github issue tracker
at https://github.com/graygnuorg/pound/issues.
.SH COPYRIGHT
Copyright \(co 2002-2010 Apsis GmbH.
.br
Copyright \(co 2018-2025 Sergey Poznyakoff
.sp
.na
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
.sp
.ad
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
.\" Local variables:
.\" eval: (add-hook 'write-file-hooks 'time-stamp)
.\" time-stamp-start: ".TH [A-Z_][A-Z0-9_.\\-]* [0-9] \""
.\" time-stamp-format: "%:B %:d, %:y"
.\" time-stamp-end: "\""
.\" time-stamp-line-limit: 20
.\" end: