The Flatconf configuration structure

This document defines a standard for Flatconf configuration structure as of 1.0 version.

Fundamentals

A Flatconf configuration starts in root directory, e.g. /etc/fc.

Each Flatconf variable is a file. A variable can have a value, which is simply the file content. There is an arbitrary subdirectory tree under the root directory, which holds the variables and provides configuration hierarchy. A particular variable or a directory (being under Flatconf root directory) can be referred to as an entry.

Each entry has unique variable locator - UNIX path, treating the Flatconf root directory as the root directory in UNIX sense, e.g. Flatconf path /net/if/eth0/addr points to a variable which in underlying file system can be located under /etc/fc/net/if/eth0. When necessary, Flatconf path can be prefixed with pseudo-protocol identifier fc:, e.g. fc:/net/if/eth0/addr.

Characters allowed in an entry name are: a-z, A-Z, 0-9, "_", ".", ":", "#" and "@".

Entries can have various properties. Properties are stored in .fc/ subdirectory, relative to directory of given entry. Usually, this is:

.fc/<name>/<property>

where:

  • <name> is entry name and
  • <property> is property name.

There are a few exceptions from simple rules described above: list variables and action directories.

Lists

A list is a meta-variable which organizes other entries which only requirement is not to be of list type, too.

A list defines belonging of entries to a single logical group. Each entry belonging to a list is called an element. An element has specified placement on a list and can be either enabled or disabled.

Each entry may belong only to a single list.

If not defined otherwise, a list is editable by the user, who can:

  • move,
  • enable,
  • disable,
  • delete and
  • rename list elements.

If an element skeleton is defined (being a property of a list type entry), user is provided with a simple interface for adding an element to the list.

Variables which hold lists must have a plus sign before it's name, e.g. +interfaces. Such convention has been chosen in order to ease parsing of Flatconf directories.

Actions

Actions are Flatconf directories which are submittable.

After setting all required variables, user can submit an action and a defined script embedded in Flatconf structure is executed. Script can give results in form of exit code and/or diagnosis message, as described later in this document.

After action submission, all variables are zeroed (ie. their values are deleted).

Properties summary

  • action-script.sh - a shell script to execute when user chooses to execute an action,
  • after.sh - a shell script to execute after changing variable value,
  • deps.sh - a shell script which exit code decide whether variable should be shown (exit code 0) or not (1),
  • order-first, order-last - controls variable ordering while listing a particular directory,
  • title-lang, help-lang, notes-lang - provides "human-readable" title, help text and important notes for given variable,
  • type - defines what type of value a variable holds,
  • skel - a skeleton (dir/file) for new element of a variable being of "list" type,
  • skel-fc - a skeleton (dir) for .fc/<element>/ of new element of a variable as above.

What's important, remember that if you don't need any of these (e.g. configuration is to be read and edited in simple manner only by computer programs), don't use them - that's perfectly fine.

Commonly used properties

Variable title

Property: .fc/<entry>/title-lang

Where lang is abbreviated language name, chosen arbitrarily, e.g. "en", "pl", etc.

This property holds human-readable variable title, e.g. "Interface IP address".

Variable help text

Property: .fc/<entry>/help-lang

As above, holds preformatted, multiline, long help text, e.g. a man page.

Variable notes

Property: .fc/<entry>/notes-lang

As above, holds one line of important notes about a particular entry, e.g. "Don't set below 100".

Variable type

Property: .fc/<entry>/type

Defines variable type, what mainly limits it's possible values and restricts value format.

May be one of the following:

  • text [default],
  • bool,
  • select,
  • file,
  • binfile,
  • ro,
  • label,
  • novalue,
  • int,
  • ipaddr,
    • ipaddr4,
    • ipaddr6,
  • macaddr and
  • action.

text

This is the most basic and generic type, accepting arbitrarily long one line of text.

bool

Accepts only two values: "1" and "0", representing Boolean "truth" and "false".

select

This type lets user choose only from the allowed values.

Each allowed value should be given in the file defining the property (ie. .fc/<entry>/type), after the "select" keyword, each value on a separate line, e.g.

select
none
value1
value2

Will let user choose from "none", "value1" and "value2".

Human-readable titles may be associated with the allowed values. A title in language lang for <entry>'s <value> should be put in .fc/<entry>/select/<value>/title-lang.

file

Holds a text file editable by the user.

binfile

As above, but variable value is binary, thus not editable by the user.

ro

Holds a read-only text file.

label

A "placeholder" having no value, for marking different parts of configuration directories having many entries.

novalue

As above, but important for configuration, not just it's presentation. Useful e.g. for priority configuration lists with movable elements.

int

An integer number. Second line may define range:

[<min>] <max>

Where:

  • <min> is minimal value and may be omitted,
  • <max> is maximal value.

ipaddr

Accepts either IPv4 or IPv6 address in CIDR notation. Subtypes:

  • ipaddr4 - accepts only IPv4,
  • ipaddr6 - accepts only IPv6.

macaddr

Accepts Ethernet hardware address (MAC address), written in upper/lower case.

action

This value is proper only for directories and marks directory as submittable, thus being simply an action.

Regular expressions

There are properties which let check user-supplied variable values against defined regular expressions. These properties are as follows.

regexp

Holds regular expressions that must match supplied value. Each expression is defined in a single line and must be quoted, e.g. with '/' characters. There may be additional modifiers after ending quoting character:

  • i,
  • m,
  • s,
  • e,
  • A,
  • D,
  • U,
  • X,

as described e.g. in the PHP manual.

Comments starts with '#' character. Empty lines and comments are ignored.

However, if a comment is immediately before regular expression, and it matches following regular expression:

/^#([a-zA-Z_]+): (.*)$/

Then \2 is used as error text in \1 language to show the user in case the regular expression did not match. Multiple error texts in different languages may be defined one by one, on separate lines.

regexp-not

As above, but defines regular expressions that must not match supplied value.

Directory listing order

Property: .fc/order-first Property: .fc/order-last

These properties define ordering while listing a directory. These files contain one entry name per line and define entries that should be shown first and last, respectively.

For example: a directory holds "abc", "bcd", "cde", "def", "efg" and "fgh" entries. It's order-first is:

bcd
efg

and it's order-last is:

abc
def

Then, listing this directory in user interface will show entries in the following order:

bcd
efg
cde
fgh
abc
def

Shell scripts

Flatconf supports embedding shell scripts in it's structure. Such scripts may be used to enhance Flatconf functionality in virtually any manner, as Flatconf stands on very simple and flexible idea - flat files perectly modifable from shell scripts.

Where appropriate, shell script's exit code may be used to pass diagnosis information back to the user:

  • $FC_OK - everything OK,
  • $FC_IO_ERR - input/output error, e.g. permission denied,
  • $FC_DIAG_MSG - show text provided on stdout to the user,
  • $FC_INV_ARG - invalid argument,
  • $FC_INT_ERR - internal error in the Flatconf structure.

Values of error codes are exported as environmental variables before script exection. Values are chosen in such manner, that they may be connected using logical OR operation to construct a complex error code, e.g.

#!/bin/bash
echo "Permission denied"
exit $((FC_IO_ERR | FC_DIAG_MSG))

will mean that an I/O error occured and script's stdout should be shown to the user.

Exceptionally, the error code of value 0 is equivalent to FC_OK.

after.sh

Property: .fc/<name>/after.sh

Communication via error code: YES

Working directory: variable directory

Script to execute after writing value to entry of given <name>. Writing new value being the same as the old one should also trigger the after.sh script.

before.sh

Property: .fc/<name>/before.sh

Communication via error code: NO

Working directory: variable directory

Script to execute before reading variable value.

deps.sh

Property: .fc/<name>/deps.sh

Communication via error code: YES, nonstandard

Working directory: entry directory

Returns 0 if entry should be shown in directory listing, or 1 (or any other code) otherwise.

action-script.sh

Property: .fc/action-script.sh

Communication via error code: YES

Working directory: action directory

Defines the script to execute after user chooses to submit an action.

Lists

Following properties may be used to limit functionality of a list. These properties have no value:

  • nodel - disable ability to delete list elements,
  • nodisable - as above, ability to enable/disable elements,
  • noorder - as above, ability to move list elements,
  • sort - cause list elements to be sorted automatically, implies noorder.

Following properties may be used to define "skeletons" for new list elements:

  • skel - a skeleton for new element - a file or a directory,
  • skel-fc - a directory which is skeleton for .fc/<element>/,
  • skel-title-lang - title to show instead of "New element name" (or similar),
  • skel-onadd.sh - shell script to execute after adding new element:
    • if skel is a directory, than working directory is changed into newly created directory,
    • new element name is passed as first argument.

Deleting a list element

When a user chooses to delete a list element, than a recursive deletion procedure is called, which works in "depth first" manner. Then, for each directory traversed, if .fc/ondel.sh script is found, then it is executed.

For example, this may be used to disable networking on network interface represented by the element being deleted from a list of network interfaces.

Fancy strings

Values of the following properties of directories may embed variable values:

  • title-lang,
  • notes-lang,
  • skel-title-lang.

To request the value of a variable to be substituted into property value, following notation is used:

%<name>%

Where <name> is the variable name under the directory the property is defined for. There is one special fancy string - "%ME%" - which substitutes the directory name.

Example .fc/eth0/title-en:

Network interface %ME%, IP %addr%

Example output: "Network interface eth0, IP 192.168.1.1".