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
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
|
<?xml version="1.0"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"dtd/docbook-xml/4.1.2/docbookx.dtd" [
<!ENTITY statuscodes_table SYSTEM "debconf/statuscodes.xml">
<!ENTITY command_list SYSTEM "debconf/commands.xml">
<!ENTITY priority_table SYSTEM "debconf/priorities.xml">
<!ENTITY type_table SYSTEM "debconf/types.xml">
<!ENTITY % versiondata SYSTEM "version.xml"> %versiondata;
]>
<article>
<articleinfo>
<title>Configuration management</title>
<subtitle>Protocol version 2.1</subtitle>
<releaseinfo>Revision 7.1, Debian Policy &version;, &date;</releaseinfo>
<author>
<firstname>Wichert</firstname>
<surname>Akkerman</surname>
<affiliation>
<orgname>The Debian Project</orgname>
<address><email>wakkerma@debian.org</email></address>
</affiliation>
</author>
<author>
<firstname>Joey</firstname>
<surname>Hess</surname>
<affiliation>
<orgname>The Debian Project</orgname>
<address><email>joeyh@debian.org</email></address>
</affiliation>
</author>
<author>
<othername>The Debian Policy Mailing List</othername>
<affiliation>
<address><email>debian-policy@lists.debian.org</email></address>
</affiliation>
</author>
<copyright>
<year>1998</year>
<year>1999</year>
<year>2000</year>
<holder>Wichert Akkerman</holder>
<holder>Joey Hess</holder>
</copyright>
<legalnotice>
<para>
These are the copyright dates of the original configuration
management protocol document. Since then, this document has been
updated by many others. No comprehensive collection of copyright
notices for subsequent work exists.
</para>
<para>
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
</para>
<orderedlist numeration="arabic">
<listitem>
<para>
Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
</para>
</listitem>
<listitem>
<para>
Redistributions in binary form must reproduce the above
copyright notice, this list of conditions and the following
disclaimer in the documentation and/or other materials
provided with the distribution.
</para>
</listitem>
<listitem>
<para>
Neither the name of the Debian Project nor the names of its
contributors may be used to endorse or promote products
derived from this software without specific prior written
permission.
</para>
</listitem>
</orderedlist>
<para>
THIS MANUAL IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
</para>
</legalnotice>
</articleinfo>
<sect1>
<title>
Introduction
</title>
<para>
Configuration management is quickly becoming a very important issue.
Having programs which do cool stuff is great, but we need to store
their configuration as well. We see more and more different
configuration systems being introduced all the time, which is not very
practical. This text introduces a general configuration management
system which flexible enough to be used for all kinds of applications.
</para>
</sect1>
<sect1>
<title>
Configuration Data
</title>
<sect2>
<title>
The configuration space
</title>
<para>
All configuration information is stored in what I call the
configuration space. This is a database with a special design
which resembles the method we look at configuration information.
This is done by defining a hierarchy of information. Each package
receives its own space in the hierarchy. Each package is free to
use a flat space, or divide its space further into
sub-hierarchies. If multiple packages share a common purpose they
may use a shared toplevel hierarchy, preferably with the same name
as a shared (virtual) package name (for example, both
<application>mutt</application> and <application>elm</application>
can use <literal>mail-reader</literal>,
<application>strn</application> and <application>nn</application>
could use <literal>news-reader</literal>). This
shared tree can also be used as a default, ie a variable
<literal>news-reader/nntpserver</literal> can be used by
<application>strn</application> if <literal>strn/nntpserver</literal>
does not exist.
</para>
<para>
Each variable in the configuration space has some information
associated with it. Most importantly, it has a value. It also may
have a set of flags and a set of substitution data.
</para>
</sect2>
</sect1>
<sect1>
<title>
Templates
</title>
<para>
Each variable in the configuration space is associated with some
meta-data. The minimum meta-data associated with a variable is:
long and short description, type, and default value. The meta-data
is essentially static; the protocol described below does not allow it
to be changed.
</para>
<para>
The meta-data exists in a space with similar naming
properties to the configuration space described above, and typically
one variable in the configuration space will have associated with it
metadata with the same name in the meta-data space. However, this need
not be the case; many different variables can all be associated with
the same meta-data. In effect the meta-data serves as a template
for the configuration variable.
</para>
<sect2>
<title>
Template information
</title>
<para>
So, what do we need to store in a variable template? Of course we
need a name to identify the template. Template names are made up of
components separated by the character `/' (slash).
Each component is limited to alphanumerics and `+' `-' `.' `_'
(plus, minus, full stop, underscore).
</para>
<para>
A type is also needed so data can be verified. Here is a table
of common types; implementations are free to make up more.
&type_table;
</para>
<para>
Of course a default value is useful as well, and
finally we need a description of the variable. We actually use two
descriptions: a short one (limited to 50 characters or so) and an
extended one.
</para>
<para>
The extended description may be word-wrapped by the
FrontEnd. To make separate paragraphs in it, use <literal>.</literal>
on a line by itself to separate them. Text in the extended
description that is prefaced by additional whitespace will not be
wordwrapped. Both the description and extended
description may have substitutions embedded in them. Ie,
<literal>${foo}</literal>. These will be expanded when the
descriptions are displayed.
</para>
<para>
This information is stored in a template file that consists of
stanzas in a rfc-822 compliant format, separated by blank lines.
Here is an example:
<programlisting>
Template: hostname
Type: string
Default: debian
Description: unqualified hostname for this computer
This is the name by which this computer will be known on the network. It
has to be a unique name in your domain.
Template: domain
Type: string
Description: domain for this computer
This is the domain your computer is a member of. Typically it is
something like "mycompany.com" or "myuniversity.edu".</programlisting>
</para>
<para>
For localization, the description field (and also the choices
field of a select or multiselect type question, and the
default field of a string or password type question) can be
supplemented with versions for other languages. These are
named <emphasis>Description-ll</emphasis>,
<emphasis>Description-ll_LL</emphasis>,
<emphasis>Description-ll_LL.encoding</emphasis> and so on.
</para>
</sect2>
</sect1>
<sect1>
<title>
Configuration frontends
</title>
<para>
Of course applications can use the database and meta-database directly.
But there should be a simple system to interact with the user that is
simple and modular enough to be used with systems ranging from
shell-scripts to Fortran programs. To do this we define a general
frontend that can be driven using the simplest and most common form of
communication: stdin and stdout.
</para>
<para>
Using this simple form of communication gives us a great advantage: it
becomes easy to change the frontend. That means the user can switch
between a console, a graphical or even a web-interface at will.
</para>
<para>
Besides being able to switch between types of frontends there is
another important aspect of a good user interface: user friendliness.
We have to account for the fact that some users know more then others
and change the information we show or ask from the user. We do this by
giving everything a priority and giving the user control over what
kind of questions he wants to see. Experts can request to see
everything, while novices get the option of only seeing only important
questions. Finally there is an option to simply skip all questions, so
it becomes possible to do automatic configuration using default values
or values that are downloaded into the database from a remote
location. This makes it simple for example to install and manage
clusters or lab rooms or do installs for dummies.
</para>
</sect1>
<sect1>
<title>
Communication with the frontend
</title>
<para>
This communication between the frontend and the application should be
as simple as possible. Since most IO implementations default to
line-buffered IO, so we use a simple language where each command is
exactly one line.
</para>
<para>
After sending each command to stdout, the client
should read one line from stdin. This is the response to the command,
and it will be in the form of a number followed by whitespace and an
optional string of text. The number is the status code, while the
text provides additional information.
&statuscodes_table;
</para>
<para>
Here are the currently supported commands.
</para>
&command_list;
</sect1>
<sect1>
<title>
Debian install-time configuration
</title>
<para>
Debian has had an excellent packaging system for a long time now. There is
one thing missing though: a system to handle the configuration of
packages so we don't have to stop the installation every time a package
needs some data from the user or wants to show some information.
</para>
<para>
We want to make a package which does not break older dpkg's, and we
want to be able to get the configuration information before the package
is unpacked. To do this we add two new files, config and templates, to
the control.tar.gz of a .deb package. Since all installation-software
(apt, dselect, dpkg) download the package before installing it, we can
extract this before the package is unpacked.
</para>
<para>
The templates file lists the templates for variables that this package
uses. This is done using the format as used in the example in the
section on templates.
</para>
<para>
The config-file contains a new element, which I call the
configmodule. This is a program that will determine the
configuration before the package is unpacked. This means it is
usually run <emphasis>before</emphasis> the preinst, and before
the package is unpacked!
<note>
<simpara>Please see debconf-devel(7) for details.</simpara>
</note>
This is done to make sure that we can
use the desired configuration in the preinst if necessary.
</para>
<para>
How does the configmodule get its information? The configmodule
needs a way to retrieve information from the configuration space, ask
the user for information if necessary, etc. But we don't want to
implement a user interface for each package. To solve this we use a
separate frontend as specified in the section on frontends.
</para>
</sect1>
</article>
|