Dconf file format

Dconf is a proprietary configuration file format used in the operation of an Apcera cluster, including cluster.conf files, application manifests, and package scripts. This document describes the format of a dconf file.

Overview

The basic format of a Dconf file is:

key ([:=]?) value ([,;]?)
key ([:=]?) value ([,;]?)
key ([:=]?) value ([,;]?)
....

Whitespace between keys and values is optional if an appropriate separator is provided. In the case where there is no separator, then whitespace must exist between keys and values. For example, the following are are all valid Dconf key-value pairs:

key value
key : value
key = value

Keys

Keys are strings that may be bare words or quoted strings. If a key would otherwise match a different value type it is handled as a string, with the exception of maps and arrays. For example, 1234 provided in the position of a key is treated as a string key, not an integer.

In addition to the characters excluded from bareword string values, the following characters are not allowed in bareword keys:

  • : – Colon.
  • = – Equals sign.

The following are examples of valid keys:

keyname : keyvalue
"keyname" = keyvalue
$keyname : keyvalue

Values

Values may be strings (including bare words, quoted strings, or block strings) maps, arrays, integers, floats, date-times, or booleans.

Strings

In general, strings follow the same conventions as keys with the exception that bare word strings may also include the following characters for values: :=/.

  • Bare word strings

    Bare words may contain any non-whitespace characters with the following exceptions:

    (, ) – Left and right parenthesis.
    [, ] – Left and right square brackets.
    {, } – Left and right curly brackets.
    " – Straight double quote.
    ' – Straight single quote.
    , – Comma.
    ; – Semi-colon.
    # – Hash.
    , – Opening and closing double smart quotes
    , – Opening and closing single smart quotes

    Valid examples:

    somekey: somevalue
    anotherkey: $another_value
    

    Invalid examples:

    somekey: some value
    anotherkey: (anothervalue)
    
  • Quoted strings

    Quoted strings begin and end with a matched pair of single quotes or double quotes. Additionally, the appropriate opening or closing smart quote may be substituted (for example, foo = “bar" or foo = "bar”). All characters between the quotes are read and interpreted as a string. No string escaping is performed.

    Valid example:

    somekey: "some value"
    anotherkey: "(anothervalue)"
    
  • Block strings

    Block strings value start with a left parenthesis (() and close with a right parenthesis ()) on a line by itself. All characters between the opening and closing parentheses are captured with no escaping. Thus, symbols that would normally be considered comments will be just another part of the string. No whitespace, commas, or other symbols are allowed on the closing line. It may be ended by CRLF, LF, EOF (0 character), or be the end of the file.

    Valid example:

    somekey: (A block string...
    ...some more text...
    )
    

    Invalid example (white space on closing line):

    somekey: (A block string...
    ...some more text...
      )
    

Maps

Maps begin with { and end with }. The syntax of maps follows that of Dconf files in general:

key ([:=]?) value ([,;]?)
key ([:=]?) value ([,;]?)
key ([:=]?) value ([,;]?) ...

Example:

resources {
  cpu: "300"
  disk_space: "256MB"
  memory: "256MB"
  network_bandwidth: "5Mbps"
  network_max: "30Gbps"
}

Arrays

Arrays begin with [ and end with ]. The syntax is as follows:

value ([,;]?)
value ([,;]?)
value ([,;]?) ...

Example:

package_dependencies: [
  "os.ubuntu",
  "runtime.ruby-1.9.3"
]

Integers

Integers are matched using the following format: (+|-)?[0-9]+.

Examples:

instances: 2
timeout: 8

Floats

Floats are matched using the following format: (+|-)? [0-9]+ '.' [0-9]+ ([eE] [0-9]+)?

Examples:

somevalue: 22.2
avogadros-number = 6.0221409e23

DateTime

DateTime values are matched using the following format: [0-9]{4} '-' [0-9]{2} '-' [0-9]{2} 'T' [0-9]{2} ':' [0-9]{2} ':' [0-9]{2} 'Z'.

Example:

someDate : 2006-01-02T15:04:05Z

Booleans

Booleans are the values true and false and are case insensitive. They must not be quoted.

Example:

"start" = true

Comments

Dconf supports single-line comments. The characters that are matched as part of a comment are not lexed according to the rest of the grammar.

A single-line comment starts with # or // and matches to the end of the line. Note that because bare words allow the / character, a comment beginning with // must typically be preceded with a whitespace if not on it's own line. Single-line comments may appear anywhere outside of a quoted or block string.

Example:

# Resource allocations
resources {
  disk_space: "768MB" // An inline comment.
  memory: "256MB"
  network_bandwidth: "10Mbps"
}