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>Protocol version 2</subtitle>
  14     <releaseinfo>Revision 7.0</releaseinfo>
  15     <author>
  16       <firstname>
  17         Wichert
  18       </firstname>
  19       <surname>
  20         Akkerman
  21       </surname>
  22       <affiliation>
  23         <orgname>
  24           The Debian Project
  25         </orgname>
  26         <address><email>wakkerma@debian.org</email></address>
  27       </affiliation>
  28     </author>
  29     <author>
  30       <firstname>
  31         Joey
  32       </firstname>
  33       <surname>
  34         Hess
  35       </surname>
  36       <affiliation>
  37         <orgname>
  38           The Debian Project
  39         </orgname>
  40         <address><email>joeyh@debian.org</email></address>
  41       </affiliation>
  42     </author>
  43     <copyright>
  44       <year>
  45         1998
  46       </year>
  47       <year>
  48         1999
  49       </year>
  50       <year>
  51         2000
  52       </year>
  53       <holder>
  54         Wichert Akkerman and Joey Hess
  55       </holder>
  56     </copyright>
  57     <legalnotice>
  58       <para>
  59         This text is copyright by the authors under the terms of the
  60         BSD license, sans advertising clause.
  61       </para>
  62     </legalnotice>
  63   </articleinfo>
  64
  65   <sect1>
  66     <title>
  67       Introduction
  68     </title>
  69     <para>
  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.
  76     </para>
  77   </sect1>
  78
  79   <sect1>
  80     <title>
  81       Configuration Data
  82     </title>
  83     <sect2>
  84       <title>
  85         The configuration space
  86       </title>
  87       <para>
  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>
 104         does not exist.
 105       </para>
 106       <para>
 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.
 110       </para>
 111     </sect2>
 112   </sect1>
 113
 114   <sect1>
 115     <title>
 116       Templates
 117     </title>
 118     <para>
 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
 123       to be changed.
 124     </para>
 125     <para>
 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.
 133     </para>
 134     <sect2>
 135       <title>
 136         Template information
 137       </title>
 138       <para>
 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).
 144       </para>
 145       <para>
 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.
 148         &type_table;
 149       </para>
 150       <para>
 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
 154         extended one.
 155       </para>
 156       <para>
 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.
 165       </para>
 166       <para>
 167         This information is stored in a template file that consists of
 168         stanzas in a rfc-822 compliant format, separated by blank lines.
 169         Here is an example:
 170         <programlisting>
 171 Template: hostname
 172 Type: string
 173 Default: debian
 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.
 177
 178 Template: domain
 179 Type: string
 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".
 183         </programlisting>
 184       </para>
 185     </sect2>
 186   </sect1>
 187   <sect1>
 188     <title>
 189       Configuration frontends
 190     </title>
 191     <para>
 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.
 198     </para>
 199     <para>
 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.
 203     </para>
 204     <para>
 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.
 217     </para>
 218   </sect1>
 219   <sect1>
 220     <title>
 221       Communication with the frontend
 222     </title>
 223     <para>
 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
 227       exactly one line.
 228     </para>
 229     <para>
 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.
 235       &statuscodes_table;
 236     </para>
 237     <para>
 238       Here are the currently supported commands.
 239     </para>
 240     <itemizedlist>
 241         &command_list;
 242     </itemizedlist>
 243   </sect1>
 244   <sect1>
 245     <title>
 246       Debian install-time configuration
 247     </title>
 248     <para>
 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.
 253     </para>
 254     <para>
 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.
 261     </para>
 262     <para>
 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.
 266     </para>
 267     <para>
 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
 273       necessary.
 274     </para>
 275     <para>
 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.
 281     </para>
 282   </sect1>
 283 </article>