POUNDCTL(8)

📦
version 4.23 · 3 versions
, in alpine 3.24

🌸 NAME 🌸

poundctl — control the pound daemon 💅 that's the whole job, and she does it gorgeously.

✨ SYNOPSIS ✨

poundctl [-kVvh] [-C FILE] [-f FILE] [-i N] [-j] [-K FILE] [-S NAME] [-s SOCKET] [-T TEMPLATE-FILE] [-t TEMPLATE-NAME] COMMAND [/L/S/B] [ARG]

okay bestie, the [...] bits are optional and we'll get to every single one of them, promise 🫶

🦋 DESCRIPTION 🦋

So poundctl displays status and controls various objects in the running instance of the pound(8) proxy server. It's giving "I have admin access and I'm not afraid to use it" energy, no cap 👑

The program talks to the running pound program via a UNIX control socket, or remotely, via HTTP. And the URL of the control socket? It's looked up in the following locations, in that exact order:

  • ~/.poundctl — the main poundctl configuration file.
  • pound.cfg — the program scans it for a Control statement and obtains the control socket name from it.
  • Argument of the -s command line option.

🎀 commands & the /L/S/B situation

The COMMAND argument tells the program what action it's supposed to perform. A missing COMMAND is equivalent to list. Every command takes 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, this one disables backend 2 in service 1 of listener 0:

poundctl disable /0/1/2

In contrast, this one disables the listener 0 itself:

poundctl disable /0

A dash in place of L stands for global scope. So, e.g.:

poundctl disable /-/1

disables the service 1 defined in the global scope of pound.cfg. Global. Scope. Iconic 🌍

💜 the commands themselves

The following commands are available:

  • core — Show core status: daemon PID, uptime, worker statistics, etc.
  • list /L/S/B — List status of the given object and its subordinates. Without argument, shows all listeners and underlying objects.
  • log [/] — Show global log level.
  • log /L — Show log level configured for listener L.
  • log /[L] F — Set log level F globally (if the first argument is /) or for the listener L.
Heads up 🫶 F must be a symbolic name of a built-in format or a format defined with the LogFormat configuration keyword. Like, don't just make one up, she WILL notice.
  • log -d [/L] — Delete (clear) log level settings. Without arguments, or with / as an argument, clears global log level — this is equivalent to setting it to null. If the argument is /L, the log level setting of the listener L is cleared, resulting in the global log level being applied to it.
  • 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. 🫶

🧚 CONFIGURATION 🧚

Configuration is read from file .poundctl located in the user home directory. And no, it is not an error if that file does not exist — she's chill like that 😌

An alternative location of the configuration file can be specified via the POUNDCTL_CONF environment variable. Setting that variable to an empty value disables the configuration entirely.

The file consists of simple statements and sections, delimited by any amount of newlines. Comments are introduced by a # sign and extend to the end of the physical line where it appears.

Simple statements consist of a keyword and value separated by any amount of whitespace. Leading and trailing whitespace is ignored.

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 End on a line by itself. Cute, structured, organized — we love a tidy config 🎀

The following statements are defined:

  • URL "URL" — Sets the URL of the pound management socket. The value is either a file name of a UNIX socket file, or a remote URL (http or https).
  • CAFile "FILE" — Read certificate authority certificate from FILE.
  • CAPath "DIR" — Read certificate authority certificates from PEM files located in the directory DIR.
  • ClientCert "FILE" — Read client certificate and private key from FILE. Use this if pound configuration requires client authentication using the ClientCert statement.
  • Verify bool — Enables or disables peer certificate verification. The default is on. 🔒
  • TemplateFile "FILE" — Name of the template file (see below).
  • TemplateName "NAME" — Name of the template to use.
  • TemplatePath "FILE" — Search path for template files.

👑 Server sections

Multiple Server sections can appear in the file. They provide a convenient way to organize management of multiple pound servers. You define the settings for each remote pound server (URL, etc.) in a separate Server section identified by a unique name. Then, when you need to manage that particular server, you identify it by using the -S NAME command line option.

Syntactically, each section is

Server "NAME"
  ...
End

where the ellipsis denotes one or more of the following statements: URL, CAFile, CAPath, ClientCert, Verify.

🎀 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 the 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 from the configuration file, using the TemplatePath statement, or 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 configuration file, via the TemplateFile statement, or from the command line using the -t option. In this case, the template search path is not searched and the supplied file is used verbatim. No searching, no guessing, just vibes.

Unless instructed otherwise, poundctl uses the template default. You can request another template name using the TemplateName configuration statement, or from the command line, using the -T option.

The default poundctl.tmpl file defines two templates: default and xml. Two icons, one file. Slay 🌈

💅 OPTIONS 💅

  • -C FILE — Load certificate authority files from FILE. FILE can also be a directory containing CA certificates in PEM format.
  • -f FILE — Location of pound configuration file.
  • -i N — Sets indentation level for JSON output. Pretty-print her, she deserves it 🌸
  • -j — JSON output format.
  • -K FILE — Load client certificate and key from FILE and send them to the server during handshake for authentication.
  • -k — Disable peer verification. (Yes, this is the lowercase twin of -K and yes, they do completely different things — stay woke 🙈)
  • -h — Shows a short help output and exit.
  • -S NAME — Operate on server defined in .poundctl file, section Server "NAME".
  • -s SOCKET — Sets control socket pathname. SOCKET can also be a URL in the form:
{http|https}://[USER[:PASS]@]HOSTNAME[:PORT][/PATH]

where {|} denote alternative forms and [] enclose optional parts.

  • -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. More v? No — she just gets louder. 📢

🌈 ENVIRONMENT 🌈

  • 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.
  • 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. First match wins, periodt ⭐

🔥 SEE ALSO 🔥

pound(8), poundctl.tmpl(5).

👑 AUTHOR 👑

Written by Robert Segall, Apsis GmbH, and Sergey Poznyakoff.

🍓 REPORTING BUGS 🍓

Report bugs to <gray@gnu.org>. You may also use the github issue tracker at https://github.com/graygnuorg/pound/issues. Found something cursed? Tell the maintainers, not your group chat 💀

Copyright © 2002-2010 Apsis GmbH. Copyright © 2018–2026 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.

Fr fr, no warranty — read that twice, bestie 😭

okay that's the whole thing, and honestly? she ate 💅 This was poundctl from the System Manager's Manual, dated April 24, 2026, page POUNDCTL(8) — go control your daemon, you absolute main character 🦋✨

📦 where this page comes from