Variable References

Variable references act as macros. They allow something to be defined once, and then they allow the re-use of that definition in many places in the configuration.

Syntax
variable = "${reference}"

A variable reference causes the configuration file parser to expand the string when the configuration file is being parsed. This expansion is performed when the server loads and should be distinguished from the run-time expansion syntax, which is %{…​}.

Further expansion may be done at run time if the string also contains the dynamic expansion string %{…​}.

The data inside the ${…​} string must be a variable that exists in the configuration files. If the variable does not exist, a parse error is returned and the server will not start.

The reference can be any one of the following; the meanings are given below each example:

  • ${reference}

    • A reference to a named variable in the current section. If the variable does not exist, then the variable is looked for in the main (i.e., global) configuration.

  • ${.reference}

    • A reference to a named variable in the current section. The global configuration is not used.

  • ${..reference}

    • A reference to the named variable found in the parent section instead of the current section. Any number of dots (.) can be used, up to the global configuration.

  • ${reference1.reference2.reference3}

    • A reference to the section named reference1, which contains a subsection named reference2, which in turn contains a variable reference3. These references may be nested to any depth.

  • ${reference1[name].reference2}

    • A reference to a section named reference1, which has an instance called name, which in turn contains a variable reference2.

The above capabilities allow any portion of the configuration files to reference values taken from any other portion.

One additional expansion is supported.

  • $ENV{variable}

    • A reference to the environment variable named variable.

Examples:

foo = bar
baz = "${foo}" # assigns "bar" to "baz"
var = "a ${baz} string" # assigns "a bar string" to "var"
name = "${client[localhost].secret}"
ipaddr = $ENV{HOSTNAME}