2 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
3 "dtd/docbook-xml/4.1.2/docbookx.dtd" [
4 <!ENTITY statuscodes_table SYSTEM "include/statuscodes.xml">
5 <!ENTITY command_list SYSTEM "include/commands.xml">
6 <!ENTITY priority_table SYSTEM "include/priorities.xml">
7 <!ENTITY type_table SYSTEM "include/types.xml">
12 <title>Configuration management</title>
13 <subtitle>Protocol version 2</subtitle>
14 <releaseinfo>Revision 7.0</releaseinfo>
26 <address><email>wakkerma@debian.org</email></address>
40 <address><email>joeyh@debian.org</email></address>
54 Wichert Akkerman and Joey Hess
59 This text is copyright by the authors under the terms of the
60 BSD license, sans advertising clause.
70 Configuration management is quickly becoming a very important issue.
71 Having programs which do cool stuff is great, but we need to store
72 their configuration as well. We see more and more different
73 configuration systems being introduced all the time, which is not very
74 practical. This text introduces a general configuration management
75 system which flexible enough to be used for all kinds of applications.
85 The configuration space
88 All configuration information is stored in what I call the
89 configuration space. This is a database with a special design
90 which resembles the method we look at configuration information.
91 This is done by defining a hierarchy of information. Each package
92 receives its own space in the hierarchy. Each package is free to
93 use a flat space, or divide its space further into
94 sub-hierarchies. If multiple packages share a common purpose they
95 may use a shared toplevel hierarchy, preferably with the same name
96 as a shared (virtual) package name (for example, both
97 <application>mutt</application> and <application>elm</application>
98 can use <literal>mail-reader</literal>,
99 <application>strn</application> and <application>nn</application>
100 could use <literal>news-reader</literal>). This
101 shared tree can also be used as a default, ie a variable
102 <literal>news-reader/nntpserver</literal> can be used by
103 <application>strn</application> if <literal>strn/nntpserver</literal>
107 Each variable in the configuration space has some information
108 associated with it. Most importantly, it has a value. It also may
109 have a set of flags and a set of substitution data.
119 Each variable in the configuration space is associated with some
120 meta-data. The minimum meta-data associated with a variable is:
121 long and short description, type, and default value. The meta-data
122 is essentially static; the protocol described below does not allow it
126 The meta-data exists in a space with similar naming
127 properties to the configuration space described above, and typically
128 one variable in the configuration space will have associated with it
129 metadata with the same name in the meta-data space. However, this need
130 not be the case; many different variables can all be associated with
131 the same meta-data. In effect the meta-data serves as a template
132 for the configuration variable.
139 So, what do we need to store in a variable template? Of course we
140 need a name to identify the template. Template names are made up of
141 components separated by the character `/' (slash).
142 Each component is limited to alphanumerics and `+' `-' `.'
143 (plus, minus, full stop).
146 A type is also needed so data can be verified. Here is a table
147 of common types; implementations are free to make up more.
151 Of course a default value is useful as well, and
152 finally we need a description of the variable. We actually use two
153 descriptions: a short one (limited to 50 characters or so) and an
157 The extended description may be word-wrapped by the
158 FrontEnd. To make separate paragraphs in it, use <literal>.</literal>
159 on a line by itself to separate them. Text in the extended
160 description that is prefaced by additional whitespace will not be
161 wordwrapped. Both the description and extended
162 description may have substitutions embedded in them. Ie,
163 <literal>${foo}</literal>. These will be expanded when the
164 descriptions are displayed.
167 This information is stored in a template file that consists of
168 stanzas in a rfc-822 compliant format, separated by blank lines.
174 Description: unqualified hostname for this computer
175 This is the name by which this computer will be known on the network. It
176 has to be a unique name in your domain.
180 Description: domain for this computer
181 This is the domain your computer is a member of. Typically it is
182 something like "mycompany.com" or "myuniversity.edu".
189 Configuration frontends
192 Of course applications can use the database and meta-database directly.
193 But there should be a simple system to interact with the user that is
194 simple and modular enough to be used with systems ranging from
195 shell-scripts to Fortran programs. To do this we define a general
196 frontend that can be driven using the simplest and most common form of
197 communication: stdin and stdout.
200 Using this simple form of communication gives us a great advantage: it
201 becomes easy to change the frontend. That means the user can switch
202 between a console, a graphical or even a web-interface at will.
205 Besides being able to switch between types of frontends there is
206 another important aspect of a good user interface: user friendliness.
207 We have to account for the fact that some users know more then others
208 and change the information we show or ask from the user. We do this by
209 giving everything a priority and giving the user control over what
210 kind of questions he wants to see. Experts can request to see
211 everything, while novices get the option of only seeing only important
212 questions. Finally there is an option to simply skip all questions, so
213 it becomes possible to do automatic configuration using default values
214 or values that are downloaded into the database from a remote
215 location. This makes it simple for example to install and manage
216 clusters or lab rooms or do installs for dummies.
221 Communication with the frontend
224 This communication between the frontend and the application should be
225 as simple as possible. Since most IO implementations default to
226 line-buffered IO, so we use a simple language where each command is
230 After sending each command to stdout, the client
231 should read one line from stdin. This is the response to the command,
232 and it will be in the form of a number followed by whitespace and an
233 optional string of text. The number is the status code, while the
234 text provides additional information.
238 Here are the currently supported commands.
246 Debian install-time configuration
249 Debian has had an excellent packaging system for a long time now. There is
250 one thing missing though: a system to handle the configuration of
251 packages so we don't have to stop the installation every time a package
252 needs some data from the user or wants to show some information.
255 We want to make a package which does not break older dpkg's, and we
256 want to be able to get the configuration information before the package
257 is unpacked. To do this we add two new files, config and templates, to
258 the control.tar.gz of a .deb package. Since all installation-software
259 (apt, dselect, dpkg) download the package before installing it, we can
260 extract this before the package is unpacked.
263 The templates file lists the templates for variables that this package
264 uses. This is done using the format as used in the example in the
265 section on templates.
268 The config-file contains a new element, which I call the configmodule.
269 This is a program that will determine the configuration before the
270 package is unpacked. This means it is run <emphasis>before</emphasis>
271 the preinst, and before the package is unpacked! This is done to make
272 sure that we can use the desired configuration in the preinst if
276 How does the configmodule get its information? The configmodule
277 needs a way to retrieve information from the configuration space, ask
278 the user for information if necessary, etc. But we don't want to
279 implement a user interface for each package. To solve this we use a
280 separate frontend as specified in the section on frontends.