What is Flatconf

Flatconf is a standard for creating simple, reliable and feature-rich software configuration systems based on flat files and tree-like directory structures.

The main idea is that each Flatconf variable consists of the following:

  • value - stored in a single, flat file, e.g. /etc/fc/sys/hostname,
  • metadata holding properties - stored in a single, structured file, e.g. /usr/share/fc/main/sys/hostname.fc.

A particular Flatconf configuration starts in the configuration root directory, e.g. /etc/fc/. This (and only this) directory must have a subdirectory named flatconf/, which holds various information about this configuration system, stored in files:

  • schema - name of the Flatconf schema which holds the metadata of this configuration; user interface should allow to override this value,
  • counter - a counter counting from 1 up, used mainly for lists,
  • any other additional, arbitrarily named files, specific for e.g. version control, schema upgrades, etc.

Schema name cannot be regexp nor skel, as these names are reserved.

The whole directory tree under some configuration root directory can be referred to as the data tree. Similarly, directories belonging to a particular Flatconf schema can be reffered to as the metadata tree.

Properties

Properties of e.g. /dir/var variable, which uses a schema named e.g. foobar are defined in file /usr/share/fc/foobar/dir/var.fc using Flatconf Markup Language (FCML). Note that FCML allows extending this file using /usr/share/fc/foobar/dir/var.d/*.fc files.

FCML offers capability of filespaces, ie. virtually changing the meaning of "/" and "." directories. In Flatconf, a filespace named "c" (for configuration) always refers to the directory tree holding the values, e.g. /etc/fc.

Naming

Both the variable value and it's properties can be referenced using following Flatconf paths:

  • fc:/sys/hostname - value of the /sys/hostname variable, physically located e.g. in /etc/fc/sys/hostname file,
    • fc@27:/sys/hostname - value of /sys/hostname in revision numer 27, if available (ie. when version management is present),
    • fc:hostname - path relative to the current working directory,
  • fs:main:/sys/hostname/type - the "type" property of the /sys/hostname variable in the schema named "main", always physically located in a variable named "type" defined in /usr/share/fc/main/sys/hostname.fc file
    • fs:/sys/hostname/type - as above, but the schema to use should be given in the context in which such path is used,
    • fs:type - as above, but more context information is required,
    • fs:/sys/hostname.fc - the FCML file holding property definitions.

Characters allowed in a variable name:

  • small letters (a-z)
  • digits (0-9)
  • underscore (_)
  • hyphen (-)

Variable name must not consists of digits only. This is reserved for list elements only.

Exceptions (mainly for user-editable variable properties):

  • fc:variable.notes - optional, user-editable notes
  • lists
    • fc:somelist/list.order - file holding the order in which elements appear on a list
    • fs:somelist.element.fc - default path to file defining properties of somelist elements
  • .variable - the variable has been deprecated and the interface should offer the user to delete it