Configuration string Data Type

A word string is composed of one word, without any surrounding quotes, such as testing123. The purpose of the word is to simplify the configuration file syntax, so that quotation marks can be omitted when they are not strictly necessary. If the word contains a reference to another configuration directive, it is expanded, as with the double-quoted string, below.

A single-quoted string is a string that is surrounded by single quotes, such as 'hello there'. The purpose of the single-quoted string is to disable expansion of configuration directives, such as with '${foo}'.

The quotes allow the string to contain spaces, which are not allowed in the word form described in the previous section. The single quote character can be placed in such a string by escaping it with a backslash. All other escaping is disallowed.

The backslash character \ can be used to escape the single quote character inside of a string. Backslashes can be escaped by using two backslashes.

A double-quoted string is a string that is surrounded by double quotes, such as "hello there". A double-quoted string is interpreted via the usual rules in programming languages for double quoted strings. The double-quote character can be placed in a string by escaping it with a backslash. Carriage returns and line-feeds can also be used via the usual \r and \n syntax.

The main difference between the single and double quoted strings is that the double quoted strings can be dynamically expanded. The syntax ${…​} is used for parse-time expansion and %{…​} is used for run-time expansion. The difference between the two methods is that the ${…​} form is expanded when the server loads the configuration files and is valid anywhere in the configuration files. The %{…​} form is valid only in conditional expressions and attribute assignments and will otherwise cause a syntax error, and the server will refuse to start.

If the string contains a reference to another configuration directive, that string is expanded when the configuration file is parsed.

Some strings are expanded at run time. See the definition of the configuration directive to see if it undergoes such expansion. These strings are treated the same as the string type and do not have their own separate data type.

The back-quoted string performs run-time expansion similar to what is done with the Unix shell. The contents of the string are split into one or more sub-strings, based on intermediate whitespace. Each substring is then expanded as described above for double quoted strings. The resulting set of strings is used to execute a program with the associated arguments.

When the program is run, its output is recorded, and the resulting data is used in place of the input string value. Where the output is composed of multiple lines, any carriage returns and line feeds are replaced by spaces.

For safety reasons, the full path to the executed program should be given. In addition, the string is split into arguments prior to dynamic expansion in order to prevent the expanded strings from being erroneously interpreted as more command-line arguments.

For performance reasons, it is recommended that the use of back-quoted strings be kept to a minimum. Executing external programs is relatively expensive, and executing a large number of programs for every request can quickly use all of the CPU time in a server. If many programs need to be executed, it is suggested that alternative ways to achieve the same result be found. In some cases, using a real language may be sufficient.

This string is permitted only in conditional expressions and when assigning values to an attribute. In versions 2.1.11 and later, using this type of in an invalid context will return a syntax error, and the server will refuse to start. In versions of the server prior to 2.1.11, the data was treated as a single quoted string, and no run-time expansion or program execution was performed.