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