poundctl - control the pound daemon

NAME SYNOPSIS DESCRIPTION TEMPLATES OPTIONS ENVIRONMENT SEE ALSO AUTHOR REPORTING BUGS COPYRIGHT

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 session with the given key. Notice that backend may not be specified.

add /L/S/B KEY

Add session with 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 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), 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, scanning stops and templates are read from that file.

Updated 2024-01-29 - jenkler.se | uex.se