10.3 poundctl template

Information received from the pound daemon 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. See Template syntax, for a detailed description.

Templates are stored in template files, which are looked up in the template search path. The path 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.

The default template path is

~/.poundctl.tmpl:datadir/pound

where datadir stands for the program data directory⁴. That is, the file .poundctl.tmpl in the user home directory is searched first, then the file poundctl.tmpl (without the leading dot) is looked up in the program data directory.

The default search path can be changed by setting the environment variable POUND_TMPL_PATH.

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’.