wiki:monza/flatconf

Flatconf

Flatconf is a filesystem-based database used for creating configuration systems.

A Flatconf configuration system consists of two parts: schema definition (metatree) and data storage (datatree). Schema defines variables - titles, allowed values, etc. - and datatree stores the actual variable values.

Variable definitions are written in FCML language according to the rules that the Flatconf Standard defines. In order to fully understand how Lintrack configuration works and how to extend it, please read the Flatconf 2.0 documentation.

If you start with Flatconf and just want to learn the basics, read the following:

An example - /usr/share/fc/lt/sys/hostname.fc:

# value
type = "text"
default = "lintrack.lan"
regexp = { "hostname" }

# presentation
title = { en: "Host name", pl: "Nazwa hosta" }
examples = { "rt1.lan", "br4.rt2.isp.com" }

This /sys/hostname variable definition in lt schema in Lintrack has storage in /etc/fc/sys/hostname file.

Implementation in Lintrack

Lintrack uses Flatconf schema named lt. The datatree is stored under /etc/fc and has following basic hierarchy:

  • /sys - all settings related to local system, e.g.:
    • fundamental networking settings,
    • configuration of important libraries or system services (like SSL) and
    • hardware;
  • /net - all networking-related settings which are not visible in the system as a process, or procesess creating network interfaces, e.g.:
    • kernel settings,
    • interfaces,
    • routing,
    • security;
  • /auth - AAA (Authentication, Authorization, Accounting) - both local and remote AAA sources/services, e.g.:
    • RADIUS,
    • PPP,
    • WPA;
  • /srv - all services visible in the system as a daemonized process, e.g.:
    • dynamic routing,
    • servers of network services for routers access networks.

It is important to keep in mind that configuration elements need to be reusable and uniform with the rest of the system. For instance, if you want to create configuration for traffic control (queues, etc.), make it so generic that it applies to every kind of a network interface in the system. Note that sometimes it requires some separation, e.g. by putting tc config in a separate subdirectory.

Datatree needs an underlying version control system so we're able to see what changes the user has made since we last used the configuration to setup the system. VC is subject of the ticket #182.

Flatconf utilities

The most important FC utility is fccat. Apart of a few options it takes an fc:path (e.g. /sys/hostname) as the first argument.

  • if it's a variable, it outputs its value (taking into account the default= property),
  • if it's a list, it outputs all enabled list elements, each in one line, in the format of '<elid> <elname>' (remember that <elname> may contain spaces),
  • otherwise it doesn't print anything to stdout and exits with non-zero error code.

Translating Flatconf to target configuration file

In order to start a daemon which needs a configuration file one has to translate the configuration from /etc/fc into a *.conf file with proper syntax. Such a Flatconf translator should be put in /etc/fc.d/ directory and has the executable bit set.

A translator is (usually) a bash script reading configuration stored somewhere in /etc/fc and rewriting it to the format understood by the software package being configured - e.g. /etc/ppp/pppoe-server-options.

Because while being an integrated Linux distribution we also leave possibility to configure everything in a traditional way, we let the end user modify the automatically generated configuration in a simple manner. Please see user documentation on making custom changes to such files for more details.

Generally, you should remember about two things when (over)writing the target configuration files:

  • use [ -k "$file" ] to test whether the file hasn't got the sticky bit set (and thus is locked for automatic changes),
  • use 'fcdsave "$file" [mode]' to automatically handle extensions via $file.d/ directory:
    • source /etc/fc.d/include/conffile.sh,
    • pass configuration on stdin to fcdsave.

See fc.pppoe-server for an example.

Last modified 11 years ago Last modified on 03/22/08 21:29:40