3.12. template / process_template section

Configuration templates are reusable snippets of config lines. They are mainly used to avoid repeating common process settings.

syntax:

TEMPLATE_SECTION := ("template " | "process_template ") + TEMPLATE_NAME + "\n" + TEMPLATE_LINE*
TEMPLATE_NAME := NAME | NAME "(" ARGUMENT_DEF* ")"

example:

template shell_with_home(home_dir, cmd="")
environment: HOME=%(home_dir)
command: %(cmd)

process demo
use_template: shell_with_home("/tmp/demo", "echo hello")

Both section headers, template and process_template, are accepted by the parser and currently behave the same.

3.12.1. Template contents

The body of a template is not interpreted when the template is defined. Instead, its key: value lines are stored verbatim and replayed later when another configuration object uses the template via use_template: ....

This means a template can contain the same kinds of lines that the target object would normally accept. In practice this is primarily useful for process settings, but the mechanism itself is generic.

3.12.2. Template arguments

Templates may declare positional parameters:

template run_on(node_name, cmd)
node: %(node_name)
command: %(cmd)

Within the template body, occurrences of %(argument_name) are replaced by the bound argument values when the template is applied.

Default values are supported:

template shell_with_home(home_dir="/tmp", cmd="")

If a call provides fewer values than the template declares, the remaining parameters use their defaults.

3.12.3. Using templates

Templates are applied with use_template: .... This is documented in more detail in process section, but the important behavior is:

  • the referenced template name is resolved relative to the current push_name_prefix scope

  • applying a template replays its stored config lines as if they had been written directly at the point of use

  • later config lines can still overwrite settings introduced by a template

  • templates can be applied indirectly through add_process_default_template: ... directives or host-local add_process_default_template: ... host settings