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.1</subtitle>
  14     <releaseinfo>Revision 7.1</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, underscore).
 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       <para>
 186         For localization, the description field (and also the choices
 187         field of a select or multiselect type question, and the
 188         default field of a string or password type question) can be
 189         supplemented with versions for other languages. These are
 190         named <emphasis>Description-ll</emphasis>,
 191         <emphasis>Description-ll_LL</emphasis>,
 192         <emphasis>Description-ll_LL.encoding</emphasis> and so on.
 193       </para>
 194     </sect2>
 195   </sect1>
 196   <sect1>
 197     <title>
 198       Configuration frontends
 199     </title>
 200     <para>
 201       Of course applications can use the database and meta-database directly.
 202       But there should be a simple system to interact with the user that is
 203       simple and modular enough to be used with systems ranging from
 204       shell-scripts to Fortran programs. To do this we define a general
 205       frontend that can be driven using the simplest and most common form of
 206       communication: stdin and stdout.
 207     </para>
 208     <para>
 209       Using this simple form of communication gives us a great advantage: it
 210       becomes easy to change the frontend. That means the user can switch
 211       between a console, a graphical or even a web-interface at will.
 212     </para>
 213     <para>
 214       Besides being able to switch between types of frontends there is
 215       another important aspect of a good user interface: user friendliness.
 216       We have to account for the fact that some users know more then others
 217       and change the information we show or ask from the user. We do this by
 218       giving everything a priority and giving the user control over what
 219       kind of questions he wants to see. Experts can request to see
 220       everything, while novices get the option of only seeing only important
 221       questions. Finally there is an option to simply skip all questions, so
 222       it becomes possible to do automatic configuration using default values
 223       or values that are downloaded into the database from a remote
 224       location. This makes it simple for example to install and manage
 225       clusters or lab rooms or do installs for dummies.
 226     </para>
 227   </sect1>
 228   <sect1>
 229     <title>
 230       Communication with the frontend
 231     </title>
 232     <para>
 233       This communication between the frontend and the application should be
 234       as simple as possible. Since most IO implementations default to
 235       line-buffered IO, so we use a simple language where each command is
 236       exactly one line.
 237     </para>
 238     <para>
 239       After sending each command to stdout, the client
 240       should read one line from stdin. This is the response to the command,
 241       and it will be in the form of a number followed by whitespace and an
 242       optional string of text. The number is the status code, while the
 243       text provides additional information.
 244       &statuscodes_table;
 245     </para>
 246     <para>
 247       Here are the currently supported commands.
 248     </para>
 249     <itemizedlist>
 250         &command_list;
 251     </itemizedlist>
 252   </sect1>
 253   <sect1>
 254     <title>
 255       Debian install-time configuration
 256     </title>
 257     <para>
 258       Debian has had an excellent packaging system for a long time now. There is
 259       one thing missing though: a system to handle the configuration of
 260       packages so we don't have to stop the installation every time a package
 261       needs some data from the user or wants to show some information.
 262     </para>
 263     <para>
 264       We want to make a package which does not break older dpkg's, and we
 265       want to be able to get the configuration information before the package
 266       is unpacked. To do this we add two new files, config and templates, to
 267       the control.tar.gz of a .deb package. Since all installation-software
 268       (apt, dselect, dpkg) download the package before installing it, we can
 269       extract this before the package is unpacked.
 270     </para>
 271     <para>
 272       The templates file lists the templates for variables that this package
 273       uses. This is done using the format as used in the example in the
 274       section on templates.
 275     </para>
 276     <para>
 277       The config-file contains a new element, which I call the
 278       configmodule.  This is a program that will determine the
 279       configuration before the package is unpacked.  This means it is
 280       usually run <emphasis>before</emphasis> the preinst, and before
 281       the package is unpacked!
 282       <note>
 283         <simpara>Please see debconf-devel(7) for details.</simpara>
 284       </note>
 285       This is done to make sure that we can
 286       use the desired configuration in the preinst if necessary.
 287     </para>
 288     <para>
 289       How does the configmodule get its information?  The configmodule
 290       needs a way to retrieve information from the configuration space, ask
 291       the user for information if necessary, etc. But we don't want to
 292       implement a user interface for each package. To solve this we use a
 293       separate frontend as specified in the section on frontends.
 294     </para>
 295   </sect1>
 296 </article>