debconf_spec/debconf_specification.xml

   1 <?xml version="1.0"?>
   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 ]>
   9 <article>
  10
  11   <articleinfo>
  12     <title>Configuration management</title>
  13     <subtitle>revision 7.0</subtitle>
  14     <author>
  15       <firstname>
  16         Wichert
  17       </firstname>
  18       <surname>
  19         Akkerman
  20       </surname>
  21       <affiliation>
  22         <orgname>
  23           The Debian Project
  24         </orgname>
  25         <address><email>wakkerma@debian.org</email></address>
  26       </affiliation>
  27     </author>
  28     <author>
  29       <firstname>
  30         Joey
  31       </firstname>
  32       <surname>
  33         Hess
  34       </surname>
  35       <affiliation>
  36         <orgname>
  37           The Debian Project
  38         </orgname>
  39         <address><email>joeyh@debian.org</email></address>
  40       </affiliation>
  41     </author>
  42     <copyright>
  43       <year>
  44         1998
  45       </year>
  46       <year>
  47         1999
  48       </year>
  49       <year>
  50         2000
  51       </year>
  52       <holder>
  53         Wichert Akkerman and Joey Hess
  54       </holder>
  55     </copyright>
  56     <legalnotice>
  57       <para>
  58         This text is copyright by the authors under the terms of the
  59         BSD license, sans advertising clause.
  60       </para>
  61     </legalnotice>
  62   </articleinfo>
  63
  64   <sect1>
  65     <title>
  66       Introduction
  67     </title>
  68     <para>
  69       Configuration management is quickly becoming a very important issue.
  70       Having programs which do cool stuff is great, but we need to store
  71       their configuration as well. We see more and more different
  72       configuration systems being introduced all the time, which is not very
  73       practical. This text introduces a general configuration management
  74       system which flexible enough to be used for all kinds of applications.
  75     </para>
  76   </sect1>
  77
  78   <sect1>
  79     <title>
  80       Configuration Data
  81     </title>
  82     <sect2>
  83       <title>
  84         The configuration space
  85       </title>
  86       <para>
  87         All configuration information is stored in what I call the
  88         configuration space. This is a database with a special design
  89         which resembles the method we look at configuration information.
  90         This is done by defining a hierarchy of information. Each package
  91         receives its own space in the hierarchy.  Each package is free to
  92         use a flat space, or divide its space further into
  93         sub-hierarchies.  If multiple packages share a common purpose they
  94         may use a shared toplevel hierarchy, preferably with the same name
  95         as a shared (virtual) package name (for example, both
  96         <application>mutt</application> and <application>elm</application>
  97         can use <literal>mail-reader</literal>,
  98         <application>strn</application> and <application>nn</application>
  99         could use <literal>news-reader</literal>).  This
 100         shared tree can also be used as a default, ie a variable
 101         <literal>news-reader/nntpserver</literal> can be used by
 102         <application>strn</application> if <literal>strn/nntpserver</literal>
 103         does not exist.
 104       </para>
 105       <para>
 106         Each variable in the configuration space has some information
 107         associated with it. Most importantly, it has a value. It also may
 108         have a set of flags and a set of substitution data.
 109       </para>
 110     </sect2>
 111   </sect1>
 112
 113   <sect1>
 114     <title>
 115       Templates
 116     </title>
 117     <para>
 118       Each variable in the configuration space is associated with some
 119       meta-data. The minimum meta-data associated with a variable is:
 120       long and short description, type, and default value. The meta-data
 121       is essentially static; the protocol described below does not allow it
 122       to be changed.
 123     </para>
 124     <para>
 125       The meta-data exists in a space with similar naming
 126       properties to the configuration space described above, and typically
 127       one variable in the configuration space will have associated with it
 128       metadata with the same name in the meta-data space. However, this need
 129       not be the case; many different variables can all be associated with
 130       the same meta-data. In effect the meta-data serves as a template
 131       for the configuration variable.
 132     </para>
 133     <sect2>
 134       <title>
 135         Template information
 136       </title>
 137       <para>
 138         So, what do we need to store in a variable template? Of course we
 139         need a name to identify the template. Template names are made up of
 140         components separated by the character `/' (slash).
 141         Each component is limited to alphanumerics and `+' `-' `.'
 142         (plus, minus, full stop).
 143       </para>
 144       <para>
 145         A type is also needed so data can be verified. Here is a table
 146         of common types; implementations are free to make up more.
 147         &type_table;
 148       </para>
 149       <para>
 150         Of course a default value is useful as well, and
 151         finally we need a description of the variable. We actually use two
 152         descriptions: a short one (limited to 50 characters or so) and an
 153         extended one.
 154       </para>
 155       <para>
 156         The extended description may be word-wrapped by the
 157         FrontEnd. To make separate paragraphs in it, use <literal>.</literal>
 158         on a line by itself to separate them. Text in the extended
 159         description that is prefaced by additional whitespace will not be
 160         wordwrapped. Both the description and extended
 161         description may have substitutions embedded in them. Ie,
 162         <literal>${foo}</literal>. These will be expanded when the
 163         descriptions are displayed.
 164       </para>
 165       <para>
 166         This information is stored in a template file that consists of
 167         stanzas in a rfc-822 compliant format, separated by blank lines.
 168         Here is an example:
 169         <programlisting>
 170 Template: hostname
 171 Type: string
 172 Default: debian
 173 Description: unqualified hostname for this computer
 174  This is the name by which this computer will be known on the network. It
 175  has to be a unique name in your domain.
 176
 177 Template: domain
 178 Type: string
 179 Description: domain for this computer
 180   This is the domain your computer is a member of. Typically it is
 181   something like "mycompany.com" or "myuniversity.edu".
 182         </programlisting>
 183       </para>
 184     </sect2>
 185   </sect1>
 186   <sect1>
 187     <title>
 188       Configuration frontends
 189     </title>
 190     <para>
 191       Of course applications can use the database and meta-database directly.
 192       But there should be a simple system to interact with the user that is
 193       simple and modular enough to be used with systems ranging from
 194       shell-scripts to Fortran programs. To do this we define a general
 195       frontend that can be driven using the simplest and most common form of
 196       communication: stdin and stdout.
 197     </para>
 198     <para>
 199       Using this simple form of communication gives us a great advantage: it
 200       becomes easy to change the frontend. That means the user can switch
 201       between a console, a graphical or even a web-interface at will.
 202     </para>
 203     <para>
 204       Besides being able to switch between types of frontends there is
 205       another important aspect of a good user interface: user friendliness.
 206       We have to account for the fact that some users know more then others
 207       and change the information we show or ask from the user. We do this by
 208       giving everything a priority and giving the user control over what
 209       kind of questions he wants to see. Experts can request to see
 210       everything, while novices get the option of only seeing only important
 211       questions. Finally there is an option to simply skip all questions, so
 212       it becomes possible to do automatic configuration using default values
 213       or values that are downloaded into the database from a remote
 214       location. This makes it simple for example to install and manage
 215       clusters or lab rooms or do installs for dummies.
 216     </para>
 217   </sect1>
 218   <sect1>
 219     <title>
 220       Communication with the frontend
 221     </title>
 222     <para>
 223       This communication between the frontend and the application should be
 224       as simple as possible. Since most IO implementations default to
 225       line-buffered IO, so we use a simple language where each command is
 226       exactly one line.
 227     </para>
 228     <para>
 229       After sending each command to stdout, the client
 230       should read one line from stdin. This is the response to the command,
 231       and it will be in the form of a number followed by whitespace and an
 232       optional string of text. The number is the status code, while the
 233       text provides additional information.
 234       &statuscodes_table;
 235     </para>
 236     <para>
 237       Here are the currently supported commands.
 238     </para>
 239     <itemizedlist>
 240         &command_list;
 241     </itemizedlist>
 242   </sect1>
 243   <sect1>
 244     <title>
 245       Debian install-time configuration
 246     </title>
 247     <para>
 248       Debian has had an excellent packaging system for a long time now. There is
 249       one thing missing though: a system to handle the configuration of
 250       packages so we don't have to stop the installation every time a package
 251       needs some data from the user or wants to show some information.
 252     </para>
 253     <para>
 254       We want to make a package which does not break older dpkg's, and we
 255       want to be able to get the configuration information before the package
 256       is unpacked. To do this we add two new files, config and templates, to
 257       the control.tar.gz of a .deb package. Since all installation-software
 258       (apt, dselect, dpkg) download the package before installing it, we can
 259       extract this before the package is unpacked.
 260     </para>
 261     <para>
 262       The templates file lists the templates for variables that this package
 263       uses. This is done using the format as used in the example in the
 264       section on templates.
 265     </para>
 266     <para>
 267       The config-file contains a new element, which I call the configmodule.
 268       This is a program that will determine the configuration before the
 269       package is unpacked.  This means it is run <emphasis>before</emphasis>
 270       the preinst, and before the package is unpacked! This is done to make
 271       sure that we can use the desired configuration in the preinst if
 272       necessary.
 273     </para>
 274     <para>
 275       How does the configmodule get its information?  The configmodule
 276       needs a way to retrieve information from the configuration space, ask
 277       the user for information if necessary, etc. But we don't want to
 278       implement a user interface for each package. To solve this we use a
 279       separate frontend as specified in the section on frontends.
 280     </para>
 281   </sect1>
 282 </article>