mirror of
https://github.com/graygnuorg/pound.git
synced 2026-10-23 22:28:53 +03:00
9d0c25bb0b
* NEWS: Document changes. * doc/pound.texi: Likewise. * doc/poundctl.8: Likewise. * src/config.c (rewrite_branch_prepare): Fix up location of the first rewrite block. * src/poundctl.c (command_trace): Treat missing argument as "/".
447 lines
13 KiB
Groff
447 lines
13 KiB
Groff
.\" Pound - the reverse-proxy load-balancer
|
|
.\" Copyright (C) 2002-2010 Apsis GmbH
|
|
.\" Copyright (C) 2018-2026 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 "September 8, 2026" "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]
|
|
[\fB\-W [\fBno\-]\fIFEATURE\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 locations,
|
|
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
|
|
.B core
|
|
Show core status: daemon PID, uptime, worker statistics, etc.
|
|
.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
|
|
\fBlog\fR [\fB/\fR]
|
|
Show global log level
|
|
.TP
|
|
\fBlog\fR \fB/\fIL\fR
|
|
Show log level configured for listener \fIL\fR.
|
|
.TP
|
|
\fBlog\fR \fB/\fR[\fIL\fR] \fIF\fR
|
|
Set log level \fIF\fR globally (if first argument is \fB/\fR) or for
|
|
the listener \fIL\fR.
|
|
.IP
|
|
\fIF\fR must be a symbolic name of a built-in format or a format
|
|
defined with the \fBLogFormat\fR configuration keyword.
|
|
.TP
|
|
\fBlog\fR -d [\fB/\fR\fIL\fR]
|
|
Delete (clear) log level settings. Without arguments, or with \fB/\fR
|
|
as an argument, clears global log level. This is equivalent to
|
|
setting it to \fBnull\fR. If the argument is \fB/\fIL\fR, log level
|
|
setting of the listener \fIL\fR is cleared, resulting in global log
|
|
level being applied to it.
|
|
.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.
|
|
.TP
|
|
\fBbeacon\fR [\fINAME\fR]
|
|
Examine the value of the beacon \fINAME\fR or all available beacons,
|
|
if no argument is given.
|
|
.IP
|
|
Beacons are special boolean values that can be used in conditional
|
|
statements in
|
|
.B pound.cfg
|
|
to assist in selecting the service to be used for each request. See
|
|
the subsection
|
|
.B Beacons
|
|
in
|
|
.BR pound (8),
|
|
for a detailed discussion.
|
|
.TP
|
|
\fBbeacon \-s \fINAME\fR
|
|
Set beacon \fINAME\fR to true.
|
|
.TP
|
|
\fBbeacon \-d \fINAME\fR
|
|
Set beacon \fINAME\fR to false.
|
|
.TP
|
|
\fBtrace\fR [\fB/\fIL\fR[\fB/\fIS\fR]]
|
|
Show trace state for the specified service. If \fIS\fR is omitted,
|
|
show trace states for all services defined in listener \fIL\fR. If
|
|
the argument is omitted, or is \fB/\fR, show states for all services.
|
|
.TP
|
|
\fBtrace -s \fR[\fB/\fIL\fR[\fB/\fIS\fR]]
|
|
Set trace state for the specified service or services. See above for
|
|
the interpretation of the argument.
|
|
.TP
|
|
\fBtrace -d \fR[\fB/\fIL\fR[\fB/\fIS\fR]]
|
|
Clear (delete) trace state for the specified service or services. See
|
|
above for the interpretation of the argument.
|
|
.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#\fR 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\fR][\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.
|
|
.TP
|
|
\fB\-W [\fBno\-]\fIFEATURE\fR
|
|
Enable or disable (if prefixed with \fBno\-\fR) additional \fBpound\fR
|
|
features. As of this version, the following \fIFEATURE\fRs are implemented:
|
|
.RS
|
|
.TP
|
|
.BI debug= LIST
|
|
Enable additional debugging. \fILIST\fR is a comma-delimited list of
|
|
keywords, each specifying the part of code to debug. Valid keywords
|
|
sections are:
|
|
.RS
|
|
.TP
|
|
.B ast
|
|
Additional information about processing of the abstract syntax
|
|
tree produced from the configuration file.
|
|
.TP
|
|
.B gram
|
|
Print grammar traces while processing the configuration.
|
|
.TP
|
|
.B lex
|
|
Print scanner traces while processing the configuration.
|
|
.RE
|
|
.TP
|
|
\fBinclude\-dir=\fIDIR\fR
|
|
Use \fIDIR\fR as the default include directory. See the discussion of
|
|
the \fBIncludeDir\fR directive in
|
|
.BR pound (8),
|
|
section
|
|
.BR "GLOBAL DIRECTIVES" .
|
|
.TP
|
|
.B no\-include\-dir
|
|
Don't set the include directory to the system configuration
|
|
directory. This means that each relative filename used in arguments
|
|
to the directives in the configuration file will be looked up in the
|
|
current working directory. This feature is useful mainly in
|
|
testsuite.
|
|
.RE
|
|
.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\(en2026 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-functions '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:
|