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">
8 <!ENTITY % versiondata SYSTEM "include/version.xml"> %versiondata;
13 <title>Configuration management</title>
14 <subtitle>Protocol version 2.1</subtitle>
15 <releaseinfo>Revision 7.1, Debian Policy &version;, &date;</releaseinfo>
17 <firstname>Wichert</firstname>
18 <surname>Akkerman</surname>
20 <orgname>The Debian Project</orgname>
21 <address><email>wakkerma@debian.org</email></address>
25 <firstname>Joey</firstname>
26 <surname>Hess</surname>
28 <orgname>The Debian Project</orgname>
29 <address><email>joeyh@debian.org</email></address>
36 <holder>Wichert Akkerman and Joey Hess</holder>
40 This text is copyright by the authors under the terms of the
41 BSD license, sans advertising clause.
51 Configuration management is quickly becoming a very important issue.
52 Having programs which do cool stuff is great, but we need to store
53 their configuration as well. We see more and more different
54 configuration systems being introduced all the time, which is not very
55 practical. This text introduces a general configuration management
56 system which flexible enough to be used for all kinds of applications.
66 The configuration space
69 All configuration information is stored in what I call the
70 configuration space. This is a database with a special design
71 which resembles the method we look at configuration information.
72 This is done by defining a hierarchy of information. Each package
73 receives its own space in the hierarchy. Each package is free to
74 use a flat space, or divide its space further into
75 sub-hierarchies. If multiple packages share a common purpose they
76 may use a shared toplevel hierarchy, preferably with the same name
77 as a shared (virtual) package name (for example, both
78 <application>mutt</application> and <application>elm</application>
79 can use <literal>mail-reader</literal>,
80 <application>strn</application> and <application>nn</application>
81 could use <literal>news-reader</literal>). This
82 shared tree can also be used as a default, ie a variable
83 <literal>news-reader/nntpserver</literal> can be used by
84 <application>strn</application> if <literal>strn/nntpserver</literal>
88 Each variable in the configuration space has some information
89 associated with it. Most importantly, it has a value. It also may
90 have a set of flags and a set of substitution data.
100 Each variable in the configuration space is associated with some
101 meta-data. The minimum meta-data associated with a variable is:
102 long and short description, type, and default value. The meta-data
103 is essentially static; the protocol described below does not allow it
107 The meta-data exists in a space with similar naming
108 properties to the configuration space described above, and typically
109 one variable in the configuration space will have associated with it
110 metadata with the same name in the meta-data space. However, this need
111 not be the case; many different variables can all be associated with
112 the same meta-data. In effect the meta-data serves as a template
113 for the configuration variable.
120 So, what do we need to store in a variable template? Of course we
121 need a name to identify the template. Template names are made up of
122 components separated by the character `/' (slash).
123 Each component is limited to alphanumerics and `+' `-' `.' `_'
124 (plus, minus, full stop, underscore).
127 A type is also needed so data can be verified. Here is a table
128 of common types; implementations are free to make up more.
132 Of course a default value is useful as well, and
133 finally we need a description of the variable. We actually use two
134 descriptions: a short one (limited to 50 characters or so) and an
138 The extended description may be word-wrapped by the
139 FrontEnd. To make separate paragraphs in it, use <literal>.</literal>
140 on a line by itself to separate them. Text in the extended
141 description that is prefaced by additional whitespace will not be
142 wordwrapped. Both the description and extended
143 description may have substitutions embedded in them. Ie,
144 <literal>${foo}</literal>. These will be expanded when the
145 descriptions are displayed.
148 This information is stored in a template file that consists of
149 stanzas in a rfc-822 compliant format, separated by blank lines.
155 Description: unqualified hostname for this computer
156 This is the name by which this computer will be known on the network. It
157 has to be a unique name in your domain.
161 Description: domain for this computer
162 This is the domain your computer is a member of. Typically it is
163 something like "mycompany.com" or "myuniversity.edu".
167 For localization, the description field (and also the choices
168 field of a select or multiselect type question, and the
169 default field of a string or password type question) can be
170 supplemented with versions for other languages. These are
171 named <emphasis>Description-ll</emphasis>,
172 <emphasis>Description-ll_LL</emphasis>,
173 <emphasis>Description-ll_LL.encoding</emphasis> and so on.
179 Configuration frontends
182 Of course applications can use the database and meta-database directly.
183 But there should be a simple system to interact with the user that is
184 simple and modular enough to be used with systems ranging from
185 shell-scripts to Fortran programs. To do this we define a general
186 frontend that can be driven using the simplest and most common form of
187 communication: stdin and stdout.
190 Using this simple form of communication gives us a great advantage: it
191 becomes easy to change the frontend. That means the user can switch
192 between a console, a graphical or even a web-interface at will.
195 Besides being able to switch between types of frontends there is
196 another important aspect of a good user interface: user friendliness.
197 We have to account for the fact that some users know more then others
198 and change the information we show or ask from the user. We do this by
199 giving everything a priority and giving the user control over what
200 kind of questions he wants to see. Experts can request to see
201 everything, while novices get the option of only seeing only important
202 questions. Finally there is an option to simply skip all questions, so
203 it becomes possible to do automatic configuration using default values
204 or values that are downloaded into the database from a remote
205 location. This makes it simple for example to install and manage
206 clusters or lab rooms or do installs for dummies.
211 Communication with the frontend
214 This communication between the frontend and the application should be
215 as simple as possible. Since most IO implementations default to
216 line-buffered IO, so we use a simple language where each command is
220 After sending each command to stdout, the client
221 should read one line from stdin. This is the response to the command,
222 and it will be in the form of a number followed by whitespace and an
223 optional string of text. The number is the status code, while the
224 text provides additional information.
228 Here are the currently supported commands.
236 Debian install-time configuration
239 Debian has had an excellent packaging system for a long time now. There is
240 one thing missing though: a system to handle the configuration of
241 packages so we don't have to stop the installation every time a package
242 needs some data from the user or wants to show some information.
245 We want to make a package which does not break older dpkg's, and we
246 want to be able to get the configuration information before the package
247 is unpacked. To do this we add two new files, config and templates, to
248 the control.tar.gz of a .deb package. Since all installation-software
249 (apt, dselect, dpkg) download the package before installing it, we can
250 extract this before the package is unpacked.
253 The templates file lists the templates for variables that this package
254 uses. This is done using the format as used in the example in the
255 section on templates.
258 The config-file contains a new element, which I call the
259 configmodule. This is a program that will determine the
260 configuration before the package is unpacked. This means it is
261 usually run <emphasis>before</emphasis> the preinst, and before
262 the package is unpacked!
264 <simpara>Please see debconf-devel(7) for details.</simpara>
266 This is done to make sure that we can
267 use the desired configuration in the preinst if necessary.
270 How does the configmodule get its information? The configmodule
271 needs a way to retrieve information from the configuration space, ask
272 the user for information if necessary, etc. But we don't want to
273 implement a user interface for each package. To solve this we use a
274 separate frontend as specified in the section on frontends.