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