summaryrefslogtreecommitdiff
path: root/Software/CFG.mdwn
blob: cdd88dc59619b19bcfca7e29e445f014c06d1ff4 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102

[[!toc ]] 


## CFG (Config4GNU)

CFG is a three layered unifying configuration framework. It can represent and modify hierarchies of settings in arbitrary config files/databases. 

Its modular framework is based on config (file) descriptions for particular packages, called meta-config definition files. These files can be maintained and installed together with the applications themselves. 

Once a meta-config definition for an application is in place the whole CFG framework can be used on the referenced configuration. 

The CFG framework features: 

                     * Simple access to all settings of a package 
                     * Different Interfaces (API, comand line, www, GUI, LDAP ...) 
                     * Higher level meta-logic beyond "keys and values" (general Forms and Wizard logic available for frontends) 
                     * Help texts and comments from the config files along with the settings. 
                     * Lossless config file updates/transformations 
                     * and more... 
In addition to the info below you might want to read the [[CfgFAQ|Software/CfgFAQ]], and look at the [[screenshots|http://config4gnu.sourceforge.net/screenshots/old.html]] of the GTK-- client prototype. In particular look for the usage of "forms". Don't get too caught up in the tree and key/value view. An end-users frontend could choose to render an icon view and only forms and wizards to alter configurations from the provided meta-data. 

Here is the short version of how it works: 

CFG's middlelayer adds the configurations it reads from the various back-end's syntax parsers to a unified XML representation according to the meta-config definitions it finds. The top-layer then provides utilities and different methods for frontends to querry and access the whole representation. CFG itself saves configuration state only in the original config files. The parsers know the syntax and the meta-config definitions are the source of the semantics. So CFG won't interfere with any hand-editing or other means of config manipulation. In case of an option, type or value error, wether real or due to a not up to date meta-config-definition, CFG can fall back to treat the option it does not know about as a string. Therefore CFG based config tools do not have to completly refuse working on modified files. 

(* means not yet implemented) 
[[!table header="no" class="mointable" data="""
**Front-Ends**: | Line Utilities | GUI | Web | LDAP* | Specialized Tools* (e.g. "go back" utility)
**Top-Layer**: | Provides API, logging*, caching, and any other shared functionality, as appropriate.|||||
**Middlelayer**: | According to found meta-config definitions: Invokes other back-end parsers, generates XML representation and activates changes after writes.|||||
"""]]
[[!table header="no" class="mointable" data="""
**Bottom-Layer**: | conf-style parser | INI-style parser | XML parser | Specialized/derived  parsers (e.g. Apache, samba, XF86``Config, Sendmail*,...)
**Back-Ends**: | Plain text config files | INI Files | XML config files/meta-config files | apache.conf, crontab*, system.dat*, LDAP server*, ...
"""]]

The original authors have working code out now, but pracically no time to work on it anymore. We need your help packaging it and documenting how to define additional meta-config definitions. Also we'd like to see some of the dependencies (re)moved. (Some more specific things can be found on the [[development|Software/CfgDevel]] page and in the sourceforge's trackers). 

Frequently asked questions (and answers) are available and maintained on the [[CfgFAQ|Software/CfgFAQ]] page, and may help to quickly grasp the concept. 


## Intended uses for CFG


### Shared foundation for universal Config Tools/Frontends

This one is obvious. Instead of keeping each config tool around up-to-date with changes in config file options and formats only one meta-config definition per package and a appropriate general syntax parser has to be maintained. Config tools can be relatively light weight and easy to maintain yet be universal tools that make use of all their UI/Toolkit features. CFG provides a XML "configuration tree" with available settings, descriptions, available choices and defaults for all packages for which a meta-config definition is available. The frontend can present the tree, or parts of it, if and how desired, and can use the information in forms and wizard definitions to generate user interfaces beyond keys and values even for things the frontend has not been specialized for. Forms and wizards defined in the meta-config only provide the basic logic necessary, the actual appearance can vary widely depending on the frontend used. 


### Config File Upgrades

Config file upgrades can simply be done by querying the existing settings from CFG, and writing the settings back after the package upgrade. With the new meta-config definition in place CFG will now generate a new style config file when told to save all previous settings (and comments etc.) that have been read out before. In cases of first time installs or without previous non-default settings the defaults defined in the meta-config would be written out to the new config file. 


### Installers

With CFG a package itself should not need to contain a config file that gets copied into /etc, if the pre-inst script finds that the required configuration settings allready exist they will be kept, if no file exists, a new file with the defaults from the meta-config will be created. But sometimes reasonable defaults don't exist for all settings. In this case the installer script/program can call the appropriate/default CFG frontend to prompt the user with the "init" form or wizard. This wizard is defined in the packages' meta-config. Filling out this init form or wizard will complete a valid configuration. The init form or wizard is for setting up things that don't have reasonable defaults but are needed to use the package.  


### Preconfigureing Packages

Applications default options are marked in the meta-config definitions as such (i.e. application-defaults that are assumed by the described application if they are not set and therefore do not need to be written to the config file). 

CFG-defaults are different from application-defaults, they serve as suggestions/defaults for frontends. There could be even group specific defaults. For example the frontend might only offer to a user to change the options that have defined user-defaults and the other options will remain to be app, distribution and admin defaults (in that order) if they haven't been explicitly set before. (multi-level configuration) 

Two ways for preconfigureing or customization are: Modifying the defaults in a special packages' meta-config as desired. Or simply pre-seeding the /etc tree with initial config files which contain the desired options during a customized installation. When the package gets installed later those settings will be picked up. If values for all required settings are available the init wizard doesn't need to be invoked anymore. 


## General package maintainer script tasks

pre-install: 

                     * Query CFG for configuration of package that is to be installed. 
                     * If result is positive save the result (XML representation) and rename the old config file. 
post-install: 

                     * If a saved XML-representation from preinst is found write it back with the now updated meta-config. 
                     * If package is installed in noninteractive mode, query CFG now again (meta-data in place, /etc still empty) and save with defaults to create a valid configuration, otherwise call frontend appropriately. 
                     * If some required settings are still missing call the default CFG frontend to "init" the package. 

## Debconf and CFG:

They extend each other. 

Existing debconf options provided by maintainer scripts can be tied into the configuration system even before explicit CFG meta-config definitions may be available for them. The idea is to make a CFG backend that functions as a frontend to debconf. This way all existing debconf settings could be readily available in the CFG configuration system. It opens a smooth transition path for packages to be updated to provide or depend on CFG meta-config files. 

Maintainers can gradualy make use of CFG functions in their package scripts to easily and safely set up and update their configfiles. Debconf will remain working as before. With the difference that the maintainer scripts debconf depends on to take care of the configuration will be easier to write and maintain due to the shared functionality. Not only the functionality between packages in debian is shared. Much of the config-management and config-description can be maintained in a collaborative way per application rather than per package or per distribution. 

Due to the meta-config definitions and the configuration system, any frontend, tool or script will now have access to the same settings and configuration possibilities. 


## Downloads

If you want to see for yourself what this is all about you can download and install Config4GNU. Be aware that the features mentioned here refer to the original Config4GNU concept which differs from the cut-down and hardcoded experimental config4gnu-wbem version. 

Download Information is available [[here|http://config4gnu.sourceforge.net/downloads/config4gnu.html]], you should prefer the cvs version over the outdated tarball. 

For more documentation look also on our first Hompage: [[http://config4gnu.sourceforge.net|http://config4gnu.sourceforge.net]] Note that not all parts there are up to date though. 

This [[news/web-mail interface|http://news.gmane.org/gmane.comp.sysutils.cfg.devel]] to our mailing list has also the later messages archived that somehow did not make it into sourceforge's [[mailing list|http://sourceforge.net/mail/?group_id=62306]] archive.