mirror of
https://github.com/graygnuorg/pound.git
synced 2026-10-28 11:35:07 +03:00
8f0228551b
* src/config.c (parse_listen_http) (parse_listen_https): Handle optional listener name. Make sure it is unique. (parse_service): Make sure service name is unique. * src/pound.h (LISTENER): New field: name. * src/poundctl.tmpl: Show listener name, if available. * svc.c (get_nth_listener, get_nth_service) (get_nth_backend,ctl_getnum): Remove. (IDENT): New data type. (ctl_getident,locate_listener,locate_service) (locate_backend): New functions. (service_serialize): Represent NULL service name as null. (listener_serialize): Add listener name. (ctl_service,ctl_listener): Identify objects by their ids or numbers. * NEWS: Document changes. * doc/pound.8: Likewise. * doc/poundctl.8: Likewise.
236 lines
7.0 KiB
Groff
236 lines
7.0 KiB
Groff
.\" Pound - the reverse-proxy load-balancer
|
|
.\" Copyright (C) 2002-2010 Apsis GmbH
|
|
.\" Copyright (C) 2018-2023 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 "March 3, 2023" "poundctl" "System Manager's Manual"
|
|
.SH NAME
|
|
poundctl \- control the pound daemon
|
|
.SH SYNOPSIS
|
|
.B poundctl
|
|
[\fB\-Vvh\fR]
|
|
[\fB\-f \fIFILE\fR]
|
|
[\fB\-i \fIN\fR]
|
|
[\fB\-j\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. The
|
|
.B pound.cfg
|
|
file must contain a
|
|
.B Control
|
|
statement for this to work. By default,
|
|
.B poundctl
|
|
will open the default
|
|
.B 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
|
|
.B \-f
|
|
command line option. Secondly, the socket name can be supplied in the
|
|
command line explicitly, using the
|
|
.B \-s
|
|
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 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 session with given key.
|
|
.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 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 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
|
|
.B \-T
|
|
command line option.
|
|
.PP
|
|
The default
|
|
.B poundctl.tmpl
|
|
file defines two templates: \fBdefault\fR and \fBxml\fR.
|
|
.SH OPTIONS
|
|
.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\-h\fR
|
|
Shows a short help output and exit.
|
|
.TP
|
|
\fB\-s \fISOCKET\fR
|
|
Sets control socket pathname.
|
|
.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 POUND_TMPL_PATH
|
|
Overrides the template search path. The value is a column-delimited
|
|
list of directories or file name. 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, 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-2023 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:
|