Formats (Cfpeek User Manual)

4 Supported Configuration File Formats

Cfpeek is able to handle input files in several formats. The supported formats differ mostly in syntax. This chapter describes them in detail. If you know of any free software which uses a structured configuration file not understood by cfpeek, please let us know (see Reporting Bugs).

4.1 Grecs Configuration File

This is the default input format. It is used, e.g., by GNU Dico¹, GNU Mailutils², GNU Radius³, Mailfromd⁴ and others.

The configuration file consists of statements and comments.

There are three classes of lexical tokens: keywords, values, and separators. Blanks, tabs, newlines and comments, collectively called white space are ignored except as they serve to separate tokens. Some white space is required to separate otherwise adjacent keywords and values.

4.1.1 Comments

Comments may appear anywhere where white space may appear in the configuration file. There are two kinds of comments: single-line and multi-line comments. Single-line comments start with ‘#’ or ‘//’ and continue to the end of the line:

# This is a comment
// This too is a comment

Multi-line or C-style comments start with the two characters ‘/*’ (slash, star) and continue until the first occurrence of ‘*/’ (star, slash).

Multi-line comments cannot be nested. However, single-line comments may well appear within multi-line ones.

4.1.2 Pragmatic Comments

Pragmatic comments are similar to usual single-line comments, except that they cause some changes in the way the configuration is parsed. Pragmatic comments begin with a ‘#’ sign and end with the next physical newline character.

#include <file>

#include file

Include the contents of the file file. There are three possible use cases.

If file is an absolute file name, the named file is included. An error message will be issued if it does not exist.

If file contains wildcard characters (‘*’, ‘[’, ‘]’ or ‘?’), it is interpreted as shell globbing pattern and all files matching that pattern are included, in lexicographical order. If no files match the pattern, the statement is silently ignored.

Otherwise, the form with angle brackets searches for file in the include search path, while the second one looks for it in the current working directory first, and, if not found there, in the include search path. If the file is not found, an error message will be issued.

The default include search path is:

prefix/share/program-name/1.2/include
prefix/share/program-name/include

where prefix is the installation prefix.

#include_once <file>

#include_once file

Same as #include, except that, if the file has already been included, it will not be included again.

#line num

#line num "file"

This line causes the parser to believe, for purposes of error diagnostics, that the line number of the next source line is given by num and the current input file is named by file. If the latter is absent, the remembered file name does not change.

# num "file"

This is a special form of #line statement, understood for compatibility with the C preprocessor.

In fact, these statements provide a rudimentary preprocessing features. For more sophisticated ways to modify configuration before parsing, see Preprocessor.

4.1.3 Statements

A simple statement consists of a keyword and value separated by any amount of whitespace. Simple statement is terminated with a semicolon (‘;’).

The following is a simple statement:

standalone yes;
pidfile /var/run/slb.pid;

A keyword begins with a letter and may contain letters, decimal digits, underscores (‘_’) and dashes (‘-’). Examples of keywords are: ‘expression’, ‘output-file’.

A value can be one of the following:

number

A number is a sequence of decimal digits.

boolean

A boolean value is one of the following: ‘yes’, ‘true’, ‘t’ or ‘1’, meaning true, and ‘no’, ‘false’, ‘nil’, ‘0’ meaning false.

unquoted string

An unquoted string may contain letters, digits, and any of the following characters: ‘_’, ‘-’, ‘.’, ‘/’, ‘@’, ‘*’, ‘:’.

quoted string

A quoted string is any sequence of characters enclosed in double-quotes (‘"’). A backslash appearing within a quoted string introduces an escape sequence, which is replaced with a single character according to the following rules:

Sequence	Replaced with
\a	Audible bell character (ASCII 7)
\b	Backspace character (ASCII 8)
\f	Form-feed character (ASCII 12)
\n	Newline character (ASCII 10)
\r	Carriage return character (ASCII 13)
\t	Horizontal tabulation character (ASCII 9)
\v	Vertical tabulation character (ASCII 11)
\\	A single backslash (‘`\`’)
\"	A double-quote.

Table 4.1: Backslash escapes

In addition, the sequence ‘\newline’ is removed from the string. This allows to split long strings over several physical lines, e.g.:

"a long string may be\
 split over several lines"

If the character following a backslash is not one of those specified above, the backslash is ignored and a warning is issued.

Here-document

A here-document is a special construct that allows to introduce strings of text containing embedded newlines.

The <<word construct instructs the parser to read all the following lines up to the line containing only word, with possible trailing blanks. Any lines thus read are concatenated together into a single string. For example:

<<EOT
A multiline
string
EOT

The body of a here-document is interpreted the same way as a double-quoted string, unless word is preceded by a backslash (e.g. ‘<<\EOT’) or enclosed in double-quotes, in which case the text is read as is, without interpretation of escape sequences.

If word is prefixed with - (a dash), then all leading tab characters are stripped from input lines and the line containing word. Furthermore, if - is followed by a single space, all leading whitespace is stripped from them. This allows to indent here-documents in a natural fashion. For example:

<<- TEXT
    The leading whitespace will be
    ignored when reading these lines.
TEXT

It is important that the terminating delimiter be the only token on its line. The only exception to this rule is allowed if a here-document appears as the last element of a statement. In this case a semicolon can be placed on the same line with its terminating delimiter, as in:

help-text <<-EOT
        A sample help text.
EOT;

list

A list is a comma-separated list of values. Lists are enclosed in parentheses. The following example shows a statement whose value is a list of strings:

alias (test,null);

In any case where a list is appropriate, a single value is allowed without being a member of a list: it is equivalent to a list with a single member. This means that, e.g.

alias test;

is equivalent to

alias (test);

A block statement introduces a logical group of statements. It consists of a keyword, followed by an optional value, and a sequence of statements enclosed in curly braces, as shown in the example below:

server srv1 {
  host 10.0.0.1;
  community "foo";
}

The closing curly brace may be followed by a semicolon, although this is not required.

4.1.4 Preprocessor

Before actual parsing, the configuration file is preprocessed. The built-in preprocessor handles only file inclusion and #line statements (see Pragmatic Comments), while the rest of traditional preprocessing facilities, such as macro expansion, is supported via m4, which serves as external preprocessor.

The detailed description of m4 facilities lies far beyond the scope of this document. You will find a complete user manual in http://www.gnu.org/software/m4/manual. For the rest of this subsection we assume the reader is sufficiently acquainted with m4 macro processor.

The external preprocessor is invoked with -s flag, which instructs it to include line synchronization information in its output. This information is then used by the parser to display meaningful diagnostic.

An initial set of macro definitions is supplied by the pp-setup file, located in prefix/share/program-name/1.2/include directory.

The default pp-setup file renames all m4 built-in macro names so they all start with the prefix ‘m4_’. This is similar to GNU m4 --prefix-builtin option, but has an advantage that it works with non-GNU m4 implementations as well.

4.2 Path Configuration File

A pathname configuration file format corresponds exactly to the default output format of cfpeek, i.e. it lists each terminal keyword as its full pathname, followed by a semicolon, a single space and its value, as in the example below:

.user: "smith"
.group: "mail"
.pidfile: "/var/run/example"
.logging.facility: "daemon"
.logging.tag: "example"
.program="a".command: "a.out"
.program="a".logging.facility: "local0"
.program="a".logging.tag: "a"
.program="b".command: "b.out"
.program="b".wait: "yes"
.program="b".pidfile: "/var/run/b.pid"

This format is similar to the one used in X-resources.

4.3 BIND Configuration File

This is the format used by the ISC BIND configuration files. In general, it is pretty similar to the ‘Grecs’, except that it does not support neither here-documents, not list values. Some of its features, such as ‘acls’ and ‘allow-*’ lists do resemble lists, but are not them in reality. Such “suspicious” statements are represented as simple statements. For example, the following statement in named.conf:

allow-transfer {
    allow-dns;
    !10.10.10.1;
    10.10.10.0/8;
};

.allow-transfer.allow-dns:
.allow-transfer.!: "10.10.10.1"
.allow-transfer."10.10.10.0/8":

Another exception is the ‘controls’ statement, which doesn’t fall well into the general syntax of BIND configuration file. Therefore a special rule is applied to handle it. In the effect, the following statement:

controls {
    inet 127.0.0.1 port 953
        allow { 127.0.0.1; 127.0.0.2; } keys { "rndc-key"; };
};

produces

.controls: (inet, 127.0.0.1, port, 953, allow, \
              (127.0.0.1, 127.0.0.2), keys, (rndc-key))

4.4 DHCPD Configuration File

This is the format used by the ISC DHCPD configuration files (/etc/dhcpd.conf and any files it might include). It is very similar to ‘Bind’, with some minor differences:

Block statements do not end with a semicolon.
Tags or values can contain lists of quoted strings delimited by commas.

4.5 MeTA1 Configuration File

This type of configuration file is used by MeTA1, an advanced MTA program. See http://www.meta1.org for details about the program and its configuration.

The syntax is similar to both ‘Grecs’ and ‘Bind’ in that it uses curly braces to delimit subordinate statements. The syntax for strings is similar to ‘Grecs’ (see quoted string). As in ‘Grecs’, adjacent quoted strings are concatenated to produce a single string.

The principal syntactic differences are:

Only ‘#’ comments are understood.
An equal sign is required between identifier and value in simple statements, e.g.:
```
log_level = 12;
```
List values are enclosed in curly braces.
Here-document is not supported.

4.6 GIT Configuration File

This is the format used by Git (http://git-scm.com). It is described in detail in http://www.kernel.org/pub/software/scm/git/docs/git-config.html.

The syntax is line-oriented. Comments are introduced by ‘#’ or ‘;’ character and extend up to the next physical newline. Statements are delimited by newlines.

The syntax for simple statement is:

ident = value

Compound statements or sections begin with a section header, i.e. a full pathname of that section using single space as a separator and enclosed in a pair of square brackets. Any identifier in the path which contains whitespace characters must be quoted using double quotes. Double quotes and backslashes appearing in a section name must be escaped as ‘\"’ and ‘\\’ correspondingly. For example:

[section "subsection name" subsubsection]

An alternative syntax for section headers is a full pathname of the section using single dot as a separator and enclosed in a pair of square brackets. When this syntax is used, whitespace is not allowed in section names:

[section.subsection.subsubsection]

A section begins with the section headers and continues until the start of next section or end of file, whichever occurs first.

Simple statements must occur only within a section. In other words, each non-empty configuration file must contain at least one section.

String values may be entirely or partially enclosed in double quotes, similarly to shell syntax. The following escape sequences are recognized within a value:

Sequence	Stands for
‘`\"`’	‘`"`’
‘`\\`’	‘`\`’
‘`\b`’	Backspace (ASCII 8)
‘`\t`’	Horizontal tab (ASCII 9)
‘`\n`’	Newline (ASCII 10)

A backslash immediately preceding a newline indicates line continuation. Both characters are removed and the remaining characters are joined with line that follows.

Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved.

CFPEEK